Messages

Send a message

POST /v1/messages

curl -X POST https://api.joinsimplesms.com/v1/messages \
  -H "Authorization: Bearer ssms_sk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "from": "+15005550100", "to": "+15005550006", "body": "Hello" }'

Returns 201 with a Message object. status starts at sent (or queued) and progresses via events.

Scheduling

Add scheduled_at (a future ISO timestamp or epoch ms, up to 30 days out) to queue the send. The response is a scheduled_message object; see Scheduled.

Automatic retries

If the carrier has a temporary problem (it is overloaded, throttling, or unreachable), we do not fail your send. The response is 202 with the message queued, and we retry it for you after 30 seconds, 2 minutes and 10 minutes. attempts counts the tries so far and next_attempt_at says when the next one runs, and the message's timeline records every attempt (sent_to_carrier and retry_scheduled with an attempt number). You get message.sent when the carrier accepts it, or message.failed if every attempt fails. You pay only for messages the carrier accepts.

A message is never sent twice. We only retry when we know the carrier did not take the message. If the carrier stops answering after we handed it the message, we cannot know, so the send fails with failure_reason: "carrier_timeout" and you decide whether to send again. A permanent rejection (a bad number, say) fails straight away with 502 carrier_error, as before.

Idempotency

Pass an Idempotency-Key header to make retries safe: the same key + same payload replays the original response (with an Idempotent-Replayed: true header); the same key with a different payload returns 409 idempotency_conflict. Keys last 24 hours. Only successful responses are kept: if a request fails, the key is released, so retrying with the same key runs it again. POST /v1/verify and POST /v1/numbers accept the header too. With scheduled_at, the schedule time is part of the payload, so a retried scheduling request never queues a second send.

With the SDKs

Both SDKs add an idempotency key to every send automatically, so their built-in retries can never double-send.

import { SimpleSMS } from 'joinsimplesms';
const sms = new SimpleSMS(process.env.SIMPLESMS_API_KEY);

const message = await sms.messages.send({
  from: '+15005550100',
  to: '+15005550006',
  body: 'Hello',
});

from joinsimplesms import SimpleSMS

client = SimpleSMS()  # reads SIMPLESMS_API_KEY

message = client.messages.send(to="+15005550006", text="Hello")
# from_ is optional while your account has one number

Retrieve a message

GET /v1/messages/{id}; the id is the msg_... from the send response.

List messages

GET /v1/messages?limit=25&cursor=...&status=failed&created_after=2026-10-01T00:00:00Z

Newest first. Responses are { "data": [...], "has_more": bool, "next_cursor": "..." }; pass next_cursor back as cursor with the same filters for the next page.

Filters combine. Pages come back full: a page shorter than limit with has_more: false is the end. A very sparse filter over a long history can return a short page with has_more: true (one request reads at most 2,000 messages); keep following next_cursor. Narrow with a date range to make those requests fast. The SDKs page for you: sms.messages.listAll() (Node, an async iterator) and client.messages.list_all() (Python, a generator).

The Message object

{
  "id": "msg_a1B2c3D4e5F6g7H8",
  "object": "message",
  "to": "+15005550007",
  "from": "+15005550100",
  "body": "Your order shipped",
  "direction": "outbound",
  "status": "failed",
  "test": true,
  "created_at": "2026-10-01T17:02:11.204Z",
  "timeline": [
    { "status": "accepted", "at": "2026-10-01T17:02:11.204Z" },
    { "status": "validated", "at": "2026-10-01T17:02:11.231Z" },
    { "status": "queued", "at": "2026-10-01T17:02:11.248Z" },
    { "status": "sent_to_carrier", "at": "2026-10-01T17:02:11.249Z" },
    { "status": "carrier_accepted", "at": "2026-10-01T17:02:11.412Z" },
    { "status": "failed", "at": "2026-10-01T17:02:13.020Z" }
  ],
  "segments": 1,
  "encoding": "gsm7",
  "price": {
    "total": 0,
    "currency": "usd",
    "breakdown": [{ "label": "Sandbox message (test mode is never billed)", "amount": 0 }]
  },
  "destination_carrier": "Sandbox Wireless",
  "failure": {
    "code": "carrier_filtered",
    "title": "Filtered as spam",
    "explanation": "The recipient's mobile carrier filtered this message as spam or unwanted traffic, so it never reached the phone.",
    "action": "Recommended: identify your business in the first words, ...",
    "carrier_code": null
  },
  "failure_reason": "stat:UNDELIV err:000 (sandbox) message filtered as spam by the destination carrier"
}

Statuses

queued → sent → delivered (or failed). Inbound messages have direction inbound and status received.

Carriers report delivery for most messages within minutes. Some never report at all. If a sent message has no delivery report 72 hours after the carrier accepted it, it gets receipt_status: "missing". Its status stays sent: we know the carrier accepted it, and we will not guess whether it arrived. No event fires. A late report still updates the message and clears the flag.