Bring SMS
into your service.

Quick start

1. Create an API key

   After signup, approval, and OTP login, visitAPI key managementto create a key.

2. Add credits

   The API uses your account balance and pricing. Credits are charged when your request is queued.

3. Send and track your messages

   Save the campaign ID and use the status endpoint to track results.

Coverage

GET/api/v1/messages/countries

Use this endpoint to check enabled destinations and your applied prices. Specify country when sending and use numbers from the same country in each request. Destinations without configured pricing are not accepted.

{ "currency": "USDT", "countries": [{ "country": "US", "unitPrice": 0.02 }] }

Authenticate with an API key

Include this header with every API request. Session cookies and OTP codes are not required.

Authorization: Bearer YOUR_API_KEY

The secret is shown only once. Store it in a server environment variable, never in frontend code. Revoked keys and suspended accounts cannot use the API. You can have up to five active keys.

Send to up to 1,000 recipients

Send the same message to multiple recipients. We validate and queue the request before returning a response. For different message content, send separate requests with unique Idempotency-Key values.

Any invalid or duplicate number rejects the entire request without sending or charging. Duplicates are checked after normalization to international format.

curl -X POST 'https://hexsms.com/api/v1/messages' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: notice-20261024-001' \
  -d '{
    "country": "US",
    "text": "Your verification code is 482913.",
    "recipients": ["+12025550123", "+12025550124"]
  }'

{
  "id": "35bed356-b84a-452a-8e94-98b538972ecd",
  "country": "US",
  "state": "RUNNING",
  "total": 2,
  "segments": 1,
  "unitPrice": 0.025,
  "cost": 0.05,
  "createdAt": 1792800000000,
  "note": null,
  "replayed": false
}

How pricing works

Recipients × segments × account unit priceUCS-2 supports 70 characters in one segment, then 67 per segment. Basic GSM-7 supports 160, then 153 per segment. Extension characters count twice; emoji use UTF-16 length. unitPrice and cost are in USDT. The response contains the applied price; 0.025 above is only an example.

Track each recipient

Use the id returned by the send endpoint. Only API campaigns owned by the same account are accessible. This endpoint returns stored results. Call refresh first if you need the latest carrier results.

curl 'https://hexsms.com/api/v1/messages/35bed356-b84a-452a-8e94-98b538972ecd?limit=1&offset=0' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "id": "35bed356-b84a-452a-8e94-98b538972ecd",
  "country": "US",
  "state": "DONE",
  "total": 2, "segments": 1,
  "unitPrice": 0.025, "cost": 0.05,
  "createdAt": 1792800000000, "note": null,
  "summary": { "DELIVERED": 1, "PENDING": 1 },
  "messages": [
    {
      "id": "d2787184-d8b8-49c6-9c15-1db90a6d5516",
      "to": "12025550123",
      "status": "DELIVERED",
      "statusName": "DELIVERED_TO_HANDSET",
      "description": "Message delivered to handset",
      "error": null,
      "updatedAt": 1792800005000
    }
  ],
  "pagination": { "limit": 1, "offset": 0, "nextOffset": 1 }
}

limit is 1–1,000 (default 100); offset is 0–1,000 (default 0). A null nextOffset means the last page. summary counts all recipients by status. to uses international digits without +. Timestamps are Unix milliseconds. Results may differ from input order; identify each message by its id.

Fetch the latest delivery results

Refresh stored results from carrier logs. No request body is needed. Read results with GET afterward. Refresh a campaign at most once every 30 seconds. Carrier logs are available for 48 hours after sending. Configured delivery webhooks may update results automatically.

curl -X POST 'https://hexsms.com/api/v1/messages/35bed356-b84a-452a-8e94-98b538972ecd/refresh' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{ "id": "35bed356-b84a-452a-8e94-98b538972ecd", "updated": 2 }

updated is the number of rows updated. It can be zero while messages are queued or no new results exist. Poll GET at intervals of at least 10 seconds and call refresh only when needed.

Understand status codes

Campaign state

PREPARING: preparing · RUNNING: processing · PAUSED: paused · DONE: queue processed · CANCELED: canceled

Handle unknown status values, as carriers may add new codes. Check statusName, description, and error for failure details.

Handling errors

{ "error": "Insufficient credits. Please top up and retry.", "code": "INSUFFICIENT_CREDITS" }

Each API key allows 120 requests per minute across sending, status, and refresh. Check Retry-After when limited. This API is for server-to-server use; browser CORS calls are not supported.

Connect with Node.js

const response = await fetch('https://hexsms.com/api/v1/messages', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + process.env.HEXSMS_API_KEY,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'notice-20261024-001'
  },
  body: JSON.stringify({
    country: 'US',
    text: 'Your order is on its way.',
    recipients: ['+12025550123', '+12025550124']
  })
});
const result = await response.json();
if (!response.ok) throw new Error(result.code + ': ' + result.error);
console.log(result.id); // Use this ID to check delivery status.

Create a request key once per operation and reuse it for retries. Resending a successful operation with a new key creates another send and charge.