SendexaDocs
Dash

SIM Route

Send from a real mobile number instead of a sender ID. The message leaves a physical SIM card, so it arrives as a normal person-to-person text and the recipient can reply to that number.

HTTP API

Add route to a normal send request. It works on both POST /v1/sms/send and POST /v1/a2p/send. Omit it, or send "sid", for the standard sender-ID route.

Bash
curl -X POST https://api.sendexa.co/v1/sms/send \
  -H "Authorization: Basic <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "233240000000",
    "from": "Sendexa",
    "message": "Your order has shipped.",
    "route": "sim"
  }'

The response tells you which route was actually used, and the number the message was sent from:

JSON
{
  "success": true,
  "data": {
    "messageId": "MSG-…",
    "message": {
      "from": { "name": "+233500000000" },
      "to": { "address": "233240000000" }
    },
    "delivery": {
      "status": "PENDING",
      "route": { "channel": "sim" }
    }
  }
}
Always check delivery.route.channel

"sim" means a SIM was picked. "sid" means the message went over the sender-ID route — because the SIM route isn't enabled on your account, or no SIM was available right now (all busy, at their daily limit, or offline). You are billed for the route that was used.

SMPP

SMPP has no per-message route field, so the choice is made per account: ask Sendexa to set your SMPP system_id's default route to SIM. Every submit_sm on that bind then uses the SIM route (when available), and delivery receipts (deliver_sm) work exactly as they do today.

Sender ID and replies

  • The from value you send is ignored on the SIM route — the SIM's own number is the sender. Your sender ID stays recorded on the message for your records.
  • Recipients can reply to that number. A reply is routed to the account that most recently sent that person a SIM-route message from that number (within 30 days), and is delivered to you as a webhook and via the API below. Replies that match no message are kept by Sendexa and never shared with another account.

Receiving replies

Subscribe a webhook to the SMS_RECEIVED event to get each reply as it arrives:

JSON
{
  "id": "cm…",
  "from": "233240000000",
  "to": "+233500000000",
  "message": "Yes, I'll be there",
  "receivedAt": "2026-01-01T10:15:00.000Z",
  "inReplyTo": "MSG-…",
  "optOut": false
}

Or pull them, newest first, with GET /v1/sms/inbound?limit=50 (pass before=<id> from nextCursor for the next page).

  • inReplyTo is the messageId of the message being answered, when it can be identified.
  • optOut is true when the reply is a stop request (STOP, UNSUBSCRIBE, CANCEL…). Honouring it is your responsibility — don't message that number again.
  • Replies are only available for phones running the Sendexa SIM Gateway app.

Fallback and billing

If a SIM can't send — the phone is offline, the gateway rejects the message, or the phone later reports the send failed — Sendexa re-sends it over the sender-ID route automatically, so it still goes out.

  • SIM sends can have their own per-segment rate. If a message falls back and the sender-ID rate is lower, the difference is credited back to your wallet — you never pay more than the route that delivered.
  • The same messageId is kept, and MESSAGE_SENT / MESSAGE_DELIVERED / MESSAGE_FAILED webhooks work as usual.