Get Started

REST API: Sending SMS Messages

The SMS Messages resource has been deprecated, replaced by the Messages resource, and may be removed in future versions of the Twilio API. Check out how to send an SMS or MMS using the new Messages resource.

Since initiating outbound SMS messages via the REST API is such a frequent task, it get its own section. Huzza!

HTTP POST to SMS/Messages

To send a new outgoing SMS message, make an HTTP POST to your SMS/Messages list resource URI:

/2010-04-01/Accounts/{AccountSid}/SMS/Messages

POST Parameters

Required Parameters

The following parameters are required in your POST to send the SMS:

Parameter Description
From A Twilio phone number enabled for SMS. Only phone numbers or short codes purchased from Twilio work here; you cannot (for example) spoof SMS messages from your own cell phone number.
To The destination phone number. Format with a '+' and country code e.g., +16175551212 (E.164 format). For 'To' numbers without a '+', Twilio will use the same country code as the 'From' number. Twilio will also attempt to handle locally formatted numbers for that country code (e.g. (415) 555-1212 for US, 07400123456 for GB). If you are sending to a different country than the 'From' number, you must include a '+' and the country code to ensure proper delivery.
Body The text of the message you want to send, limited to 160 characters.
If you are sending SMS while in Trial mode, the 'To' phone number must be verified with Twilio.
Optional Parameters

You may include the following parameters:

Parameter Description
StatusCallback A URL that Twilio will POST to when your message is processed. Twilio will POST the SmsSid as well as SmsStatus=sent or SmsStatus=failed.
ApplicationSid Twilio will POST SmsSid as well as SmsStatus=sent or SmsStatus=failed to the URL in the SmsStatusCallback property of this Application. If the StatusCallback parameter above is also passed, the Application's SmsStatusCallback parameter will take precedence.

Example

Send an SMS from 415-814-1829 to 415-935-2345 begging Jenny for a second chance:

Rate limiting

You can queue as many messages as you like, however Twilio will only send out SMS messages at a rate of one message per phone number per second. It is not possible to adjust this rate, and it does not vary based on the country in which your number is located.

If you anticipate the need to send out a large number of messages quickly (a time-limited promotion, for example) or at a rate greater than one message per second, you can purchase additional numbers, increasing your outbound capacity.

Short codes are not subject to the same rate limits as long-code numbers and may be a better option for you. Check out our short code FAQ or talk to our sales team to determine what is best for you.

Handling SMS Replies

By specifying an SMS URL for your SMS enabled Twilio phone number, Twilio will make a request to your application to notify you when someone replies to a message you send. Twilio's request and your corresponding response are covered in the SMS portion of the TwiML documentation.