Référence API

Documentation Technique

Intégrez EnvoiSMS.ma en moins de 15 minutes avec nos SDK PHP, Node.js et Python. Conçu pour les développeurs.

openapi.json openapi.yaml Postman Collection
🧪 Mode Sandbox (Test sans frais)Clé API active :
env_test_demo_2026
Les requêtes de la console interactive et du Swagger UI sont exécutées en direct sur https://api.envoisms.ma.

Start here

Tout pour démarrer avant la première requête.

EnvoiSMS.ma est une infrastructure de messagerie programmable conçue pour le Maroc. Nos routes directes avec IAM, Inwi et Orange garantissent une latence minimale.

URL de basehttps://api.envoisms.ma
Version API/v1 (Stable)
Format des donnéesapplication/json; charset=utf-8
AuthentificationAuthorization: Bearer smr_xxx
Limite par défaut100 requêtes / minute
Format numéroE.164 (ex: +212612345678)
Canaux actifsSMS direct opérateur, WhatsApp Business API
LocalisationHébergée au Maroc — edge Cloudflare 🇲🇦
01

Générez votre clé API "smr_..." depuis votre Console EnvoiSMS.ma.

02

Utilisez l'authentification Bearer dans vos headers HTTP pour chaque requête.

03

Testez votre intégration via des clés Sandbox (env_test_...) sur l'URL live pour valider vos appels sans consommer de crédit réel.

04

Intégrez le WhatsApp Business API pour diviser vos coûts OTP par 10.

05

Configurez un Webhook signé pour recevoir les accusés de réception en temps réel.

06

Suivez votre consommation et vos factures MAD directement sur votre Dashboard.

Envoyer votre premier message
// config/services.php
'envoisms' => [
    'key' => env('ENVOISMS_API_KEY'),
],

// Usage
Http::withToken(config('services.envoisms.key'))
    ->post('https://api.envoisms.ma/v1/messages', [
        'to' => '+212612345678',
        'message' => 'Votre commande est en cours de livraison 🚚',
        'from' => 'MaBoutique'
    ]);
OpenAPI Spec

Authentification

Clés Bearer, headers et restrictions de sécurité.

Chaque endpoint /v1 nécessite une clé API valide transmise dans le header Authorization sous forme de jeton Bearer. Les clés de test et de production peuvent être générées ou révoquées depuis votre console.

Authorization

Authorization: Bearer smr_xxx

Headers de limite

X-RateLimit-Limit et X-RateLimit-Remaining retournés à chaque appel.

Allowlists IP

Les requêtes provenant d'adresses IP non configurées retournent un statut 401.

CORS supporté

JSON, Authorization, X-EnvoiSMS.ma-Signature, et X-EnvoiSMS.ma-Version sont supportés.

Exemple d'en-têtes HTTP
POST /v1/messages HTTP/1.1
Host: api.envoisms.ma
Authorization: Bearer smr_xxxxxxxx
Content-Type: application/json
Accept: application/json

Open Source

SDKs officiels & Librairies clientes

Incorporez l'API EnvoiSMS en quelques lignes de code grâce à nos SDKs open-source officiels.

NPM PackageTypeScript & JavaScript
Node.js / TypeScript
npm install envoisms
GitHub Repository
Composer PackagePHP 8.0+
PHP Client
composer require envoisms/envoisms-php
GitHub Repository
PyPI PackagePython 3.8+
Python Client
pip install envoisms
GitHub Repository
Notification ChannelLaravel 9 - 11
Laravel OTP Package
composer require envoisms/laravel-otp
GitHub Repository
POST/v1/messages

Envoyer un message

Envoie un SMS ou un message WhatsApp Business à un destinataire unique.

Request Body
tostringRequis
Numéro de téléphone au format E.164 (+212...).
messagestringRequis
Contenu textuel (max 1600 caractères). Également accepté sous le nom "body".
fromstringOptionnel
Sender ID personnalisé (ex: NOM_MARQUE). Par défaut "EnvoiSMS".
channelstringOptionnel
"sms" ou "whatsapp". Par défaut "sms".
cascadebooleanOptionnel
Si activé, tente de délivrer par WhatsApp et bascule automatiquement sur SMS en cas d'échec.
metadataobjectOptionnel
Clés-valeurs personnalisées stockées avec le message et transmises dans les webhooks (elles ne sont pas renvoyées par les endpoints GET /v1/messages). Une clé a un sens pour la plateforme : purpose: "otp" signale un code à usage unique que vous générez vous-même et active la relivraison automatique (voir notes).
buttonsarrayOptionnel
Tableau d'objets boutons WhatsApp interactifs (max 3, type "copy" | "url" | "call").
Notes
  • Vous envoyez des codes OTP ? Deux approches. /v1/verify/send gère tout le cycle (génération, livraison, validation, expiration) et reste la voie recommandée. Si vous générez vos propres codes et les envoyez ici, ajoutez metadata: {"purpose": "otp"} : en cas d'échec de livraison confirmé par le réseau sur un numéro marocain alors que le code est encore frais (moins de 10 minutes), la plateforme le renvoie automatiquement une fois par une route SMS alternative — même identifiant de message, aucun coût supplémentaire. Sans ce tag, le message est traité comme un SMS ordinaire.
  • Les sauts de ligne (\n) sont pleinement pris en charge sur tous les canaux et s'affichent correctement chez le destinataire.
  • Le formatage de texte enrichi (gras, italique, etc.) n'est pas supporté par le canal SMS (texte brut uniquement).
  • Le canal WhatsApp prend en charge le formatage de texte avec la syntaxe standard (*gras*, _italique_, ~barré~).
