SMS API Documentation
Our API allows you to build applications that can send SMS. Here’s how to get started.
Endpoint and format
Use the API by sending an HTTP POST to the following URL:
You can also substitute .xml at the end of the URL if you prefer responses to be formatted in XML rather than JSON.
You’ll need your API credentials to authenticate. You can find those on the "API Settings" page under "Configuration".
Use the Basic authentication method, specifying your API key as the username, and API secret as the password. At the protocol level, this means joining the API key and secret with a colon (:), Base64 encoding it, and sending the resulting string in the HTTP Authorization header.
For example, if your API key is “xyz123” and API secret is “t0ps3cret“, you calculate the Base64 of “xyz123:t0ps3cret“. The resulting header is:
Authorization: Basic eHl6MTIzOnQwcHMzY3JldA==
Send your request as a regular application/x-www-form-urlencoded POST; this is the default in most instances. The body contains key–value pairs separated by equals signs, joined by ampersands. The keys and values should be escaped, replacing spaces with plus symbols, and URL encoding all other non-alphanumeric characters.
An overview of the parameters follows.
- The body of the SMS. An SMS message can be up to 925 characters; after the first 160 characters, each additional 153 characters will cost an additional credit per SMS.
- to and/or list_id(required)
- The destination for the SMS. At least one of to or list_id must be specified, or both.to takes a comma-separated list of phone numbers; they should be in international (E.164) format, although local numbers will work if in the correct format for the country specified in your Account Details.list_id expects the ID of a contact list, whose opted-in recipients will receive the message.
- The time when the message should be sent. If omitted, the message is sent immediately. The time should be specified in the format YYYY-MM-DD HH:MM:SS or YYYY-MM-DD (implies midnight), and is interpreted as in UTC.
- The Caller ID for the message. This can be up to 11 alphanumeric characters. If omitted, one of our system numbers will be used; this is required if you want recipients to be able to reply to the message, unless you have a dedicated number and specify it here.
- A URL for delivery callback reports. When a message is delivered, we’ll send a GET request to this URL. Details follow in the next section.
- A URL for reply callbacks. When a message is replied to, we’ll send a GET request to this URL. See below.
- The maximum time we’ll attempt to deliver the message before giving up. Specify the number in minutes; 0 implies no limit.
Assuming everything went well, you’ll receive an HTTP 200 response with JSON or XML body, depending on how you called the API. The body will have the following keys (or elements):
- The ID of the message batch.
- The time the message batch will be sent. The format is YYYY-MM-DD HH:MM:SS, and represents a date and time in UTC.
- The number of recipients that will receive the message, including contact list contacts if list_id was specified.
- The cost to you in credits of sending this batch. This will depend on the number of recipients and length of message.
- An object describing statistics regarding the messages in the batch. The keys are delivered, pending, bounced, responses, and optouts. All keys will have zero values, except pending, which will equal the recipient count.
- An object with two keys: code, which will have the value SUCCESS, and description. In case of error, a non-200 response will be returned, and this object can be used to find out what’s gone wrong.
When a message is delivered or replied to, we can notify a web service. We make a GET request to the URL of your choice, adding the query parameters detailed below. You can specify a URL with a query string, and we’ll simply append our parameters to those.
Delivery callbacks, sent to the URL specified in the dlr_callback parameter of the send-sms request, are generated whenever the delivery status of a message changes. We’ll add the following parameters to the URL:
- The batch ID of the message. You can use this together with mobile to track delivery reports for the same message, and to correlate it with later replies.
- The destination mobile number in E.164 format, with the leading plus symbol removed.
- The date and time the delivery report was received. The format is YYYY-MM-DD HH:MM:SS.
- The delivery status of the message. This will be one of pending (yet to be delivered), delivered (successfully delivered to the device), or hard-bounce (the message was rejected by the carrier; the destination number may not exist).
Reply callbacks, sent to the URL specified in the reply_callback parameter of the send-sms request, are generated when a reply to a message has been received. Note that the message must have been sent without a Caller ID specified (the from parameter), or with a number that correlates to a dedicated number you have in your account.
The following parameters are added to the URL for replies:
- The batch ID of the message. This is the same ID that you will have earlier received delivery callbacks for, if you specified a URL for delivery callbacks.
- The source mobile number in E.164 format, with the leading plus symbol removed.
- The date and time the reply was received. The format is YYYY-MM-DD HH:MM:SS.
- The text of the message that was received.
If you schedule a message for future sending with send_at, you can cancel it up until 5 minutes before the scheduled sending time. Send a POST to the following URL:
Send your request as above. This endpoint accepts only one endpoint: id. This is the same as the message_id returned by send-sms above.
You can get your current balance by sending a POST to the following URL:
It takes no parameters. Your credit balance is returned in the balance key as a number.