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. If you wish to send more than one image in the message body, please provide multiple MediaUrl values in the POST request. |
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.
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 MessageSid along with the other standard request parameters as well as MessageStatus equal to the value queued, sending, sent, or failed |
| 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. |
Send an 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.