POSThttps://api.envoisms.ma/v1/messages
curl -X POST "https://api.envoisms.ma/v1/messages" \
  -H "Authorization: Bearer smr_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+212612345678",
    "message": "Votre code de validation est 849204",
    "from": "MaBoutique",
    "channel": "whatsapp"
  }'
{
  "id": "msg_8f2d...",
  "to": "+212612345678",
  "channel": "whatsapp",
  "cascade": false,
  "status": "queued",
  "cost": {
    "eur": 0.03,
    "mad": 0.33
  },
  "segments": 1,
  "created_at": "2026-05-15T10:30:00Z"
}
POST/v1/messages/bulk

Envoi groupé (Bulk)

Envoie jusqu'à 10 000 messages en un seul appel API avec des destinataires ou des contenus uniques.

Request Body
messagesarrayRequis
Tableau d'objets contenant "to", "message" (ou "body"), et un objet facultatif "metadata".
fromstringOptionnel
Sender ID global pour tout le lot.
channelstringOptionnel
Canal global ("sms" ou "whatsapp"). Par défaut "sms".
Notes
  • Les sauts de ligne (\n) sont pleinement pris en charge dans les corps des messages groupés.
  • Le formatage de texte enrichi (gras, italique, etc.) n'est pas supporté par le canal SMS (texte brut uniquement).
  • Le canal WhatsApp prend en charge le formatage de texte avec la syntaxe standard (*gras*, _italique_, ~barré~).
POSThttps://api.envoisms.ma/v1/messages/bulk
curl -X POST "https://api.envoisms.ma/v1/messages/bulk" \
  -H "Authorization: Bearer smr_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "to": "+212611111111",
        "message": "Hello Client 1"
      },
      {
        "to": "+212622222222",
        "message": "Hello Client 2"
      }
    ],
    "from": "ENVOISMS",
    "channel": "sms"
  }'
{
  "batch_id": "batch_9a3c...",
  "total": 2,
  "channel": "sms",
  "estimated_cost": {
    "eur": 0.056,
    "mad": 0.62
  },
  "messages": [
    {
      "id": "msg_1a2b...",
      "to": "+212611111111",
      "status": "queued"
    },
    {
      "id": "msg_3c4d...",
      "to": "+212622222222",
      "status": "queued"
    }
  ]
}
GET/v1/messages

Lister les messages

Récupère une liste paginée de tous les messages envoyés depuis le compte.

Query Parameters
limitintegerOptionnel
Nombre de résultats à retourner (1-200, défaut: 50).
offsetintegerOptionnel
Nombre de résultats à ignorer pour la pagination (défaut: 0).
statusstringOptionnel
Filtrer par statut (queued, sent, delivered, failed, undeliverable, unconfirmed).
channelstringOptionnel
Filtrer par canal (sms, whatsapp).
from_datestringOptionnel
Filtrer par date de début (format ISO 8601).
to_datestringOptionnel
Filtrer par date de fin (format ISO 8601).
GEThttps://api.envoisms.ma/v1/messages
curl -X GET "https://api.envoisms.ma/v1/messages?limit=50&offset=0" \
  -H "Authorization: Bearer smr_xxx"
{
  "data": [
    {
      "id": "msg_8f2d...",
      "to": "+212612345678",
      "channel": "whatsapp",
      "body": "Votre code de validation est 849204",
      "sender_id": "MaBanque",
      "status": "delivered",
      "cost_mad": 0.13,
      "created_at": "2026-05-15T10:30:00Z"
    }
  ],
  "limit": 50,
  "offset": 0,
  "total": 1
}
GET/v1/messages/:id

Statut du message

Consulte les détails et l'état de livraison en temps réel d'un message spécifique.

Notes
  • Statuts possibles : queued, sent, delivered, failed, undeliverable, unconfirmed. "unconfirmed" signifie que l'opérateur n'a jamais confirmé ni infirmé la livraison — un accusé arrivant plus tard peut encore le remplacer.
  • Le champ metadata fourni à l'envoi n'est pas renvoyé ici ; il est transmis dans les webhooks.
GEThttps://api.envoisms.ma/v1/messages/:id
curl -X GET "https://api.envoisms.ma/v1/messages/:id" \
  -H "Authorization: Bearer smr_xxx"
{
  "id": "msg_8f2d...",
  "campaign_id": null,
  "to": "+212612345678",
  "channel": "sms",
  "body": "Votre code de validation est 849204",
  "sender_id": "MaBanque",
  "unicode": 0,
  "segments": 1,
  "status": "delivered",
  "error_code": null,
  "error_message": null,
  "cost_eur": 0.0436,
  "cost_mad": 0.48,
  "scheduled_at": null,
  "sent_at": "2026-05-15T10:30:02Z",
  "delivered_at": "2026-05-15T10:30:05Z",
  "failed_at": null,
  "operator": "Maroc Telecom",
  "sandbox": 0,
  "created_at": "2026-05-15T10:30:00Z"
}
GET/v1/templates

