# SMS Gateway API The eCommunicate **SMS Gateway** (Payless4SMS) is a direct HTTP/JSON API for sending single and bulk SMS, tracking delivery, receiving replies and delivery receipts, scheduling messages, and managing your credit balance. It is a standalone product, separate from the WhatsApp-centric [Omnichannel Integration API](./omnichannel.yaml). Use this API when you need plain SMS to any mobile network. ## Authentication Every request is authenticated with an **API key**: send an `X-API-Key: ecomm_...` header. Generate and revoke keys from the client portal (**API Keys**). Always use HTTPS so the key is never sent in the clear. ## High-priority (OTP) traffic For one-time-pin traffic that must deliver in 5–10 seconds, request an OTP token from support and send it as an `otpToken` header. Valid tokens are routed to a dedicated priority queue with automatic backup-gateway fallback. If the response `statusCode` is `502`, resend via your backup gateway until it returns to `100`. ## Status codes Responses carry a string `statusCode` and `statusDescription`. Common values: `001` Request Completed · `021` Authentication Failed · `022` Invalid Parameters · `023` Missing Parameters · `100` Accepted For Processing · `126` Blacklisted Destination · `128` Invalid Destination · `129` Duplicate Destination · `136` Batch Size Exceeded (max 1000 recipients) · `137` Insufficient Credits · `201` Batch Scheduled · `500` Message Sent · `501` Queued At MNO · `600` Delivery Success · `620` Failed In Delivery. The gateway sometimes returns equivalent alternates (e.g. Invalid Destination `128`/`226`), so treat `statusCode` as an opaque string. Direct bulk & transactional SMS over a simple HTTP JSON API. Version: 1.31 ## Servers Production ``` https://api.payless4sms.com ``` Production (alternate host) ``` https://api.ecommunicate.co.za ``` ## Security ### ApiKeyAuth API key issued to a client or reseller, prefixed `ecomm_`. Required on every request. Generate and revoke keys from the client portal. Type: apiKey In: header Name: X-API-Key ## Download OpenAPI description [SMS Gateway API](https://docs.ecommunicate.co.za/_bundle/apis/sms.yaml) ## Messaging Send single and bulk SMS. ### Send SMS (JSON) - [POST /sms/json](https://docs.ecommunicate.co.za/apis/sms/messaging/sendsms.md): Send a single message, the same message to many recipients, or many messages to many recipients. Keep each request to a maximum of 1000 recipients and send the next request only after receiving the previous response. Also available over GET /sms/json (query parameters) for quick testing. ### Send SMS (query parameters) - [GET /sms/json](https://docs.ecommunicate.co.za/apis/sms/messaging/sendsmsget.md): A convenience form for quick testing. Send the same text to one or more destinations (comma-separated to). POST is recommended for production — it is not length-limited. ## Tracking Query delivery status and delivery receipts. ### Track message status - [POST /sms/trackingMessageStatus](https://docs.ecommunicate.co.za/apis/sms/tracking/trackingmessagestatus.md): Query delivery status and receipts. Filter by time range (startDate/endDate), by ctid + sentDate, by stid, or by the global ids gctid/gstid. Add showfinalstatus=true to return only final states. Rate limited to 10 queries per id in the first 10 minutes, then once per 10 minutes. Also available over GET. ### Get receipts for a recipient - [GET /sms/getReceiptsForRecipient](https://docs.ecommunicate.co.za/apis/sms/tracking/getreceiptsforrecipient.md): Return delivery receipts for one recipient over a date range. ## Replies Retrieve inbound reply messages. ### Get inbound replies - [POST /sms/getReply](https://docs.ecommunicate.co.za/apis/sms/replies/getreply.md): Retrieve reply messages received over a time range. Set includeSentSms to attach the last message sent to each replier. Also available over GET. ## Scheduling Schedule and cancel future SMS. ### Cancel scheduled SMS - [POST /sms/deleteScheduledSMS](https://docs.ecommunicate.co.za/apis/sms/scheduling/deletescheduledsms.md): Delete scheduled (not-yet-sent) messages by stid + destination, by ctid, by a ctids array, by time range (startDate/endDate), or all of them with deleteall. Also available over GET. ## Account Credit balance, server time, unsubscribes, and SMSC status. ### Get credit balance - [POST /sms/getBalance](https://docs.ecommunicate.co.za/apis/sms/account/getbalance.md): Return the current credit balance. Authenticated by the X-API-Key header; no request body is required. Also available over GET. ### Get unsubscribed numbers - [POST /sms/getUnsubscribelist](https://docs.ecommunicate.co.za/apis/sms/account/getunsubscribelist.md): Return numbers that have unsubscribed / been blacklisted over a date range. Recipients who reply STOP, END, CANCEL, QUIT, or UNSUBSCRIBE are blacklisted automatically. ### Get server time - [POST /sms/getServerTime](https://docs.ecommunicate.co.za/apis/sms/account/getservertime.md): Return the gateway's current server time. Authenticated by the X-API-Key header; no request body is required. Also available over GET. ### Set SMSC status webhook URL - [GET /SMS/client/setSmscStatusCallbackUrl](https://docs.ecommunicate.co.za/apis/sms/account/setsmscstatuscallbackurl.md): Register a URL that the gateway calls with real-time SMSC connectivity events. See the SMSC status webhook. ### Get current SMSC status - [GET /SMS/client/getSmscStatus](https://docs.ecommunicate.co.za/apis/sms/account/getsmscstatus.md): Return the current SMSC connectivity status. ## Webhooks Callbacks the gateway sends to your server (delivery receipts, replies, SMSC status). ### Delivery receipt - [GET deliveryReceipt](https://docs.ecommunicate.co.za/apis/sms/webhooks/ondeliveryreceipt.md): When a receiptCallBackURL is configured, the gateway performs an HTTP GET to it as delivery status changes. Return HTTP 200. Undelivered callbacks are retried for up to 24 hours (2m, 4m, 8m … 1440m). ### Inbound reply - [POST reply](https://docs.ecommunicate.co.za/apis/sms/webhooks/onreply.md): When a replyCallBackURL is configured, the gateway forwards inbound replies. This shows the POST form; a GET form (?gstid=&ctid=&date=&from=&message=) is also supported. Return HTTP 200. ### SMSC status - [GET smscStatus](https://docs.ecommunicate.co.za/apis/sms/webhooks/onsmscstatus.md): Real-time SMSC connectivity events sent to the URL registered via Set SMSC status webhook URL. Return HTTP 200.