REST API: Sending SMS or MMS

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.


Send a message wishing your friend Jenny good luck on the bar exam, along with an image of a hamster eating a four-leaf clover. Note that while you can send text-only messages just about anywhere on the planet, sending images is currently only possible in the US and Canada:

Send a Message with an Image URL
  • C#
  • Java
  • Node.js
  • PHP
  • Python
  • Ruby
  • curl
SDK Version:
  • 6.x
  • 7.x
SDK Version:
  • 4.x
  • 5.x
// Download the twilio-csharp library from
using System;
using Twilio;
class Example
 static void Main(string[] args)
    // Find your Account Sid and Auth Token at
    string AuthToken = "your_auth_token";
    var twilio = new TwilioRestClient(AccountSid, AuthToken);

    var message = twilio.SendMessage(
        "+15017250604", "+15558675309",
        "Hey Jenny! Good luck on the bar exam!",
        new string[] { "" }
// Twilio Credentials 
var authToken = 'your_auth_token'; 
//require the Twilio module and create a REST client 
var client = require('twilio')(accountSid, authToken); 
    to: "+15558675309", 
    from: "+15017250604", 
    body: "Hey Jenny! Good luck on the bar exam!", 
    mediaUrl: "",  
}, function(err, message) { 
from import TwilioRestClient 
# put your own credentials here 
AUTH_TOKEN = "your_auth_token" 
client = TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN) 
    body="Hey Jenny! Good luck on the bar exam!", 
require 'rubygems' # not necessary with ruby 1.9 but included for completeness 
require 'twilio-ruby' 
# put your own credentials here 
auth_token = 'your_auth_token' 
# set up a client to talk to the Twilio REST API 
@client = account_sid, auth_token 
  :from => '+15017250604', 
  :to => '+15558675309', 
  :body => 'Hey Jenny! Good luck on the bar exam!', 
  :media_url => '', 
// Get the PHP helper library from
require_once '/path/to/vendor/autoload.php'; // Loads the library
use Twilio\Rest\Client;

// Your Account Sid and Auth Token from
$token = "your_auth_token";
$client = new Client($sid, $token);

        'from' => '+15017250604',
        'body' => "Hey Jenny! Good luck on the bar exam!",
        'mediaUrl' => "",

// this line loads the library 
$auth_token = 'your_auth_token'; 
$client = new Services_Twilio($account_sid, $auth_token); 
    'To' => "+15558675309", 
    'From' => "+15017250604", 
    'Body' => "Hey Jenny! Good luck on the bar exam!", 
    'MediaUrl' => "",  
// You may want to be more specific in your imports
import java.util.*;
import com.twilio.sdk.*;
import com.twilio.sdk.resource.factory.*;
import com.twilio.sdk.resource.instance.*;
import com.twilio.sdk.resource.list.*;
import java.util.ArrayList;
import java.util.List;
import org.apache.http.NameValuePair;
import org.apache.http.message.BasicNameValuePair;

public class TwilioTest {
 // Find your Account Sid and Token at
 public static final String AUTH_TOKEN = "your_auth_token";

 public static void main(String[]args) throws TwilioRestException {
  TwilioRestClient client = new TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN);

   // Build the parameters
   List<NameValuePair> params = new ArrayList<NameValuePair>();
   params.add(new BasicNameValuePair("To", "+15558675309"));
   params.add(new BasicNameValuePair("From", "+15017250604"));
   params.add(new BasicNameValuePair("Body", "Hey Jenny! Good luck on the bar exam!"));
   params.add(new BasicNameValuePair("MediaUrl", ""));

   MessageFactory messageFactory = client.getAccount().getMessageFactory();
   Message message = messageFactory.create(params);
// Install the Java helper library from
import com.twilio.Twilio;
import com.twilio.type.PhoneNumber;

public class Example {
  // Find your Account Sid and Token at
  public static final String API_SECRET = "your_api_secret";