Lister les templates

Récupère tous les templates WhatsApp et SMS approuvés de votre compte.

GEThttps://api.envoisms.ma/v1/templates
curl -X GET "https://api.envoisms.ma/v1/templates" \
  -H "Authorization: Bearer smr_xxx"
{
  "data": [
    {
      "id": "tpl_1234...",
      "name": "otp_verification",
      "channel": "whatsapp",
      "body": "Votre code de validation est {{1}}",
      "status": "approved",
      "category": "otp",
      "created_at": "2026-05-15T10:30:00Z"
    }
  ],
  "total": 1
}
POST/v1/templates

Créer un template

Soumet un nouveau template pour approbation par les opérateurs ou WhatsApp.

Request Body
namestringRequis
Nom interne du template.
channelstringRequis
"sms" ou "whatsapp".
bodystringRequis
Contenu du message avec variables (ex: {{1}}).
categorystringOptionnel
Catégorie du template (ex: "otp", "marketing").
POSThttps://api.envoisms.ma/v1/templates
curl -X POST "https://api.envoisms.ma/v1/templates" \
  -H "Authorization: Bearer smr_xxx" \
  -H "Content-Type: application/json" \
  -d '{}'
{
  "id": "tpl_1234...",
  "name": "otp_verification",
  "status": "pending"
}
GET/v1/sender-ids

Lister les Sender IDs

Récupère la liste de vos Sender IDs avec leur statut d'approbation.

GEThttps://api.envoisms.ma/v1/sender-ids
curl -X GET "https://api.envoisms.ma/v1/sender-ids" \
  -H "Authorization: Bearer smr_xxx"
{
  "data": [
    {
      "id": "sid_9a8b...",
      "sender_id": "MABANQUE",
      "status": "approved",
      "requested_at": "2026-05-10T09:00:00Z"
    }
  ]
}
POST/v1/sender-ids

Demander un Sender ID

Soumet un nouveau Sender ID pour approbation (requis pour le Maroc).

Request Body
sender_idstringRequis
Le nom d'expéditeur souhaité (max 11 caractères).
rc_urlstringOptionnel
Lien vers le Registre de Commerce pour vérification.
POSThttps://api.envoisms.ma/v1/sender-ids
curl -X POST "https://api.envoisms.ma/v1/sender-ids" \
  -H "Authorization: Bearer smr_xxx" \
  -H "Content-Type: application/json" \
  -d '{}'
{
  "id": "sid_9a8b...",
  "sender_id": "MABANQUE",
  "status": "pending"
}
POST/v1/verify/send

Générer un OTP

Envoie un code de vérification à usage unique. Deux modes au choix : "whatsapp" — vérification gérée, le plus simple et le moins cher (EnvoiSMS génère le code, le livre sur WhatsApp depuis un expéditeur vérifié, puis bascule automatiquement en SMS s'il n'est pas confirmé sous 60 s ; aucun code à stocker de votre côté) — ou "sms" — vous gardez le contrôle total du code, du modèle et de l'expéditeur. Dans les deux cas, la validation se fait avec le même appel /v1/verify/check. Vous souhaitez votre propre marque sur le repli SMS de la vérification gérée ? Disponible sur demande : contact@envoisms.ma.

Request Body
tostringRequis
Destinataire au format E.164.
channelstringOptionnel
"whatsapp" (vérification gérée : WhatsApp puis SMS automatique, code valide 5 min, 3 essais, facturée au tarif WhatsApp par vérification — le plus économique) ou "sms" (code généré pour vous, envoyé avec votre marque). Défaut: "sms".
app_idstringOptionnel
ID de l'application Verify configurée sur le tableau de bord (ex: vra_...). Applique automatiquement les paramètres de code, de délais et la cascade de canaux.
brandstringOptionnel
(Canal sms) Nom de la marque affiché (ex: MonApp, max 32 car.). Par défaut "EnvoiSMS".
code_lengthintegerOptionnel
(Canal sms) Longueur du code généré (de 4 à 8 chiffres, défaut: 6).
expiryintegerOptionnel
(Canal sms) Durée de validité du code en secondes (de 60 à 1800, défaut: 600).
cascadearrayOptionnel
(Canal sms) Liste ordonnée de canaux pour le basculement automatique en cascade (ex: ["whatsapp", "sms"]).
templatestringOptionnel
(Canal sms) Texte personnalisé avec les variables {{code}} et {{brand}}. En mode whatsapp, le message localisé (fr/en/es) est géré pour vous.
otp_button_textstringOptionnel
(Canal whatsapp) Libellé personnalisé pour le bouton de copie automatique WhatsApp (max 25 car.).
web_otp_domainstringOptionnel
(Optionnel, canal sms) Domaine web pour le remplissage automatique W3C WebOTP (ex: "https://monsite.ma"). Ajoute le tag @domaine #code à la fin du SMS.
app_hashstringOptionnel
(Optionnel, canal sms) Hash de signature d'application Android de 11 caractères (SMS Retriever API) pour détection automatique du code sur Android.
Notes
  • Autofill OTP (iOS & Android) : Pour permettre à vos utilisateurs de remplir automatiquement le code reçu en 1 clic au-dessus de leur clavier, ajoutez simplement autocomplete="one-time-code" et inputmode="numeric" sur le champ <input> de votre site.
