Sending Messages
Using Twilio's REST API, you can send outgoing SMS messages from your Twilio phone number to mobile phones around the globe.
In this guide, we'll explore how you can use Twilio's Programmable Messaging API to:
Prefer a step-by-step guide to sending your first message? Check out our Programmable SMS quickstart in C#, Java, Node.js, PHP, Python, Ruby, or Go.
You can also find the full API reference for the Message resource here.
If you're looking to send and verify One-Time Passcodes (OTPs) via SMS, check out our Verify APIs for phone verification and 2FA.
Send an SMS with Twilio's API
To send a new outgoing message from a Twilio phone number to an outside number, make an HTTP POST to your account's Message resource:
/2010-04-01/Accounts/{AccountSid}/Messages
You can post directly to the API with cURL or use one of our six supported helper libraries to send messages with C#, Java, Node.js, PHP, Python, Ruby, or Go.
When creating a new message via the API, include the parameters To
, From
, and Body
.
To
This parameter determines the destination phone number for your SMS message. Format this number with a '+' and a country code, e.g., +16175551212
(E.164 format).
If you send messages while in trial mode, you must first verify your 'To' phone number so Twilio knows you own it. If you attempt to send an SMS from your trial account to an unverified number, the API will return Error 21219.
You can verify your phone number by adding it to your Verified Caller IDs in the console.
From
From
specifies the Twilio phone number, short code, or Messaging Service that sends this message. This must be a Twilio phone number that you own, formatted with a '+' and country code, e.g. +16175551212
(E.164 format).
To get your first Twilio phone number, head on over to the console and find a number you like with SMS capabilities. If you're interested in using a short code, you can apply for one via the console as well.
Note that you cannot spoof messages from your personal cell phone number without porting your number to Twilio first. Learn more here.
Tip: Send a Message from a Messaging Service
You can also enter a Messaging Service SID as the From
parameter value when you send an SMS message. When you use a Messaging Service SID, Twilio will automatically send your message using one of the phone numbers in your service pool.
A messaging service is like a container for your phone numbers, bundled around common use cases, such as routing intelligence and content features. For more information, check out the guide on Sending SMS Messages from a Messaging Service.
Body
The Body
parameter includes the full text of the message you want to send, limited to 1600 characters.
Twilio will verify that you've included a valid Twilio phone number in the From
parameter, and then either queue the call or return an error.
Check out the full API Reference for Messages for the full list of parameters you can include in your request. You can also find the parameters you can expect back from Twilio.
Monitor the status of your message
By including a StatusCallback
URL in your API call, you can tell Twilio where to POST information about your message.
Please note that Twilio will make a POST request to your StatusCallback
URL.
Twilio will POST to this URL each time the status of your message changes to one of the following:
- queued
- failed
- sent
- delivered
- undelivered
The parameters Twilio sends to your callback URL include a subset of the standard request parameters and some unique messaging parameters. You can see the full list in the API Reference for the Message resource.
Below is an example of the request parameters sent to the StatusCallback URL for a delivered message:
{
"SmsSid": "SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"SmsStatus": "delivered",
"MessageStatus": "delivered",
"To": "+15558675310",
"MessageSid": "SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"AccountSid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"From": "+15017122661",
"ApiVersion": "2010-04-01"
}
Include media in your messages
While you can send text-only messages almost anywhere on the planet, sending media is currently only available in the US and Canada.
Sending an MMS message looks a lot like sending an SMS, but it includes a new parameter, MediaUrl
. This parameter specifies the URL of the media you want to include with your message.
Twilio supports .gif
, .png
, or .jpeg
content and will format the image on your recipient's device. If the content-type header of your MediaUrl
does not match the media at that URL, Twilio will reject the request.
Other MIME types are accepted by the API, but will not be modified for device capability.
The size limit for message media is 5MB.
To send more than one image in a message body, provide multiple MediaUrl
values in your POST request (limited to 10 per message).
Use an Alphanumeric Sender ID
Alphanumeric sender IDs are used for branded one-way messaging. Instead of using an E.164 formatted Twilio phone number for the "From" value, you can use a custom string like your own business' branding. Alphanumeric sender IDs may be used at no additional cost when sending an SMS to countries that support this feature.
Support for sending messages from an alphanumeric sender ID depends on your destination (‘To’) phone number and is not available everywhere. Please see this article for the full list of countries that support this feature.
A note on rate limiting
If you send multiple messages at once from a single Twilio sender (number or Alphanumeric Sender ID), Twilio will queue them up for delivery. Your messages may experience differing rate limits based on the sender you are using. For messages from a US or Canada long code number, the limit is one message segment per second (MPS). If you're sending messages from a non-US or Canada long code number, or an Alphanumeric Sender ID, the upper limit is 10 MPS.
API requests for messages that exceed the specified rates will be queued and executed at the sending rate of your Twilio sender.
If your application tries to enqueue more than 4 hours' worth of outbound traffic from a single sender (e.g., enqueuing more than 14,400 message segments to Canada over one long code phone number), the excess messages will fail with error 30001 (Queue Overflow).
If you need to increase your outbound SMS throughput, we recommend using a Messaging Service.
Are you planning to send out a large number of messages at a rate greater than one message per second? Consider applying for a short code.
Short codes are not subjected to the same rate limits as long-code numbers and may be a better option for you.
What's next?
- Dive into the API Reference documentation for Twilio SMS.
- Turn your messages into a conversation with our Create an SMS Conversation guide for C#, Java, Node.js, PHP, Python, or Ruby.
- Learn how to track the delivery status of messages you send with C#, Java, Node.js, PHP, Python, or Ruby.
- Optimize your message deliverability by sending Message Feedback to Twilio.
Need some help?
We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.