SENDSMSNOW / DEVELOPERS

Your code.
Our messaging.

Bring SMS into your product with a straightforward REST API. Send a message, follow its delivery and keep your customers in the loop.

Start building Get your API token

HTTPS / JSONAPI v1

POST /api/v1/messages

{
  "recipientPhone": "+447700900123",
  "senderName": "YOUR_SENDER",
  "body": "Your order is ready.",
  "requestKey": "YOUR_MESSAGE_UUID"
}

201 Created Message queued. You’re connected.

FROM ZERO TO YOUR FIRST MESSAGE

A few steps. One connection.

All examples use your real account. You need a paid package, confirmed email and phone, an available sender and sufficient credits before sending.

Get your token

Open API token. Confirm your password and copy the token when it appears.

Choose a sender

Call GET /senders and use a returned value as senderName. Replace all example placeholders.

Send & follow

Send your first SMS, keep the returned message ID and check its delivery status.

BASE URLhttps://www.sendsmsnow.com/api/v1

One token. Your account.

Send your token in the Authorization header on every request. Send Accept: application/json and, for POST requests, Content-Type: application/json. Browser cookies and tokens in URLs are not supported.

Authentication header

Authorization: Bearer YOUR_API_TOKEN
Accept: application/json

Keep your token on your server.

Store it as SENDSMSNOW_API_TOKEN in an environment variable or secret manager. Never put it in public frontend code, mobile apps, URLs or source control.

Tokens last 90 days and are shown only when created. Replacing or revoking a token immediately disables the old one. Password changes revoke it too. API access is blocked if your account is suspended, no longer has a paid package, or loses email or phone verification. A token grants messaging and read access, without access to administration, billing changes or account settings.

WORK WITH YOUR STACK

Copy. Connect. Build.

9 languages

Choose an operation and your language. These are ordinary HTTP requests, with no SendSMSnow SDK required. Examples are for server-side applications.

Operation

cURL · POST /messages

# Generate this once per message; keep it for retries.
REQUEST_KEY="$(uuidgen)"
curl --fail-with-body --max-time 30 'https://www.sendsmsnow.com/api/v1/messages' \
  --header "Authorization: Bearer $SENDSMSNOW_API_TOKEN" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data "{\"recipientPhone\":\"+447700900123\",\"senderName\":\"YOUR_SENDER\",\"body\":\"Your order is ready.\",\"requestKey\":\"$REQUEST_KEY\"}"

Replace YOUR_SENDER and the sample recipient before sending. Phone numbers shown here are illustrative. Requests are not executed from this page.

THE REFERENCE

Small surface. Useful building blocks.

GET/account

Check your balance

Read the current plan, billing status and available message credits for the account that owns your token.

Check your balance · 200 response (excerpt)

{
  "account": {
    "planCode": "growth",
    "status": "active",
    "creditsBalance": 1000,
    "currency": "USD"
  }
}

GET/senders

Find your sender

List the sender values currently available to your account. Use one of these values exactly as senderName. An empty list means number setup must be completed in Plans & billing.

Find your sender · 200 response (excerpt)

{
  "senders": [
    {
      "value": "+447700900000",
      "type": "phone"
    }
  ]
}

POST/messages

Send an SMS

Send one message to one international number, immediately or at a future time. Limit: 10 send requests per rolling second per account. If you receive 429, wait for Retry-After and retry with the same requestKey. Credits are reserved before the message is queued. A successful response confirms queueing, not delivery.

recipientPhonestring · required

International number in E.164 format, including + and the country code. For example, +447700900123.

senderNamestring · required

A value returned by GET /senders. Maximum 20 characters.

bodystring · required

Your message, 1–1,600 characters after trimming. Long or Unicode messages can use multiple SMS segments.

requestKeyUUID · required

Generate a new UUID for each new message. Reuse it only when retrying that same message.

recipientNamestring · optional

A display name, up to 80 characters.

scheduledForISO 8601 · optional