POSThttps://api.envoisms.ma/v1/verify/send
curl -X POST "https://api.envoisms.ma/v1/verify/send" \
  -H "Authorization: Bearer smr_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+212612345678",
    "brand": "MonApp",
    "channel": "whatsapp",
    "code_length": 6,
    "expiry": 600
  }'
{
  "session_id": "vrf_7e2a...",
  "to": "+212612345678",
  "channel": "whatsapp",
  "resend_after_seconds": 30,
  "fallback_channels": ["sms"],
  "expires_at": "2026-05-15T10:35:00Z",
  "status": "sent",
  "cost": { "eur": 0.025, "mad": 0.33 }
}
POST/v1/verify/resend

Renvoyer un code OTP (Repli)

Renvoie le même code OTP actif via un canal alternatif (ex: SMS après WhatsApp) une fois le délai de temporisation (30 s) écoulé. Aucun nouveau code n'est généré, évitant les erreurs de saisie.

Request Body
session_idstringRequis
Identifiant de session reçu lors de l'appel initial à /v1/verify/send.
channelstringOptionnel
Canal de renvoi cible ("sms"). Par défaut : "sms".
POSThttps://api.envoisms.ma/v1/verify/resend
curl -X POST "https://api.envoisms.ma/v1/verify/resend" \
  -H "Authorization: Bearer smr_xxx" \
  -H "Content-Type: application/json" \
  -d '{}'
{
  "session_id": "vrf_7e2a...",
  "message_id": "msg_9f1a...",
  "to": "+212612345678",
  "channel": "sms",
  "status": "sent",
  "resend_after_seconds": 30,
  "expires_at": "2026-05-15T10:35:00Z"
}
POST/v1/verify/check

Vérifier un OTP

Valide le code fourni par l'utilisateur pour une session de vérification donnée.

Request Body
session_idstringRequis
ID de session reçu lors de l'appel à /v1/verify/send.
codestringRequis
Le code reçu et saisi par l'utilisateur.
POSThttps://api.envoisms.ma/v1/verify/check
curl -X POST "https://api.envoisms.ma/v1/verify/check" \
  -H "Authorization: Bearer smr_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "vrf_7e2a...",
    "code": "849204"
  }'
{
  "session_id": "vrf_7e2a...",
  "verified": true,
  "verified_at": "2026-05-15T10:35:12Z"
}
GET/v1/verify/:id

Statut de session OTP

Consulte l'état (validé ou expiré) d'une session de vérification spécifique.

GEThttps://api.envoisms.ma/v1/verify/:id
curl -X GET "https://api.envoisms.ma/v1/verify/:id" \
  -H "Authorization: Bearer smr_xxx"
{
  "id": "vrf_7e2a...",
  "to": "+212612345678",
  "channel": "whatsapp",
  "expires_at": "2026-05-15T10:40:00Z",
  "verified_at": "2026-05-15T10:35:12Z",
  "created_at": "2026-05-15T10:30:00Z"
}
POST/v1/verify/lookup

Validation de numéro

Valide le format, l'opérateur (carrier), le type de ligne et la localisation géographique d'un numéro de téléphone.

Request Body
numberstringRequis
Le numéro de téléphone à valider (format local ou international).
country_codestringOptionnel
Code pays ISO à 2 lettres (ex: MA, FR). Recommandé si le numéro est au format local.
POSThttps://api.envoisms.ma/v1/verify/lookup
curl -X POST "https://api.envoisms.ma/v1/verify/lookup" \
  -H "Authorization: Bearer smr_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "+212612345678",
    "country_code": "MA"
  }'
{
  "valid": true,
  "number": "212612345678",
  "local_format": "0612345678",
  "international_format": "+212612345678",
  "country_prefix": "212",
  "country_code": "MA",
  "country_name": "Morocco",
  "location": "Casablanca",
  "carrier": "Maroc Telecom (IAM)",
  "line_type": "mobile"
}
GET/v1/contacts

Lister les contacts

Récupère tous les contacts de votre compte, avec filtrage par mot-clé ou par liste.

Query Parameters
limitintegerOptionnel
Résultats par page (1-500, défaut: 100).
offsetintegerOptionnel
Décalage de pagination (défaut: 0).
qstringOptionnel
Recherche par nom, téléphone ou email.
list_idstringOptionnel
Filtrer uniquement les membres d'une liste de contacts spécifique.
GEThttps://api.envoisms.ma/v1/contacts
curl -X GET "https://api.envoisms.ma/v1/contacts?limit=50&offset=0" \
  -H "Authorization: Bearer smr_xxx"
{
  "data": [
    {
      "id": "ctc_a2b3...",
      "phone": "+212612345678",
      "name": "Karim Bennani",
      "email": "karim@email.ma",
      "custom1": "VIP",
      "custom2": null,
      "custom3": null,
      "created_at": "2026-05-10T14:20:00Z"
    }
  ],
  "limit": 100,
  "offset": 0,
  "total": 1
}
POST/v1/contacts

Créer / Modifier un contact

Ajoute un contact ou met à jour les informations d'un contact existant (détection par numéro).

