Documentation

Construisez avec l’API mysms

Une API REST, des webhooks signés et des clés de test gratuites. Tout ce qu’il faut pour envoyer votre premier SMS en cinq minutes, puis passer en production sereinement.

Obtenir une clé API Référence API
api.mysms.ma REST + JSON Webhooks signés HMAC Clés de test gratuites SDK PHP · Node.js · Python

Démarrage rapide

Premier SMS en 3 étapes

Pas de SDK obligatoire : une requête HTTPS suffit. Les SDK viennent ensuite, quand vous voulez les relances et les types.

  1. Créez une clé de test

    Compte gratuit, 100 SMS de test offerts, sans carte bancaire. Copiez votre clé sk_test_ depuis Développeurs › Clés API.

    sk_test_••••4f1c

  2. Envoyez votre premier SMS

    Une requête HTTPS suffit : POST /v1/messages avec le destinataire, l’expéditeur et le texte.

    POST /v1/messages

  3. Suivez la livraison

    Déclarez une URL de webhook : chaque changement de statut y arrive, signé, en temps réel.

    message.delivered
zsh — premier-envoi
export MYSMS_KEY=sk_test_••••••••4f1ccurl https://api.mysms.ma/v1/messages \    -H "Authorization: Bearer $MYSMS_KEY" \    -d to=+212612345678 -d from=MyShop \    -d body="Bienvenue chez MyShop !"{ "id": "msg_9fK2", "status": "queued", "segments": 1 }← POST /hooks/sms  message.sent       09:41:02← POST /hooks/sms  message.delivered  09:41:03  ✓

Authentification

Trois types de clés,
chacune à sa place

Le préfixe dit tout : vous savez en un coup d’œil ce qu’une clé peut faire, et vos outils de détection de secrets aussi.

Production

Secrète

Envoie de vrais SMS et débite votre solde. À garder côté serveur, dans une variable d’environnement.

  • Oui :Envoyer des SMS
  • Oui :Lire statuts et statistiques
  • Oui :Débiter le solde
  • Oui :Déclencher les webhooks

Test

Gratuite

Mêmes requêtes et mêmes réponses qu’en production, mais rien n’est envoyé ni facturé. Pour le développement et la CI.

  • Oui :Envoyer des SMS
  • Oui :Lire statuts et statistiques
  • Non :Débiter le solde
  • Oui :Déclencher les webhooks

Lecture seule

Restreinte

Statuts, statistiques et solde, sans aucun droit d’envoi. Idéale pour un tableau de bord interne ou un assistant IA.

  • Non :Envoyer des SMS
  • Oui :Lire statuts et statistiques
  • Non :Débiter le solde
  • Non :Déclencher les webhooks

Concepts

Cinq notions pour tout comprendre

Le vocabulaire du SMS professionnel, expliqué une fois pour toutes.

Messages

Un SMS envoyé (ou reçu) est une ressource avec un id, un statut et un prix. Vous le créez en un appel, il vit ensuite sa vie.

POST /v1/messages

Accusé de réception (DLR)

L’opérateur confirme que le message est arrivé sur le téléphone. C’est ce qui fait passer le statut de sent à delivered.

Cycle de vie

Webhooks

Nous appelons votre URL à chaque événement, avec une signature HMAC à vérifier. Plus besoin d’interroger l’API en boucle.

Événements et signature

Sender ID

Le nom affiché comme expéditeur, jusqu’à 11 caractères. Il est validé auprès des opérateurs avant le premier envoi.

Demander un Sender ID

Segments

Un SMS long est découpé en segments, facturés chacun comme un SMS. L’encodage décide de leur taille : 160 ou 70 caractères.

Calculer mes segments

Encodage

Un accent peut doubler
le prix d’un SMS

Un seul caractère hors de l’alphabet GSM-7 fait passer tout le message en UCS-2 : de 160 à 70 caractères par segment. Essayez.

EncodageGSM-7
Caractères112
Segments1
Restant48

Tous les caractères appartiennent à l’alphabet GSM-7.

Les règles

Encodage1 segmentPar segment si long
GSM-7Latin, é è à ù, chiffres160153
UCS-2Arabe, ê ç î ô, emoji7067
  • ^ { } [ ] ~ | € \ sont en GSM-7 mais comptent pour deux caractères.
  • Un emoji compte pour deux caractères en UCS-2.
  • L’API renvoie encoding et segments pour chaque message, et le prix correspondant.
  • Astuce : remplacer « ê » par « e » dans un message promotionnel peut diviser son coût par deux.

Webhooks

Le cycle de vie d’un message

