API Reference

التوثيق التقني

ادمج خدمات EnvoiSMS.ma في أقل من 15 دقيقة باستخدام مكتباتنا للغات PHP و Node.js و Python. مصمم للمطورين المحترفين.

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 env_live_xxx

Limite par défaut100 requêtes / minute

Format numéroE.164 (ex: +212612345678)

Canaux actifsSMS Premium, WhatsApp Business API

LocalisationInfrastructure hébergée au Maroc 🇲🇦

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

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

Testez votre intégration via le mode Sandbox pour ne consommer aucun crédit réel.

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

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

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

// 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 env_live_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 env_live_xxxxxxxx
Content-Type: application/json
Accept: application/json

POST/v1/messages

Envoyer un message

Envoie un SMS Premium 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.

buttonsarrayOptionnel

Tableau d'objets boutons WhatsApp interactifs (max 3, type "copy" | "url" | "call").

POSThttps://api.envoisms.ma/v1/messages

curl -X POST "https://api.envoisms.ma/v1/messages" \
  -H "Authorization: Bearer env_live_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.0118,
    "mad": 0.13
  },
  "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".

POSThttps://api.envoisms.ma/v1/messages/bulk

curl -X POST "https://api.envoisms.ma/v1/messages/bulk" \
  -H "Authorization: Bearer env_live_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).

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 env_live_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.

GEThttps://api.envoisms.ma/v1/messages/:id

curl -X GET "https://api.envoisms.ma/v1/messages/:id" \
  -H "Authorization: Bearer env_live_xxx"

{
  "id": "msg_8f2d...",
  "account_id": "acc_3f1a...",
  "api_key_id": "key_e84c...",
  "campaign_id": null,
  "to": "+212612345678",
  "channel": "whatsapp",
  "body": "Votre code de validation est 849204",
  "sender_id": "MaBanque",
  "unicode": 0,
  "segments": 1,
  "status": "delivered",
  "cost_eur": 0.0118,
  "cost_mad": 0.13,
  "metadata": "{\"purpose\": \"otp\"}",
  "created_at": "2026-05-15T10:30:00Z"
}

POST/v1/verify/send

Générer un OTP

Génère un code de validation à usage unique et l'envoie par SMS ou WhatsApp.

Request Body

tostringRequis

Destinataire au format E.164.

brandstringOptionnel

Nom de la marque affiché (ex: MonApp, max 32 car.). Par défaut "EnvoiSMS".

channelstringOptionnel

"whatsapp" (recommandé pour diviser les coûts par 10) ou "sms". Défaut: "sms".

code_lengthintegerOptionnel

Longueur du code généré (de 4 à 8 chiffres, défaut: 6).

expiryintegerOptionnel

Durée de validité du code en secondes (de 60 à 1800, défaut: 600).

templatestringOptionnel

Texte personnalisé avec les variables {{code}} et {{brand}}.

otp_button_textstringOptionnel

Libellé personnalisé pour le bouton de copie automatique WhatsApp (max 25 car.).

POSThttps://api.envoisms.ma/v1/verify/send

curl -X POST "https://api.envoisms.ma/v1/verify/send" \
  -H "Authorization: Bearer env_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+212612345678",
    "brand": "MonApp",
    "channel": "whatsapp",
    "code_length": 6,
    "expiry": 600
  }'

{
  "session_id": "vrf_7e2a...",
  "message_id": "msg_1b8e...",
  "to": "+212612345678",
  "channel": "whatsapp",
  "expires_at": "2026-05-15T10:40:00Z",
  "status": "sent"
}

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 env_live_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 env_live_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 env_live_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

Pagination offset (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 env_live_xxx"

{
  "data": [
    {
      "id": "ctc_a2b3...",
      "phone": "+212612345678",
      "name": "Karim Bennani",
      "email": "[email protected]",
      "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 env_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+212612345678",
    "name": "Karim Bennani",
    "email": "[email protected]",
    "list_id": "lst_f84b..."
  }'

{
  "id": "ctc_a2b3...",
  "phone": "+212612345678",
  "name": "Karim Bennani",
  "email": "[email protected]",
  "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 env_live_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 env_live_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 env_live_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 env_live_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/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 env_live_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.

bodystring (Requis*)Requis

Corps du message. Peut utiliser la variable {{name}}.

template_idstring (Requis*)Requis

Alternativement, ID d'un template approuvé. (*L'un des deux requis).

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 env_live_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 env_live_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 env_live_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 env_live_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"]). Défaut: tous.

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 env_live_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 env_live_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 env_live_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 env_live_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 env_live_xxx"

{
  "data": [
    {
      "id": "key_e84c...",
      "name": "Production Server",
      "key_prefix": "env_live",
      "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).

POSThttps://api.envoisms.ma/v1/api-keys

curl -X POST "https://api.envoisms.ma/v1/api-keys" \
  -H "Authorization: Bearer env_live_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": "env_live",
  "api_key": "env_live_a8f7d6c5b4a3...",
  "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 env_live_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 env_live_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 env_live_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 env_live_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.delivered

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

message.failed

Échec de livraison (numéro invalide, rejet opérateur).

message.expired

Le message a expiré dans la file d'attente opérateur.

verify.success

Une session OTP a été validée avec succès.

import crypto from 'node:crypto';

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.

CHANNEL_NOT_ALLOWED

Le canal demandé (ex: WhatsApp) n'est pas activé sur votre compte.

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.