Request Body
phonestringRequis
Numéro de téléphone au format E.164.
namestringOptionnel
Nom complet du contact.
emailstringOptionnel
Adresse email.
list_idstringOptionnel
Associer immédiatement le contact à une liste existante.
custom_fieldsobjectOptionnel
Objet contenant jusqu'à 3 champs personnalisés ("custom1", "custom2", "custom3").
POSThttps://api.envoisms.ma/v1/contacts
curl -X POST "https://api.envoisms.ma/v1/contacts" \
  -H "Authorization: Bearer smr_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+212612345678",
    "name": "Karim Bennani",
    "email": "karim@email.ma",
    "list_id": "lst_f84b..."
  }'
{
  "id": "ctc_a2b3...",
  "phone": "+212612345678",
  "name": "Karim Bennani",
  "email": "karim@email.ma",
  "custom1": "VIP",
  "custom2": null,
  "custom3": null,
  "created_at": "2026-05-10T14:20:00Z"
}
POST/v1/contacts/import

Importer des contacts

Importe massivement jusqu'à 5 000 contacts en un seul appel.

Request Body
contactsarrayRequis
Tableau d'objets contenant "phone", "name" (optionnel) et "email" (optionnel).
list_idstringOptionnel
ID de la liste dans laquelle importer le groupe.
POSThttps://api.envoisms.ma/v1/contacts/import
curl -X POST "https://api.envoisms.ma/v1/contacts/import" \
  -H "Authorization: Bearer smr_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      {
        "phone": "+212611111111",
        "name": "Karim"
      },
      {
        "phone": "+212622222222",
        "name": "Youssef"
      }
    ],
    "list_id": "lst_f84b..."
  }'
{
  "imported": 150,
  "skipped": 3
}
DELETE/v1/contacts/:id

Supprimer un contact

Supprime définitivement un contact à partir de son identifiant unique.

DELETEhttps://api.envoisms.ma/v1/contacts/:id
curl -X DELETE "https://api.envoisms.ma/v1/contacts/:id" \
  -H "Authorization: Bearer smr_xxx"
{
  "deleted": true,
  "id": "ctc_a2b3..."
}
GET/v1/contacts/lists

Lister les listes

Récupère toutes les listes de contacts créées pour les campagnes de diffusion.

GEThttps://api.envoisms.ma/v1/contacts/lists
curl -X GET "https://api.envoisms.ma/v1/contacts/lists" \
  -H "Authorization: Bearer smr_xxx"
{
  "data": [
    {
      "id": "lst_f84b...",
      "name": "Newsletter Clients",
      "description": "Clients inscrits à notre lettre d'information",
      "count": 1420,
      "created_at": "2026-04-15T09:00:00Z"
    }
  ]
}
POST/v1/contacts/lists

Créer une liste

Crée un nouveau groupe (liste de contacts) vide destiné aux campagnes.

Request Body
namestringRequis
Nom de la liste.
descriptionstringOptionnel
Description de la liste.
POSThttps://api.envoisms.ma/v1/contacts/lists
curl -X POST "https://api.envoisms.ma/v1/contacts/lists" \
  -H "Authorization: Bearer smr_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Newsletter Clients",
    "description": "Clients inscrits"
  }'
{
  "id": "lst_f84b...",
  "name": "Newsletter Clients",
  "description": "Clients inscrits",
  "count": 0
}
GET/v1/optouts

Lister les désinscriptions

Récupère la liste des numéros qui se sont désinscrits (STOP) de vos communications.

GEThttps://api.envoisms.ma/v1/optouts
curl -X GET "https://api.envoisms.ma/v1/optouts" \
  -H "Authorization: Bearer smr_xxx"
{
  "data": [
    {
      "phone": "+212611111111",
      "opted_out_at": "2026-06-01T12:00:00Z"
    }
  ],
  "total": 1
}
POST/v1/optouts

Ajouter une désinscription

Ajoute manuellement un numéro à votre liste de désinscription (blacklist globale).

Request Body
phonestringRequis
Numéro de téléphone au format E.164.
POSThttps://api.envoisms.ma/v1/optouts
curl -X POST "https://api.envoisms.ma/v1/optouts" \
  -H "Authorization: Bearer smr_xxx" \
  -H "Content-Type: application/json" \
  -d '{}'
{
  "success": true,
  "phone": "+212611111111",
  "opted_out_at": "2026-06-01T12:00:00Z"
}
DELETE/v1/optouts/:phone

Retirer une désinscription

Retire un numéro de la liste de désinscription.

DELETEhttps://api.envoisms.ma/v1/optouts/:phone
curl -X DELETE "https://api.envoisms.ma/v1/optouts/:phone" \
  -H "Authorization: Bearer smr_xxx"
{
  "deleted": true,
  "phone": "+212611111111"
}
GET/v1/campaigns

Lister les campagnes

Récupère toutes vos campagnes d'envoi programmé ou de diffusion en cours.

GEThttps://api.envoisms.ma/v1/campaigns
curl -X GET "https://api.envoisms.ma/v1/campaigns" \
  -H "Authorization: Bearer smr_xxx"
{
  "data": [
    {
      "id": "cmp_8d2a...",
      "name": "Soldes d'été 2026",
      "channel": "sms",
      "list_id": "lst_f84b...",
      "template_id": null,
      "body": "Bonjour {{name}}, profitez de -50% sur toute la collection avec le code ETE50 !",
      "sender_id": "SOLDES",
      "status": "draft",
      "scheduled_at": null,
      "created_at": "2026-06-01T12:00:00Z"
    }
  ]
}
POST/v1/campaigns

