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 SMS API to:
You can also find the full API reference for the Message resource here.
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:
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 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). You can also use a Messaging Service SID.
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.
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.
By including a
StatusCallback URL in your API call, you can tell Twilio where to POST information about your message.
Twilio will POST to this URL each time the status of your message changes to one of the following:
The parameters Twilio sends to your callback URL include all its standard request parameters and some unique messaging parameters. You can see the full list in the API Reference for the Message resource.
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 .
.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).
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.
To learn more about Alphanumeric Sender IDs, see the support article on getting started with Alphanumeric Sender ID.
If you send multiple messages at once via the API, Twilio will queue them up for delivery. Your messages may experience differing rate limits based on the message destination. For messages with destinations in the US and Canada, the limit is one message per second (MPS). If you're sending messages internationally, the upper limit is 10 MPS.
API requests for messages that exceed the specified rates will be queued and executed as capacity is available.
If your application tries to enqueue more than 4 hours worth of outbound traffic (e.g., enqueuing more than 14,400 messages to Canada over one long code phone number), the API will start returning
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? You can get more phone numbers to increase your outbound capacity, or consider using 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.
- 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.