SMS API

The SMS API lets you send messages to any Mauritanian number. Messages are queued immediately and delivered through Mauritania-optimized carrier routing.

Requires a secret key (sk_…). See API Keys.

Send a message

POST /api/sms

Request headers

Request body

Response

Example

curl -X POST https://api.moorsyl.com/api/sms \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk_live_..." \
  -d '{
    "to": "+22236551999",
    "from": "MyBrand",
    "body": "Your order #1042 has been shipped."
  }'

{
  "accepted": true,
  "messageId": "2a8df28b-9b7e-4f8a-aafd-21f8ef34f4e1",
  "idempotencyKey": "a3b4c5d6-...",
  "organizationId": "org_..."
}

Phone number format

Only Mauritanian numbers are accepted. The number must start with +222, followed by a digit 2, 3, or 4, then 7 more digits:

+222[2-4]XXXXXXX

Idempotency

Supply an idempotencyKey to ensure a message is only sent once even if you retry the request. If a request with the same key has already been accepted, the API returns the original response without queuing a new message.

If you omit idempotencyKey, one is generated and returned in the response.

curl -X POST https://api.moorsyl.com/api/sms \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk_live_..." \
  -d '{
    "to": "+22236551999",
    "from": "MyBrand",
    "body": "Your code is 847291",
    "idempotencyKey": "otp-user42-20240101T120000"
  }'

Good idempotency keys include the user ID and a timestamp or attempt counter so they are unique per intent but stable across retries.

Poll message status

Use the messageId returned by POST /api/sms to fetch the latest delivery state.

curl -X POST https://api.moorsyl.com/api/sms/get \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk_live_..." \
  -d '{
    "messageId": "2a8df28b-9b7e-4f8a-aafd-21f8ef34f4e1"
  }'

Delivery events

When a message is sent or fails, Moorsyl fires a webhook event. Set up a Webhook endpoint to receive sms.sent and sms.failed events and trigger downstream actions in your system.

Errors