Créer une campagne

Enregistre une nouvelle campagne en tant que brouillon ou la planifie à une date précise.

Request Body
namestringRequis
Nom de la campagne.
bodystringRequis
Corps du message. Peut utiliser la variable {{name}}. (L'un des deux requis : body ou template_id.)
template_idstringRequis
Alternativement, ID d'un template approuvé. (L'un des deux requis : body ou template_id.)
channelstringOptionnel
"sms" ou "whatsapp". Par défaut "sms".
list_idstringOptionnel
ID de la liste de contacts destinataire.
sender_idstringOptionnel
Nom d'expéditeur.
scheduled_atstringOptionnel
Date de programmation (ISO 8601). Met le statut en "scheduled".
buttonsarrayOptionnel
Tableau de boutons WhatsApp interactifs (max 3, type "copy" | "url" | "call").
metadataobjectOptionnel
Métadonnées personnalisées (ex: options de throttling / cadence d'envoi : {"throttling": "50_min"}).
POSThttps://api.envoisms.ma/v1/campaigns
curl -X POST "https://api.envoisms.ma/v1/campaigns" \
  -H "Authorization: Bearer smr_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Soldes d'été 2026",
    "body": "Bonjour {{name}}, profitez de -50% avec le code ETE50 !",
    "channel": "sms",
    "list_id": "lst_f84b...",
    "sender_id": "SOLDES"
  }'
{
  "id": "cmp_8d2a...",
  "status": "draft"
}
GET/v1/campaigns/:id

Détails d'une campagne

Récupère les détails, la planification et le statut d'exécution d'une campagne.

GEThttps://api.envoisms.ma/v1/campaigns/:id
curl -X GET "https://api.envoisms.ma/v1/campaigns/:id" \
  -H "Authorization: Bearer smr_xxx"
{
  "id": "cmp_8d2a...",
  "name": "Soldes d'été 2026",
  "channel": "sms",
  "list_id": "lst_f84b...",
  "body": "Bonjour {{name}}, profitez de -50%...",
  "sender_id": "SOLDES",
  "status": "running",
  "total_count": 1420,
  "sent_count": 840,
  "started_at": "2026-06-15T10:00:00Z",
  "created_at": "2026-06-01T12:00:00Z"
}
POST/v1/campaigns/:id/send

Lancer une campagne

Démarre immédiatement la diffusion d'une campagne de type brouillon vers tous les contacts associés.

POSThttps://api.envoisms.ma/v1/campaigns/:id/send
curl -X POST "https://api.envoisms.ma/v1/campaigns/:id/send" \
  -H "Authorization: Bearer smr_xxx" \
  -H "Content-Type: application/json" \
  -d '{}'
{
  "id": "cmp_8d2a...",
  "queued": 1420,
  "total": 1420
}
GET/v1/webhooks

Lister les webhooks

Récupère la liste de tous vos endpoints de webhooks enregistrés.

GEThttps://api.envoisms.ma/v1/webhooks
curl -X GET "https://api.envoisms.ma/v1/webhooks" \
  -H "Authorization: Bearer smr_xxx"
{
  "data": [
    {
      "id": "whk_5f2b...",
      "url": "https://mon-serveur.ma/api/envoisms-receiver",
      "events": [
        "message.delivered",
        "message.failed"
      ],
      "active": true,
      "last_triggered_at": "2026-06-15T09:30:15Z",
      "last_status": 200,
      "created_at": "2026-05-01T10:00:00Z"
    }
  ]
}
POST/v1/webhooks

Créer un Webhook

Enregistre une URL HTTPS de callback pour recevoir les notifications d'événements.

Request Body
urlstringRequis
URL cible sécurisée commençant par "https://".
eventsarrayOptionnel
Tableau d'événements (ex: ["message.delivered", "message.failed"]). Les jokers "message.*" et "*" sont acceptés. Défaut: ["message.delivered", "message.failed"].
secretstringOptionnel
Clé de signature secrète. Si non fournie, elle sera générée automatiquement.
POSThttps://api.envoisms.ma/v1/webhooks
curl -X POST "https://api.envoisms.ma/v1/webhooks" \
  -H "Authorization: Bearer smr_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://mon-serveur.ma/api/envoisms-receiver",
    "events": [
      "message.delivered",
      "message.failed"
    ]
  }'
{
  "id": "whk_5f2b...",
  "url": "https://mon-serveur.ma/api/envoisms-receiver",
  "events": [
    "message.delivered",
    "message.failed"
  ],
  "secret": "whsec_2f8a9e7d...",
  "active": true
}
PATCH/v1/webhooks/:id

Modifier un Webhook

Met à jour la configuration d'un webhook (URL, événements surveillés ou état actif).

Request Body
urlstringOptionnel
Nouvelle URL HTTPS.
eventsarrayOptionnel
Nouvelle liste d'événements abonnés.
activebooleanOptionnel
Activer (true) ou désactiver (false) le webhook.
PATCHhttps://api.envoisms.ma/v1/webhooks/:id
curl -X PATCH "https://api.envoisms.ma/v1/webhooks/:id" \
  -H "Authorization: Bearer smr_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://mon-serveur.ma/api/envoisms-receiver-updated",
    "active": false
  }'
{
  "updated": true,
  "id": "whk_5f2b..."
}
DELETE/v1/webhooks/:id

