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.


Send a message from 415-814-1829 to 651-867-5309 wishing your friend Jenny good luck on the bar exam, along with an image of a hamster eating a four-leaf clover. Note that while you can send text-only messages just about anywhere on the planet, sending images is currently only possible in the US and Canada:

HTTP POST to Messages

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


POST Parameters

Required Parameters

The To parameter is required in your POST to send the message:

ToThe destination phone number. Format with a '+' and country code e.g., +16175551212 (E.164 format).
If you are sending messages while in trial mode, the 'To' phone number must be verified with Twilio.
Conditional Parameters

You must POST at least one of the following parameters to determine the 'From' phone number or Sender ID of your message:

FromA Twilio phone number (in E.164 format) or alphanumeric sender ID enabled for the type of message you wish to send. Phone numbers or short codes purchased from Twilio work here. You cannot (for example) spoof messages from your own cell phone number.
MessagingServiceSidThe 34 character unique id of the Messaging Service you want to associate with this Message. Set this parameter to use the Messaging Service Settings and Copilot Features you have configured. When only this parameter is set, Twilio will use your enabled Copilot Features to select the From phone number for delivery.

There is a slight difference in API response when specifying the MessagingServiceSid parameter. When you only specify the From parameter, Twilio will validate the phone numbers synchronously and return either a queued status or an error. When specifying the MessagingServiceSid parameter, Twilio will first return an accepted status. Twilio then determines the optimal From phone number and any delivery errors will be sent asynchronously to your StatusCallback URL.

You must also POST at least one of the following parameters for the content of your message:

BodyThe text of the message you want to send, limited to 1600 characters.
MediaUrlThe 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 GSM-7 characters (or 70 UCS-2 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.

Optional Parameters

You may include the following parameters:

StatusCallbackA URL that Twilio will POST to each time your message status changes to one of the following: queued, failed, sent, delivered, or undelivered. Twilio will POST the MessageSid along with the other standard request parameters as well as MessageStatus and ErrorCode. If this parameter passed in addition to a MessagingServiceSid, Twilio will override the Status Callback URL of the Messaging Service.
ApplicationSidTwilio 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.
MaxPriceThe total maximum price up to the fourth decimal (0.0001) in US dollars acceptable for the message to be delivered. All messages regardless of the price point will be queued for delivery. A POST request will later be made to your Status Callback URL with a status change of 'Sent' or 'Failed'. When the price of the message is above this value the message will fail and not be sent. When MaxPrice is not set, all prices for the message is accepted. This parameter is not available when sending with a Messaging Service.
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:

MessageStatusThe status of the message. Message delivery information is reflected in message status. The possible values are described here.
ErrorCodeThe 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.

Messaging Services

As you use Twilio Messaging to power different use cases, it may be helpful to organize your account and message logs into separate Messaging Services. Messaging Services allow you to organize your messages and enable specific features for these groups of messages. This keeps your code clean and let’s you adjust messaging configuration right from your Account Portal.

With every Messaging Service, you start by configuring the Inbound Request URL and Status Callback URL. For advanced configuration, Twilio Copilot Features are available to add intelligence to your application.

When sending messages, you must associate one or more phone numbers and/or short codes to your Messaging Service. One of the phone numbers in your Messaging Service will be chosen based on the enabled Copilot Features whenever you send an outbound message.

Alphanumeric Sender ID

Alphanumeric sender IDs are used for branded one-way messaging. Alphanumeric s ender IDs may be used at no additional cost when sending an SMS to countries that are supported. Accepted characters include both upper- and lower-case ASCII letters, the digits 0 through 9, and space: [A-Za-z0-9 ]. When using an alphanumeric sender ID, at least 1 letter and no more than 11 alphanumeric characters may be used.

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.