Send an SMS

POST /v1/messages

Sends an SMS from one of your numbers. In test mode the message is simulated: it reaches delivered but no text is sent (simulated: true, an X-SimpleSMS-Simulated header, and a notice when to is a real-looking number). The one exception is a send to your own verified phone, which is really delivered when a verification sender is available (simulated: false). from may be omitted when the account has exactly one number for the key's mode (the sandbox number with a test key, the one live sending number with a live key); with none or several the request is refused and the error lists the choices under numbers. Supports the Idempotency-Key header, including with scheduled_at. A live send from a US local number that is not yet linked to an approved registration (sender.state other than active) is delivered only to your verified numbers; to anyone else it answers 403 sender_not_registered with an X-SimpleSMS-Sender-State header (test_only | pending | action_needed).

Send your API key as a bearer token: Authorization: Bearer ssms_sk_.... Test keys run this endpoint against the sandbox; see Authentication for key modes and scopes.

Headers

Request body

JSON (Content-Type: application/json).

Responses

201: Message fields

Errors

Every error has the same JSON shape, and request_id matches the X-Request-Id response header. Errors lists every code and what to do about it.

{
  "error": {
    "code": "invalid_request",
    "message": "What went wrong, in plain words.",
    "param": "the_field",
    "request_id": "req_a1B2c3D4e5F6g7H8"
  }
}

Idempotency

Send an Idempotency-Key header to make retries safe. For 24 hours the same key with the same body replays the original successful response (with Idempotent-Replayed: true); the same key with a different body returns 409. A failed request releases its key.

Examples

curl

curl -X POST "https://api.joinsimplesms.com/v1/messages" \
  -H "Authorization: Bearer $SIMPLESMS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2f0e-order-1042" \
  -d '{
  "to": "+15005550006",
  "from": "+15005550100",
  "body": "Hello from SimpleSMS"
}'

Node.js

import { SimpleSMS } from 'joinsimplesms'; // npm install joinsimplesms

const sms = new SimpleSMS(process.env.SIMPLESMS_API_KEY);

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

console.log(message.id, message.status);

Python

import os
from joinsimplesms import SimpleSMS  # pip install joinsimplesms

client = SimpleSMS(os.environ["SIMPLESMS_API_KEY"])

message = client.messages.send(
    to="+15005550006",
    body="Hello from SimpleSMS",
    from_="+15005550100",
)

print(message["id"], message["status"])

Related

• Guide: Messages
• All messages endpoints
• API reference