Supprimer un Webhook

Désactive et supprime logiquement un endpoint de webhook.

DELETEhttps://api.envoisms.ma/v1/webhooks/:id
curl -X DELETE "https://api.envoisms.ma/v1/webhooks/:id" \
  -H "Authorization: Bearer smr_xxx"
{
  "deleted": true,
  "id": "whk_5f2b..."
}
POST/v1/webhooks/:id/test

Tester un Webhook

Déclenche un événement de test ("message.test") vers l'URL configurée du webhook.

POSThttps://api.envoisms.ma/v1/webhooks/:id/test
curl -X POST "https://api.envoisms.ma/v1/webhooks/:id/test" \
  -H "Authorization: Bearer smr_xxx" \
  -H "Content-Type: application/json" \
  -d '{}'
{
  "queued": true,
  "id": "whk_5f2b..."
}
GET/v1/api-keys

Lister les clés API

Récupère la liste de toutes vos clés d'API actives ou révoquées.

GEThttps://api.envoisms.ma/v1/api-keys
curl -X GET "https://api.envoisms.ma/v1/api-keys" \
  -H "Authorization: Bearer smr_xxx"
{
  "data": [
    {
      "id": "key_e84c...",
      "name": "Production Server",
      "key_prefix": "smr_a8f7d6c5",
      "sandbox": false,
      "ip_whitelist": [
        "196.200.1.4"
      ],
      "rate_limit": 100,
      "permissions": [
        "send",
        "verify",
        "status"
      ],
      "active": true,
      "last_used_at": "2026-06-15T10:30:00Z",
      "created_at": "2026-05-01T08:00:00Z"
    }
  ]
}
POST/v1/api-keys

Créer une clé API

Génère un nouveau jeton d'API sécurisé avec des permissions et restrictions spécifiques.

Request Body
namestringOptionnel
Libellé pour identifier la clé (défaut: "API key").
permissionsarrayOptionnel
Droits accordés (send, verify, status, balance, contacts, campaigns, webhooks, billing, analytics, api_keys, optouts).
ip_whitelistarrayOptionnel
Liste d'adresses IP autorisées à exécuter des requêtes avec cette clé.
rate_limitintegerOptionnel
Limite maximale de requêtes/min (de 10 à 1000, défaut: 100).
sandboxbooleanOptionnel
true génère une clé de test préfixée env_test_. Les requêtes sont validées et enregistrées, mais aucun message n'est réellement envoyé et rien n'est facturé. Le mode d'une clé est définitif : pour changer, créez une nouvelle clé.
POSThttps://api.envoisms.ma/v1/api-keys
curl -X POST "https://api.envoisms.ma/v1/api-keys" \
  -H "Authorization: Bearer smr_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Server",
    "permissions": [
      "send",
      "verify",
      "status"
    ],
    "ip_whitelist": [
      "196.200.1.4"
    ],
    "rate_limit": 100
  }'
{
  "id": "key_e84c...",
  "name": "Production Server",
  "key_prefix": "smr_a8f7d6c5",
  "api_key": "smr_a8f7d6c5b4a3...",
  "sandbox": false,
  "permissions": [
    "send",
    "verify",
    "status"
  ],
  "rate_limit": 100,
  "warning": "The full API key is shown once. Store it securely."
}
PATCH/v1/api-keys/:id

Modifier une clé API

Met à jour les permissions, restrictions IP ou l'état d'activation d'une clé API.

Request Body
namestringOptionnel
Nouveau nom.
permissionsarrayOptionnel
Nouvelle liste de permissions.
ip_whitelistarrayOptionnel
Nouvelle liste d'adresses IP autorisées.
rate_limitintegerOptionnel
Nouvelle limite de débit par minute.
activebooleanOptionnel
Activer ou suspendre la clé.
PATCHhttps://api.envoisms.ma/v1/api-keys/:id
curl -X PATCH "https://api.envoisms.ma/v1/api-keys/:id" \
  -H "Authorization: Bearer smr_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Backup Server",
    "active": true
  }'
{
  "updated": true,
  "id": "key_e84c..."
}
DELETE/v1/api-keys/:id

Révoquer une clé API

Révoque définitivement une clé API pour l'empêcher d'authentifier les requêtes.

DELETEhttps://api.envoisms.ma/v1/api-keys/:id
curl -X DELETE "https://api.envoisms.ma/v1/api-keys/:id" \
  -H "Authorization: Bearer smr_xxx"
{
  "revoked": true,
  "id": "key_e84c..."
}
GET/v1/billing/balance

Consulter le solde

Consulte le solde disponible en Dirhams Marocains (MAD) ainsi que la devise et le forfait actif.

GEThttps://api.envoisms.ma/v1/billing/balance
curl -X GET "https://api.envoisms.ma/v1/billing/balance" \
  -H "Authorization: Bearer smr_xxx"
{
  "balance_mad": 1492.5,
  "currency": "MAD",
  "plan": "croissance"
}
GET/v1/analytics

Statistiques d'usage

Récupère des métriques clés sur vos envois (volumes totaux, taux de délivrabilité, et coûts facturés).

