La documentation de l’API REST Sendimo v1.

L’essentiel

Endpoints v1

Authentification

Chaque requête porte une clé API secrète en jeton Bearer. Les clés sont créées et révoquées dans votre espace ; chaque clé n’est affichée qu’une fois, à sa création.

• Les clés s’utilisent uniquement côté serveur. Ne les placez jamais dans une application mobile ou du code navigateur.
• Une clé absente ou invalide renvoie 401 unauthorized. Une clé révoquée renvoie 401 key_revoked.
• Numéros de test : en mode test, +21600000001 finit toujours en delivered et +21600000002 toujours en failed.

curl https://api.sendimo.tn/v1/account/balance \
  -H "Authorization: Bearer sk_live_9f2c..."

Envoyer un SMS — POST /messages

Envoie un SMS. L’appel répond dès que le message est accepté (202) ; le statut final arrive ensuite par webhook ou via GET /messages/{id}.

curl -X POST https://api.sendimo.tn/v1/messages \
  -H "Authorization: Bearer $SENDIMO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-4821-otp" \
  -d '{
    "to": "+21620123456",
    "from": "SENDIMO",
    "text": "Votre code est 482913. Il expire dans 5 minutes.",
    "reference": "order-4821"
  }'

{
  "id": "msg_01HF8Z3K9QX2",
  "status": "queued",
  "to": "+21620123456",
  "from": "SENDIMO",
  "text": "Votre code est 482913. Il expire dans 5 minutes.",
  "encoding": "GSM-7",
  "segments": 1,
  "network": "ooredoo",
  "cost": { "amount": "0.140", "currency": "TND" },
  "reference": "order-4821",
  "scheduled_at": null,
  "created_at": "2026-10-30T09:15:00Z"
}

Envoi en masse — POST /messages/bulk

Envoie jusqu’à 10 000 messages en un seul appel, avec un texte commun ou un texte par destinataire pour personnaliser. Renvoie un lot (batch) que vous pouvez suivre.

Les numéros invalides ne font pas échouer tout le lot : ils sont listés dans rejected avec { "index", "to", "error" } et ne sont pas facturés. GET /batches/{id} renvoie le même objet avec le nombre de messages par statut (queued, sent, delivered, failed).

{
  "from": "SENDIMO",
  "text": "Promo -20% ce week-end sur tout le magasin.",
  "messages": [
    { "to": "+21620123456" },
    { "to": "+21698765432", "text": "Salut Amine, -20% pour toi ce week-end." }
  ]
}

{
  "id": "bat_01HF90AB7C",
  "status": "processing",
  "total": 2,
  "accepted": 2,
  "rejected": [],
  "estimated_cost": { "amount": "0.280", "currency": "TND" },
  "created_at": "2026-10-30T09:20:00Z"
}

Consulter et lister les messages

GET /messages/{id} renvoie le message avec son statut actuel, ainsi que sent_at, delivered_at et error (null sauf en cas d’échec).

GET /messages liste les messages, du plus récent au plus ancien, avec une pagination par curseur.

{
  "data": [ { "id": "msg_01HF8Z3K9QX2", "status": "delivered", "...": "..." } ],
  "has_more": true,
  "next_cursor": "eyJpZCI6Im1zZ18wMUhGOFoz..."
}

Statuts des messages

Un message passe de queued à sent puis delivered, ou se termine en failed, undelivered ou canceled. Les statuts finaux ne changent plus. Pour annuler un message programmé : DELETE /messages/{id} (uniquement tant qu’il est scheduled).

Sender IDs

Un Sender ID est le nom que voient les destinataires à la place d’un numéro (11 lettres ou chiffres max, par exemple SENDIMO). Les opérateurs tunisiens exigent que chaque nom soit approuvé avant utilisation : les nouveaux noms passent donc en revue.

Statuts : pending, approved, rejected (avec un motif). Envoyer avec un nom non approuvé renvoie 403 sender_not_approved.

{
  "data": [
    { "id": "snd_01HE7A", "name": "SENDIMO", "status": "approved", "created_at": "2026-10-01T10:00:00Z" },
    { "id": "snd_01HF2C", "name": "MYSHOP", "status": "pending", "created_at": "2026-10-29T14:30:00Z" }
  ]
}

{ "name": "MYSHOP", "use_case": "Order confirmations and delivery updates for myshop.tn" }

Solde — GET /account/balance

reserved est bloqué pour les messages en file d’attente, puis libéré ou débité quand ils atteignent un statut. Un envoi qui dépasse le solde disponible renvoie 402 insufficient_balance.

{
  "balance": { "amount": "152.340", "currency": "TND" },
  "reserved": { "amount": "0.900", "currency": "TND" },
  "low_balance_threshold": { "amount": "20.000", "currency": "TND" }
}

Erreurs

Toutes les erreurs ont le même format, avec un code stable lisible par machine et un request_id pour le support.

{
  "error": {
    "code": "invalid_phone_number",
    "message": "'to' must be a valid Tunisian number in E.164 format.",
    "field": "to",
    "request_id": "req_01HF9C4D"
  }
}

Limites de débit

Chaque réponse contient X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset. Une réponse 429 inclut Retry-After, en secondes.

Idempotence

Envoyez un en-tête Idempotency-Key (n’importe quelle chaîne unique, 64 caractères max) sur chaque POST. Si une erreur réseau vous laisse dans le doute, réessayez avec la même clé : Sendimo renvoie la réponse d’origine au lieu d’envoyer deux fois. Les clés sont conservées 24 heures.

Encodage et segments

Sendimo choisit l’encodage automatiquement et facture par segment. Le texte arabe, les emojis et certains caractères accentués imposent l’Unicode, ce qui divise environ par deux le nombre de caractères par SMS.

La réponse indique toujours encoding, segments et cost : vous pouvez afficher le prix avant un envoi en masse.

Les autres intégrations