Bulk SMS API reference for Sri Lanka

The REST API for sending bulk SMS in Sri Lanka with e-SMS. JSON in, JSON out, over HTTPS, at a flat Rs 0.99 per SMS segment (see pricing). Every request carries an API token you generate in the dashboard under API tokens.

Authorization: Bearer 12|your-token-here Content-Type: application/json Accept: application/json

Successful responses carry "status": "success" and a data object. Failures carry "status": "error" and a readable message. A 402 means you ran out of credits.

Send a message

POST /api/v3/sms/send

Parameter	Description
recipient required	One number, or several separated by commas. Local formats such as 0712345678 are accepted and normalised to 94712345678.
sender_id required	An approved sender name on your account.
type	`plain` or `unicode`. Left out, the encoding is detected from the message.
message required	The body of the SMS.
schedule_time	Send later, in `YYYY-MM-DD HH:MM`.

curl -X POST https://esms.lk/api/v3/sms/send \ -H 'Authorization: Bearer 12|your-token-here' \ -H 'Content-Type: application/json' \ -d '{ "recipient": "94710000000,94770000000", "sender_id": "YourBrand", "message": "Your order #4821 is out for delivery." }'

Response

{ "status": "success", "data": { "uid": "a91f3c7d2e04", "uids": ["a91f3c7d2e04", "b72e1d9a5c83"], "to": "94710000000,94770000000", "sms_count": 1, "cost": 2, "status": "Queued" } }

sms_count is the segments in one message; cost is the total credits taken, which is segments multiplied by recipients.

Cost a message without sending

POST /api/v3/sms/estimate

Same body as a send. Returns the segment count, encoding and credits required. Useful before a large batch.

Send to a contact group

POST /api/v3/sms/campaign

Parameter	Description
contact_list_id required	The group ID from `GET /api/v3/contacts`.
sender_id required	An approved sender name.
message required	The body of the SMS.
schedule_time	Send later, in `YYYY-MM-DD HH:MM`.

Look up one message

GET /api/v3/sms/{uid}

{ "status": "success", "data": { "uid": "a91f3c7d2e04", "to": "94710000000", "from": "YourBrand", "message": "Your order #4821 is out for delivery.", "sms_type": "plain", "status": "Delivered", "sms_count": 1, "cost": 1, "sent_at": "2026-09-12 14:22:08" } }

List messages

GET /api/v3/sms

Query	Description
start_date	Filter from this date and time.
end_date	Filter up to this date and time.
sms_type	`plain` or `unicode`.
direction	`api` or `dashboard`.
page	Page number. 25 per page by default.

Check your credits

GET /api/v3/balance

{ "status": "success", "data": { "remaining_sms_unit": 4820, "rate": 0.99, "currency": "LKR" } }

Your contact groups

GET /api/v3/contacts

Returns the groups on your account with their IDs and contact counts.

Rate limits

120 requests a minute per token. Beyond that you get a 429 with a RateLimit-Reset header telling you how long to wait.

Errors

Code	Meaning
401	The token is missing, malformed or revoked.
402	Not enough credits for this send.
422	Something in the request is wrong; the message says what.
429	Rate limited.
500	Our side failed. The credits are not taken.