GEThttps://api.envoisms.ma/v1/analytics
curl -X GET "https://api.envoisms.ma/v1/analytics" \
  -H "Authorization: Bearer smr_xxx"
{
  "summary": {
    "total": 12840,
    "delivered": 12570,
    "delivery_rate": 97.9,
    "cost_mad": 2663.1
  }
}

Guide Webhooks

Callbacks de livraison signés et sécurisés.

EnvoiSMS.ma poste des événements JSON à l'URL HTTPS de votre serveur avec un en-tête X-EnvoiSMS.ma-Signature pour authentifier l'expéditeur.

message.sent

Le message a été accepté par le réseau de l'opérateur.

message.delivered

Le message a été remis avec succès au destinataire.

message.failed

Échec de livraison côté route ou soumission (rejet, erreur d'acheminement).

message.undeliverable

Le réseau a confirmé que le message ne peut pas être remis (numéro inexistant, expiré en file opérateur).

message.inbound

Un destinataire a répondu à l'un de vos messages SMS (inbound).

contact.optout

Un destinataire s'est désabonné (mot-clé STOP ou assimilé).

Validation de Signature
import crypto from 'node:crypto';

// La signature arrive dans le header X-EnvoiSMS-Signature
// (format "sha256=<hex>"), l'événement dans X-EnvoiSMS-Event.
// Corps livré : { "event": "...", "data": { ... }, "timestamp": "..." }
export function verifySignature(body: string, sig: string, secret: string) {
  const hmac = crypto.createHmac('sha256', secret)
    .update(body)
    .digest('hex');

  return crypto.timingSafeEqual(Buffer.from(sig), Buffer.from('sha256=' + hmac));
}
OpenAPI Spec

Erreurs

Structure des réponses d'erreur de l'API.

Toutes les erreurs de l'API retournent un code HTTP approprié (4xx ou 5xx) ainsi qu'une enveloppe JSON prévisible contenant le code de l'erreur et une description.

{
  "error": {
    "code": "INVALID_PHONE",
    "message": "to must be E.164 format, for example +212612345678",
    "docs": "https://envoisms.ma/docs#errors"
  }
}
UNAUTHORIZED

Clé API manquante ou invalide.

INSUFFICIENT_BALANCE

Solde insuffisant pour effectuer l'envoi.

INVALID_PHONE

Le numéro de téléphone n'est pas au format E.164.

RATE_LIMITED

Limite de requêtes par minute dépassée. Respectez l'en-tête Retry-After.

INVALID_IDEMPOTENCY_KEY

L'en-tête Idempotency-Key dépasse 255 caractères.

IDEMPOTENCY_IN_FLIGHT

La requête originale portant cette Idempotency-Key est encore en cours. Réessayez dans un instant.

IDEMPOTENCY_KEY_REUSED

Cette Idempotency-Key a déjà été utilisée avec un corps de requête différent. Utilisez une nouvelle clé.

INVALID_CHANNEL

Le canal demandé n'existe pas. Canaux valides : sms, whatsapp, telegram, voice, rcs.

CHANNEL_NOT_CONFIGURED

Le canal demandé n'est pas disponible actuellement sur la plateforme.

CHANNEL_DISABLED

Le canal demandé est désactivé sur la plateforme.

FORBIDDEN

La clé API n'a pas la permission requise pour cette action, ou le compte est suspendu.

SENDER_ID_TOO_LONG

Le Sender ID dépasse la limite de 11 caractères.

SENDER_ID_INVALID

Le Sender ID contient des caractères non autorisés.

SENDER_ID_NOT_APPROVED

Le Sender ID n'a pas encore été approuvé par les opérateurs.

SENDER_ID_PENDING

Le Sender ID est en cours d'approbation.

SENDER_ID_REJECTED

Le Sender ID a été rejeté par les opérateurs.

MISSING_FIELD

Un champ obligatoire est manquant dans la requête.

CASCADE_TIMEOUT

Le premier canal a expiré, basculement vers le canal secondaire (cascade).

UPSTREAM_ERROR

Erreur de livraison au niveau de l'opérateur ou de la passerelle.

OPTED_OUT

Le numéro a refusé vos communications (STOP). Envoi interdit.

SPAM_OR_PHISHING_DETECTED

Le message contient un lien identifié comme hameçonnage ou spam. Envoi refusé.

CONTENT_BLOCKED

Le contenu du message a été bloqué par le contrôle anti-abus et le compte est suspendu en attente de revue. Contactez le support.

INVALID_CODE

Le code OTP soumis est incorrect. Le message d'erreur indique le nombre de tentatives restantes.

EXPIRED_CODE

Le code OTP a expiré. Demandez un nouveau code via /v1/verify/send.

MAX_ATTEMPTS

Nombre maximal de tentatives de vérification dépassé. La session est clôturée.

STRIPE_ERROR

La page de paiement n'a pas pu être créée de notre côté. Aucun débit n'a eu lieu — réessayez dans un instant.

INTERNAL_ERROR

Erreur interne de notre côté. Réessayez ; contactez le support si le problème persiste.

Limites

Contraintes et quotas de l'environnement de production.

OpenAPI YAML
Requêtes API

100 requêtes / minute (extensible sur demande).

Taille Message

1600 caractères maximum par message.

Batch Bulk

Jusqu'à 10 000 messages par appel API.

Rétention Logs

90 jours pour les rapports détaillés.