  public static void main(String[] args) {

    Message message = Message
        .create(new PhoneNumber("+15558675309"), new PhoneNumber("+15017250604"),
            "Never gonna give you up.")

curl -X POST '' \
--data-urlencode 'To=+15558675309'  \
--data-urlencode 'From=+15017250604'  \
--data-urlencode 'Body=Hey Jenny! Good luck on the bar exam!'  \
-d 'MediaUrl=' \
Show Output
  • JSON
  • XML
  "sid": "MMc781610ec0b3400c9e0cab8e757da937",
  "date_created": "Mon, 19 Oct 2015 07:07:03 +0000",
  "date_updated": "Mon, 19 Oct 2015 07:07:03 +0000",
  "date_sent": null,
  "to": "+16518675309",
  "from": "+14158141829",
  "body": "Hey Jenny! Good luck on the bar exam!",
  "status": "queued",
  "num_segments": "1",
  "num_media": "1",
  "direction": "outbound-api",
  "api_version": "2010-04-01",
  "price": null,
  "price_unit": "USD",
  "error_code": null,
  "error_message": null,
  "uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/MMc781610ec0b3400c9e0cab8e757da937.json",
  "subresource_uris": {
    "media": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/MMc781610ec0b3400c9e0cab8e757da937/Media.json"
<?xml version='1.0' encoding='UTF-8'?>
  <DateCreated>Mon, 19 Oct 2015 07:09:09 +0000</DateCreated>
  <DateUpdated>Mon, 19 Oct 2015 07:09:09 +0000</DateUpdated>
  <Body>Hey Jenny! Good luck on the bar exam!</Body>

HTTP POST to Messages

To send a new outgoing message, make an HTTP POST to your Messages list resource URI:


POST Parameters

Required Parameters

The To parameter is required in your POST to send the message:

Parameter Description
To The destination phone number. Format with a '+' and country code e.g., +16175551212 (E.164 format).
If you are sending messages while in trial mode, the 'To' phone number must be verified with Twilio.
Conditional Parameters

You must POST at least one of the following parameters to determine the 'From' phone number or Sender ID of your message:

Parameter Description
From A Twilio phone number (in E.164 format) or alphanumeric sender ID enabled for the type of message you wish to send. Phone numbers or short codes purchased from Twilio work here. You cannot (for example) spoof messages from your own cell phone number.
MessagingServiceSid The 34 character unique id of the Messaging Service you want to associate with this Message. Set this parameter to use the Messaging Service Settings and Copilot Features you have configured. When only this parameter is set, Twilio will use your enabled Copilot Features to select the From phone number for delivery.

There is a slight difference in API response when specifying the MessagingServiceSid parameter. When you only specify the From parameter, Twilio will validate the phone numbers synchronously and return either a queued status or an error. When specifying the MessagingServiceSid parameter, Twilio will first return an accepted status. Twilio then determines the optimal From phone number and any delivery errors will be sent asynchronously to your StatusCallback URL.

You must also POST at least one of the following parameters for the content of your message:

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 GSM-7 characters (or 70 UCS-2 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.

Optional Parameters

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: queued, failed, sent, delivered, or undelivered. Twilio will POST the MessageSid along with the other standard request parameters as well as MessageStatus and ErrorCode. If this parameter passed in addition to a MessagingServiceSid, Twilio will override the Status Callback URL of the Messaging Service. Non-relative URLs must contain a valid hostname (underscores are not allowed).
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.
MaxPrice The total maximum price up to the fourth decimal (0.0001) in US dollars acceptable for the message to be delivered. All messages regardless of the price point will be queued for delivery. A POST request will later be made to your Status Callback URL with a status change of 'Sent' or 'Failed'. When the price of the message is above this value the message will fail and not be sent. When MaxPrice is not set, all prices for the message is accepted. This parameter is not available when sending with a Messaging Service.
ProvideFeedback Set this value to true if you are sending messages that have a trackable user action and you intend to confirm delivery of the message using the Message Feedback API. This parameter is set to false by default.
Request Parameters

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.

Messaging Services

As you use Twilio Messaging to power different use cases, it may be helpful to organize your account and message logs into separate Messaging Services. Messaging Services allow you to organize your messages and enable specific features for these groups of messages. This keeps your code clean and lets you adjust messaging configuration right from your Account Portal.

With every Messaging Service, you start by configuring the Inbound Request URL and Status Callback URL. For advanced configuration, Twilio Copilot Features are available to add intelligence to your application.

When sending messages, you must associate one or more phone numbers and/or short codes to your Messaging Service. One of the phone numbers in your Messaging Service will be chosen based on the enabled Copilot Features whenever you send an outbound message.

Alphanumeric Sender ID

Alphanumeric sender IDs are used for branded one-way messaging. Alphanumeric sender IDs may be used at no additional cost when sending an SMS to countries that are supported. Accepted characters include both upper- and lower-case ASCII letters, the digits 0 through 9, and space: [A-Za-z0-9 ]. When using an alphanumeric sender ID, at least 1 letter and no more than 11 alphanumeric characters may be used.

Please email to enable alphanumeric sender IDs for your account.

Rate limiting

Your messages may be rate limited at different rates based on the destination you're sending messages to. For example, for US/CA destinations the limit is one message per second. Internationally, the upper limit is 10 MPS. For more information, check out this FAQ.

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

Handling Message Replies

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.