A future timestamp with timezone, for example 2027-01-15T10:00:00Z. Omit for immediate sending.

Safe retries with requestKey

Save the UUID before sending. A retry with the same key returns the original message with HTTP 200 and idempotentReplay: true, without another credit reservation. Do not reuse a key for different content. A new message gets HTTP 201. There is no bulk-send operation in this API version.

Send an SMS · 201 response (excerpt)

{
  "message": {
    "id": 12345,
    "recipientPhone": "+447700900123",
    "senderName": "+447700900000",
    "body": "Your order is ready.",
    "status": "queued",
    "segments": 1,
    "errorCode": null,
    "deliveredAt": null
  },
  "state": "queued",
  "stored": true,
  "queued": true,
  "creditsReserved": 1
}

GET/messages/{id}

Track delivery

Replace 12345 with the message.id returned when you send. Read the latest provider status, errorCode and deliveredAt. Only messages belonging to your account are accessible.

Track delivery · 200 response (excerpt)

{
  "message": {
    "id": 12345,
    "recipientPhone": "+447700900123",
    "status": "delivered",
    "segments": 1,
    "errorCode": null,
    "submittedAt": "2026-09-11T09:00:00.000Z",
    "deliveredAt": "2026-09-11T09:00:03.000Z"
  }
}

GET/messages

List your messages

Browse your message history, newest first. page starts at 1; perPage defaults to 25 and accepts 1–100. Content may be removed according to your history settings. Status and operational records remain available.

List your messages · 200 response (excerpt)

{
  "messages": [
    {
      "id": 12345,
      "recipientPhone": "+447700900123",
      "status": "delivered",
      "segments": 1
    }
  ],
  "pagination": {
    "currentPage": 1,
    "lastPage": 1,
    "perPage": 25,
    "total": 1
  }
}

Follow the message, end to end.

queuedacceptedsentdelivered

Provider acceptance and sent do not confirm delivery to the handset. Check status, deliveredAt and errorCode on the message. Updates depend on the provider and destination; delivery reports are not guaranteed for every route.

scheduled / queued / retry: Waiting to send, or waiting for a retry.
submitting / accepted / sending / sent: Submission or provider processing is in progress.
delivered / read: The provider has reported successful delivery or reading where supported.
failed / undelivered / canceled / suppressed: The message failed, was canceled or was blocked from sending.
submission_unknown: The submission result is uncertain. Do not resend with a new key; check again later or contact support.

Poll selectively and back off as time passes. This version supports status polling; customer-configurable delivery webhooks are not included.

Credits follow SMS segments.

One segment reserves one credit. Message length and encoding affect the segment count. Read segments and creditsReserved from the response. Recipient opt-outs, blocked numbers, sender restrictions and platform sending controls also apply to API messages.

Clear errors. Predictable limits.

Handle errors by HTTP status. The description is in message or error; validation responses may also include a field-keyed errors object.

401

Missing, invalid, expired or revoked token. Create a new token if needed.

403

Access blocked: package, account, verification or token permissions need attention.

404

The message does not exist or does not belong to your account.

422

Invalid fields, unavailable sender or provider, recipient restrictions, or insufficient credits. Review the response before retrying.

429

Rate limit reached. Wait for the Retry-After interval before trying again.

503

Sending is temporarily paused or the service is unavailable. Retry later with the same requestKey.

120 / minute

Read requests per account.

10 / second

SMS send requests per account, across all tokens.

POST /messages allows 10 send requests in any rolling one-second window per account. Each request sends to one recipient; invalid requests and retries also count. Excess requests receive HTTP 429 before any SMS is queued or credits are reserved. Wait at least the Retry-After interval (1 second for the send limit), then retry with the same requestKey. Read requests have a separate 120/minute allowance. A shared network is limited to 1,200 total requests per minute per IP. Observe X-RateLimit-Limit, X-RateLimit-Remaining and Retry-After when returned. On connection errors or server errors, retry with backoff and the same message UUID.