Sendimo REST API v1 documentation.

Essentials

v1 endpoints

Authentication

Every request carries a secret API key as a Bearer token. Keys are created and revoked in the dashboard; each key is shown once at creation.

• Keys are server-side only. Never ship them in a mobile app or browser code.
• A missing or invalid key returns 401 unauthorized. A revoked key returns 401 key_revoked.
• Test numbers: in test mode, +21600000001 always ends delivered and +21600000002 always ends failed.

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

Send SMS — POST /messages

Sends one SMS. The call returns as soon as the message is accepted (202); the final status arrives later via webhook or 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": "Your code is 482913. It expires in 5 minutes.",
    "reference": "order-4821"
  }'

{
  "id": "msg_01HF8Z3K9QX2",
  "status": "queued",
  "to": "+21620123456",
  "from": "SENDIMO",
  "text": "Your code is 482913. It expires in 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"
}

Bulk send — POST /messages/bulk

Sends up to 10,000 messages in one call. Use a shared text, or per-recipient text for personalized messages. Returns a batch you can track.

Invalid numbers do not fail the whole batch: they are listed in rejected with { "index", "to", "error" } and are not charged. GET /batches/{id} returns the same object with live counts per status (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"
}

Get and list messages

GET /messages/{id} returns the message object with its current status, plus sent_at, delivered_at and error (null unless failed).

GET /messages lists messages, newest first, with cursor pagination.

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

Message statuses

A message moves queued → sent → delivered, or ends in failed, undelivered or canceled. Final statuses never change. To cancel a scheduled message: DELETE /messages/{id} (only while scheduled).

Sender IDs

A sender ID is the name recipients see instead of a number (max 11 letters/digits, e.g. SENDIMO). Tunisian operators require each one to be approved before use, so new IDs go through review.

Statuses: pending, approved, rejected (with a reason). Sending with an ID that is not approved returns 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" }

Balance — GET /account/balance

reserved is held for queued messages and released or charged once they reach a status. A send that exceeds the available balance returns 402 insufficient_balance.

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

Errors

Every error uses the same shape, with a stable machine-readable code and a request_id for support.

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

Rate limits

Each response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. A 429 includes Retry-After in seconds.

Idempotency

Send an Idempotency-Key header (any unique string, max 64 chars) on every POST. If a network error leaves you unsure whether a send worked, retry with the same key: Sendimo returns the original response instead of sending twice. Keys are kept 24 hours.

Encoding and segments

Sendimo picks the encoding automatically and bills per segment. Arabic text, emoji and some accented characters force Unicode, which roughly halves the characters per SMS.

The response always returns encoding, segments and cost, so clients can show the price before a bulk send.

Other integrations