Skip to main content
500CallsDocs
Browse the docs

Send one SMS (deprecated)

POST/v1/messages

Deprecated: use POST /v1/sms/messages, which takes the same body and gives the same responses. Every response carries the Deprecation and Sunset headers, which give the removal date, and a Link header to the migration guide.

Scope
messages:send

Request

Every request needs an API key in the Authorization header, and the key needs the scope the endpoint names.

Parameters

  • Idempotency-Keyheaderstring

    1 to 64 characters from A-Z, a-z, 0-9, _ and -. Repeating a request with the same key and body within 24 hours returns the stored success response without acting again; the same key with a different body is refused with 409.

    • Matches ^[A-Za-z0-9_-]{1,64}$

Body

  • tostringRequired

    The recipient, in any common Nigerian or international format, such as 08031234567 or +2348031234567.

    • At most 256 characters
  • fromstringRequired

    The sender ID: 3 to 11 letters, digits, spaces, hyphens or periods. It must be one of yours that can be used now.

    • 3 to 11 characters
    • Matches ^[A-Za-z0-9 .-]+$
  • bodystringRequired

    The message text, sent exactly as given. Placeholders such as {{name}} are not filled in; send a batch to personalise.

  • client_referencestringor null

    Your own reference: 1 to 64 printable ASCII characters. You can filter messages by it.

    • 1 to 64 characters
    • Matches ^[\x20-\x7e]+$
  • send_atstring (date-time)or null

    Schedule the send for this time, between 1 minute and 90 days from now. Omit it to send now.

Example body
{  "to": "08031234567",  "from": "ACME",  "body": "Your ACME code is 482913. It expires in 5 minutes.",  "client_reference": "order-78123"}

Responses

202 Accepted

ReturnsMessageEnvelope

Headers

  • Cache-ControlstringRequired

    Responses are never cached.

  • DeprecationstringRequired

    This endpoint is deprecated. A request refused before it reaches the endpoint (413, 415) has none.

  • Idempotent-Replayedstring

    Present when this is the stored response of an earlier request with the same Idempotency-Key.

  • LinkstringRequired

    The migration guide, as <url>; rel="deprecation". A request refused before it reaches the endpoint (413, 415) has none.

  • LocationstringRequired

    The new message's URL, /v1/messages/{id}.

  • RateLimit-Limitinteger

    Requests per second your account may sustain.

  • RateLimit-Remaininginteger

    Whole requests left in your account's bucket.

  • RateLimit-Resetinteger

    Seconds until the bucket is full again.

  • SunsetstringRequired

    The HTTP-date after which this endpoint may be removed. A request refused before it reaches the endpoint (413, 415) has none.

  • X-Request-IdstringRequired

    This request's ID, also given as request_id in error bodies. Quote it to support.

Example response
{  "data": {    "id": "msg_01M3KR6CEGVQVV5PV6Q9J1G6SP",    "object": "message",    "amount": null,    "body": "Your ACME code is 482913. It expires in 5 minutes.",    "campaign_id": null,    "channel": "sms",    "client_reference": "order-78123",    "completed_at": null,    "created_at": "2026-09-28T10:15:30.000Z",    "currency": "NGN",    "direction": "outbound",    "encoding": "gsm7",    "error": null,    "from": "ACME",    "held_amount": "3.5000",    "mode": "live",    "scheduled_at": null,    "segments": 1,    "sent_at": null,    "source": "api",    "status": "queued",    "to": "+2348031234567",    "unit_price": null,    "updated_at": "2026-09-28T10:15:30.000Z"  }}

Errors

Each code links to its page. Branch on the code, never on the title or detail.

Example 422 response
{  "type": "https://docs.messaging.500calls.com/errors/validation_error",  "title": "Validation error",  "status": 422,  "code": "validation_error",  "detail": "No recipient could be accepted. No message was created.",  "request_id": "req_01M3KR6CQ26S90NG2V790GVFTX",  "errors": [    {      "field": "to",      "code": "invalid_recipient",      "message": "Not a valid mobile number."    }  ]}

Code samples

Each sample reads your key from the API_KEY_500CALLS environment variable.

cURL
curl -X POST 'https://api.messaging.500calls.com/v1/messages' \  -H "Authorization: Bearer $API_KEY_500CALLS" \  -H 'Content-Type: application/json' \  -H 'Idempotency-Key: order-78123-otp' \  -d '{  "to": "08031234567",  "from": "ACME",  "body": "Your ACME code is 482913. It expires in 5 minutes.",  "client_reference": "order-78123"}'
Python
import osimport requestsresponse = requests.post(    "https://api.messaging.500calls.com/v1/messages",    headers={        "Authorization": f"Bearer {os.environ['API_KEY_500CALLS']}",        "Idempotency-Key": "order-78123-otp",    },    json={        "to": "08031234567",        "from": "ACME",        "body": "Your ACME code is 482913. It expires in 5 minutes.",        "client_reference": "order-78123",    },    timeout=30,)print(response.status_code, response.json())
Node.js
const response = await fetch("https://api.messaging.500calls.com/v1/messages", {  method: "POST",  headers: {    Authorization: `Bearer ${process.env.API_KEY_500CALLS}`,    "Content-Type": "application/json",    "Idempotency-Key": "order-78123-otp",  },  body: JSON.stringify({    "to": "08031234567",    "from": "ACME",    "body": "Your ACME code is 482913. It expires in 5 minutes.",    "client_reference": "order-78123"  }),});console.log(response.status, await response.json());
PHP
<?php$curl = curl_init('https://api.messaging.500calls.com/v1/messages');curl_setopt_array($curl, [    CURLOPT_CUSTOMREQUEST => 'POST',    CURLOPT_HTTPHEADER => [        'Authorization: Bearer ' . getenv('API_KEY_500CALLS'),        'Content-Type: application/json',        'Idempotency-Key: order-78123-otp',    ],    CURLOPT_POSTFIELDS => json_encode([        'to' => '08031234567',        'from' => 'ACME',        'body' => 'Your ACME code is 482913. It expires in 5 minutes.',        'client_reference' => 'order-78123',    ]),    CURLOPT_RETURNTRANSFER => true,]);$body = curl_exec($curl);$status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);echo $status, PHP_EOL, $body, PHP_EOL;