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:

• Send an SMS message from your Twilio phone number
• Track your message's status
• Include media in your message (US & Canada only)
• Handle replies with AI-powered SMS bots

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).

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.

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.

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

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.

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).

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.