Get Started

REST API: Sending SMS or MMS

Sending an SMS or MMS is one of the most common tasks performed on the Twilio Platform. Sending a message is as simple as POST-ing to the Messages resource but since it’s a common action it’s worth walking through in detail below.

HTTP POST to Messages

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

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

POST Parameters

Required Parameters

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

Parameter Description
From A Twilio phone number enabled for the type of message you wish to send. Only phone numbers or short codes purchased from Twilio work here; you cannot (for example) spoof 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.

You must also POST at least one of the following parameters:

Parameter Description
Body The text of the message you want to send, limited to 1600 characters.
MediaUrl The URL of the media you wish to send out with the message. gif , png and jpeg content is currently supported and will be formatted correctly on the recipient's device. Other types are also accepted by the API. The media size limit is 5MB. If you wish to send more than one image in the message body, please provide multiple MediaUrls values in the POST request. You may include up to 10 MediaUrls per message.

If you are sending non-BMP characters in the message Body the number of characters could be smaller than 1600. Almost all global languages are supported without the use of the non-BMP character plane.

Note that if you do not specify a MediaUrl and the body is greater than 160 characters, the message will be sent as SMS, segmented and charged accordingly.

Content types for MediaUrl validation are fetched via the content-type header at the provided URLs. If the content-type header does not match the media, Twilio will reject the request. Twilio supports image/gif, image/png, and image/jpeg mime-types and accepts many others.

If you are sending messages 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 each time your message status changes to one of the following: failed, sent, delivered, or undelivered. Twilio will POST the MessageSid along with the other standard request parameters as well as MessageStatus and ErrorCode.
ApplicationSid Twilio will POST MessageSid as well as MessageStatus=sent or MessageStatus=failed to the URL in the MessageStatusCallback property of this Application. If the StatusCallback parameter above is also passed, the Application's MessageStatusCallback parameter will take precedence.

StatusCallback Parameter

Each time a message status changes, Twilio will make an asynchronous HTTP request to the StatusCallback URL, if you provided one.

Request Parameters

The parameters Twilio passes to your application in its request to the StatusCallback URL include all the standard request parameters and these additional parameters:

Parameter Description
MessageStatus The status of the message. Message delivery information is reflected in message status. The possible values are described here.
ErrorCode The error code (if any) associated with your message. If your message status is failed or undelivered, the ErrorCode can give you more information about the failure. If the message was delivered successfully, no ErrorCode will be present. The possible values are described here.

Example

Send a Message from 415-814-1829 to 555-867-5309 begging Jenny for a second chance including a heart image:

Rate limiting

You can queue as many messages as you like, however Twilio will only send out 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 to determine what is best for you.

Handling Message Replies

By specifying an Message URL for your messaging 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 Message portion of the TwiML documentation.