Chaque transition déclenche un événement signé sur votre URL. Vous savez toujours où en est chaque SMS.

  • message.queuedLa requête est validée, le coût réservé. Réponse immédiate 201.
  • message.sentLe message est remis au réseau de l’opérateur du destinataire.
  • message.deliveredL’opérateur confirme la livraison : c’est l’accusé de réception (DLR).
  • message.failedÉchec définitif avec un error_code.

Erreurs

Des erreurs qui disent quoi faire

Un code stable pour votre logique, un message lisible pour vos journaux. Filtrez par code ou par statut HTTP.

11 codes
CodeHTTPSignificationQue faire
invalid_api_key401Clé absente, mal formée ou révoquée.Vérifiez l’en-tête Authorization: Bearer et l’environnement de la clé.
permission_denied403La clé n’a pas ce droit (clé en lecture seule).Utilisez une clé secrète pour les envois.
insufficient_balance402Le solde ne couvre pas le message.Rechargez par virement bancaire depuis le tableau de bord.
invalid_phone_number422Le numéro n’est pas au format E.164 ou n’existe pas.Normalisez en +212… avant l’envoi.
sender_not_approved422Le Sender ID n’est pas encore validé.Attendez sender.updated ou utilisez un Sender ID approuvé.
body_too_long422Le message dépasse 10 segments.Raccourcissez le texte ou envoyez un lien.
idempotency_conflict409Clé d’idempotence déjà utilisée avec un autre corps.Générez une nouvelle clé pour chaque nouvel envoi.
resource_missing404L’identifiant demandé n’existe pas sur ce compte.Vérifiez l’id et la clé (test ou production).
verification_expired410Le code Verify a expiré ou a été bloqué.Relancez POST /v1/verify.
rate_limited429Trop de requêtes en peu de temps.Attendez Retry-After secondes, puis réessayez avec un délai croissant.
internal_error500Erreur inattendue de notre côté.Réessayez avec la même Idempotency-Key ; aucun double envoi.

Codes d’échec de livraison error_code dans message.failed

unreachable
Téléphone éteint ou hors couverture pendant toute la durée de validité.
invalid_number
Numéro non attribué ou résilié chez l’opérateur.
blocked
Le destinataire a répondu STOP à cet expéditeur.
operator_rejected
Message refusé par l’opérateur (contenu ou Sender ID).
expired
Non livré avant l’expiration (48 h par défaut).

Limites de débit

Des limites généreuses, annoncées

Chaque réponse indique où vous en êtes. Au-delà, l’API répond 429 avec un délai d’attente : jamais de message perdu en silence.

Envoi 50req/s

POST /v1/messages, par compte. Pour les gros volumes, utilisez les campagnes : elles sont lissées pour vous.

Lecture 100req/s

Statuts, listes et solde. Préférez les webhooks au polling : ils ne comptent pas dans la limite.

Verify 5codes/h

Par numéro de destination, pour bloquer les abus (SMS pumping). Ajustable sur demande.

En-têtes de réponse
X-RateLimit-Limit: 50X-RateLimit-Remaining: 12X-RateLimit-Reset: 1792569601# Après dépassement :HTTP/1.1 429 Too Many RequestsRetry-After: 1

Valeurs par défaut de l’aperçu, susceptibles d’évoluer. Besoin de plus ? Parlez-nous de votre volume.

Mode test

Testez tout, n’envoyez rien

Une clé sk_test_ accepte exactement les mêmes requêtes qu’en production, déclenche vos webhooks, mais n’envoie aucun SMS et ne débite rien.

Numéros magiques

Avec une clé de test, ces numéros produisent un résultat prévisible : parfait pour vos tests d’intégration et votre CI.

  • +212 600 000 001deliveredLivré après environ 1 seconde.
  • +212 600 000 002failedÉchec avec error_code unreachable.
  • +212 600 000 003sentReste en sent, jamais confirmé.
  • +212 600 000 004422Rejeté : invalid_phone_number.

Tout autre numéro valide passe par queued, sent puis delivered.

Verify en mode test
curl https://api.mysms.ma/v1/verify \  -H "Authorization: Bearer sk_test_••••••••" \  -d to=+212600000001# En mode test, le code est renvoyé pour vos tests automatisés :{ "id": "vrf_3Hq8", "status": "pending", "test_code": "123456" }

Démarrer

Référence

Outils

Une question d’intégration ? Écrivez-nous à contact@mysms.ma.

Commencez à envoyer en 5 minutes

Créez un compte gratuit, recevez 100 messages de test et constatez la rapidité de la livraison locale. Sans carte bancaire.

Commencer gratuitement Voir la documentation