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.
To send a new outgoing message, make an HTTP POST to your Messages list resource URI:
/2010-04-01/Accounts/{AccountSid}/Messages
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.
If you send a message with a MediaUrl to a recipient whose carrier does not support MMS, the message will be sent as an SMS with a shortened URL linking to your media (http://m.twil.io/ followed by 7 unique characters) appended to the end of the message body. The URL will remain active for 7 days. Messages sent in this way will be billed as SMS. If the appended URL causes the body of the text message to be greater than 160 characters, the message will be segmented and charged accordingly. Should you wish to disable this functionality, you can do so through the account settings page in the portal.
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.
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. |
Each time a message status changes, Twilio will make an asynchronous HTTP request to the StatusCallback URL, if you provided one.
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. |
Send a Message from 415-814-1829 to 555-867-5309 begging Jenny for a second chance including a heart image:
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.
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.