REST API: SMS Messages

The SMS/Messages resource has been deprecated, replaced by the Messages resource, and may be removed in future versions of the Twilio API. Since the Messages resource is a superset of SMS/Messages, we recommend its use going forward.

An SMS Message instance resource represents an inbound or outbound SMS message. Whenever someone sends an SMS message to one of your Twilio numbers, or when you send an SMS message via the REST API or using the <Sms> verb, Twilio creates an SMS Message instance resource and associates it with your account.

The SMS Messages list resource represents the set of SMS messages sent from and received by an account.

SMS Message Instance Resource

This resource represents an individual SMS message.

Resource URI

/2010-04-01/Accounts/{AccountSid}/SMS/Messages/{SMSMessageSid}

Resource Properties

An SMS Message resource is represented by the following properties:

Property Description
Sid A 34 character string that uniquely identifies this resource.
DateCreated The date that this resource was created, given in RFC 2822 format.
DateUpdated The date that this resource was last updated, given in RFC 2822 format.
DateSent The date that the SMS was sent. For incoming messages, this is the date that Twilio received the SMS. The date is given in RFC 2822 format.
AccountSid The unique id of the Account that sent this SMS message.
From The phone number that initiated the message in E.164 format. For incoming messages, this will be the remote phone. For outgoing messages, this will be one of your Twilio phone numbers.
To The phone number that received the message in E.164 format. For incoming messages, this will be one of your Twilio phone numbers. For outgoing messages, this will be the remote phone.
Body The text body of the SMS message. Up to 160 characters long.
Status The status of this SMS message. Either queued, sending, sent,failed, or received.
Direction The direction of this SMS message. inbound for incoming messages, outbound-api for messages initiated via the REST API, outbound-call for messages initiated during a call or outbound-reply for messages initiated in response to an incoming SMS.
Price The amount billed for the message, in the currency associated with the account.
PriceUnit The currency in which Price is measured, in ISO 4127 format (e.g. usd, eur, jpy).
ApiVersion The version of the Twilio API used to process the SMS message.
Uri The URI for this resource, relative to https://api.twilio.com
SMS Status Values

The following are the possible values for the 'Status' parameter.

Status Description
queued The API request to send an SMS message was successful and the message is queued to be sent out.
sending Twilio is in the process of dispatching your message to the nearest upstream carrier in the SMS network.
sent The message was sent to the nearest upstream carrier, and that carrier accepted the message.
failed The message could not be sent, most likely because the "To" number is non-existent.
received On inbound messages only. The message was received by one of your Twilio numbers.

HTTP GET

Returns a single SMS message specified by the provided {SMSMessageSid}.

Example
Retrieve an SMS
  • C#
  • Java
  • Node.js
  • PHP
  • Python
  • Ruby
  • curl
  • 4.x
  • 5.x
  • json
  • xml
// Download the twilio-csharp library from twilio.com/docs/csharp/install
using System;
using Twilio;
class Example 
{
  static void Main(string[] args) 
  {
    // Find your Account Sid and Auth Token at twilio.com/user/account
    string AccountSid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
    string AuthToken = "your_auth_token";
    var twilio = new TwilioRestClient(AccountSid, AuthToken);

    var sms = twilio.GetSmsMessage("SM800f449d0399ed014aae2bcc0cc2f2ec");
    
    Console.WriteLine(sms.Body);
  }
}
// Install the Java helper library from twilio.com/docs/java/install
import com.twilio.sdk.TwilioRestClient;
import com.twilio.sdk.TwilioRestException;
import com.twilio.sdk.resource.instance.Sms;

public class Example { 

  // Find your Account Sid and Token at twilio.com/user/account
  public static final String ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
  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);

    // Get an object from its sid. If you do not have a sid,
    // check out the list resource examples on this page
    Sms sms = client.getAccount().getSms("SM800f449d0399ed014aae2bcc0cc2f2ec");
    System.out.println(sms.getBody());
    
  }
}
// Download the Node helper library from twilio.com/docs/node/install
// These vars are your accountSid and authToken from twilio.com/user/account
var accountSid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
var authToken = "your_auth_token";
var client = require('twilio')(accountSid, authToken);

client.sms.messages("SM800f449d0399ed014aae2bcc0cc2f2ec").get(function(err, sms) {
    console.log(sms.body);
});
# Download the Python helper library from twilio.com/docs/python/install
from twilio.rest import TwilioRestClient

# Your Account Sid and Auth Token from twilio.com/user/account
account_sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
auth_token  = "your_auth_token"
client = TwilioRestClient(account_sid, auth_token)

sms = client.sms.messages.get("SM800f449d0399ed014aae2bcc0cc2f2ec")
print(sms.body)
# Get twilio-ruby from twilio.com/docs/ruby/install
require 'rubygems'          # This line not needed for ruby > 1.8
require 'twilio-ruby'

# Get your Account Sid and Auth Token from twilio.com/user/account
account_sid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
auth_token = 'your_auth_token'
@client = Twilio::REST::Client.new account_sid, auth_token

# Get an object from its sid. If you do not have a sid,
# check out the list resource examples on this page
@sms = @client.account.sms.messages.get("SM800f449d0399ed014aae2bcc0cc2f2ec")
puts @sms.body
$ curl -G https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/SMS/Messages/SM800f449d0399ed014aae2bcc0cc2f2ec.json \
    -u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token'
<?php
// Get the PHP helper library from twilio.com/docs/php/install
require_once('/path/to/twilio-php/Services/Twilio.php'); // Loads the library

// Your Account Sid and Auth Token from twilio.com/user/account
$sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"; 
$token = "your_auth_token"; 
$client = new Services_Twilio($sid, $token);

// Get an object from its sid. If you do not have a sid,
// check out the list resource examples on this page
$sms = $client->account->sms_messages->get("SM800f449d0399ed014aae2bcc0cc2f2ec");
echo $sms->body;
$ curl -G https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/SMS/Messages/SM800f449d0399ed014aae2bcc0cc2f2ec \
    -u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token'
<?php
// Get the PHP helper library from twilio.com/docs/php/install
require_once '/path/to/vendor/autoload.php'; // Loads the library
use Twilio\Rest\Client;

// Your Account Sid and Auth Token from twilio.com/user/account
$sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
$token = "your_auth_token";
$client = new Client($sid, $token);

// Get an object from its sid. If you do not have a sid,
// check out the list resource examples on this page
$sms = $client->sms
    ->messages("SM800f449d0399ed014aae2bcc0cc2f2ec")
    ->fetch();

echo $sms->body;
Show Output
  • JSON
  • XML
{
	"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
	"api_version": "2008-08-01",
	"body": "Hey Jenny why aren't you returning my calls?",
	"date_created": "Mon, 16 Aug 2010 03:45:01 +0000",
	"date_sent": "Mon, 16 Aug 2010 03:45:03 +0000",
	"date_updated": "Mon, 16 Aug 2010 03:45:03 +0000",
	"direction": "outbound-api",
	"from": "+14158141829",
	"price": "-0.02000",
	"sid": "SM800f449d0399ed014aae2bcc0cc2f2ec",
	"status": "sent",
	"to": "+14159978453",
	"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/SMS/Messages/SM800f449d0399ed014aae2bcc0cc2f2ec.json"
}
<TwilioResponse>
	<SMSMessage>
		<Sid>SM800f449d0399ed014aae2bcc0cc2f2ec</Sid>
		<DateCreated>Mon, 16 Aug 2010 03:45:01 +0000</DateCreated>
		<DateUpdated>Mon, 16 Aug 2010 03:45:03 +0000</DateUpdated>
		<DateSent>Mon, 16 Aug 2010 03:45:03 +0000</DateSent>
		<AccountSid>ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</AccountSid>
		<To>+14159978453</To>
		<From>+14158141829</From>
		<Body>Hey Jenny why aren't you returning my calls?</Body>
		<Status>sent</Status>
		<Direction>outbound-api</Direction>
		<ApiVersion>2010-04-01</ApiVersion>
		<Price>-0.02000</Price>
		<Uri>/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/SMS/Messages/SM800f449d0399ed014aae2bcc0cc2f2ec</Uri>
	</SMSMessage>
</TwilioResponse>

HTTP POST

Not supported.

HTTP PUT

Not supported.

HTTP DELETE

Not supported.

SMS Messages List Resource

Resource URI

/2010-04-01/Accounts/{AccountSid}/SMS/Messages

HTTP GET

Returns a list of SMS messages associated with your account. The list includes paging information.

List Filters

You may limit the list by providing certain query string parameters to the listing resource. Note, parameters are case-sensitive:

Parameter Description
To Only show SMS messages to this phone number.
From Only show SMS messages from this phone number.
DateSent Only show SMS messages sent on this date (in GMT format), given as YYYY-MM-DD. Example: DateSent=2009-07-06. You can also specify inequality, such as DateSent<=YYYY-MM-DD for SMS messages that were sent on or before midnight on a date, and DateSent>=YYYY-MM-DD for SMS messages sent on or after midnight on a date.
Example

Grab the whole list of messages.

List all SMSs
  • C#
  • Java
  • Node.js
  • PHP
  • Python
  • Ruby
  • curl
  • 4.x
  • 5.x
  • json
  • xml
// Download the twilio-csharp library from twilio.com/docs/csharp/install
using System;
using Twilio;
class Example 
{
  static void Main(string[] args) 
  {
    // Find your Account Sid and Auth Token at twilio.com/user/account
    string AccountSid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
    string AuthToken = "your_auth_token";
    var twilio = new TwilioRestClient(AccountSid, AuthToken);

    var smss = twilio.ListSmsMessages(null, null, null, null, null);
    
    foreach (var sms in smss.SMSMessages)
    {
      Console.WriteLine(sms.To);
    }
  }
}
// Install the Java helper library from twilio.com/docs/java/install
import com.twilio.sdk.TwilioRestClient;
import com.twilio.sdk.TwilioRestException;
import com.twilio.sdk.resource.instance.Sms;
import com.twilio.sdk.resource.list.SmsList;

public class Example { 

  // Find your Account Sid and Token at twilio.com/user/account
  public static final String ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
  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);

    
    
    SmsList smss = client.getAccount().getSmsMessages();
    
    // Loop over smss and print out a property for each one.
    for (Sms sms : smss) {
      System.out.println(sms.getTo());
    }
    
  }
}
// Download the Node helper library from twilio.com/docs/node/install
// These vars are your accountSid and authToken from twilio.com/user/account
var accountSid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
var authToken = "your_auth_token";
var client = require('twilio')(accountSid, authToken);

client.sms.messages.list(function(err, data) {
    data.smsMessages.forEach(function(sms) {
        console.log(sms.to);
    });
});
# Download the Python helper library from twilio.com/docs/python/install
from twilio.rest import TwilioRestClient

# Your Account Sid and Auth Token from twilio.com/user/account
account_sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
auth_token  = "your_auth_token"
client = TwilioRestClient(account_sid, auth_token)

# A list of sms objects with the properties described above
smss = client.sms.messages.list()
# Get twilio-ruby from twilio.com/docs/ruby/install
require 'rubygems'          # This line not needed for ruby > 1.8
require 'twilio-ruby'

# Get your Account Sid and Auth Token from twilio.com/user/account
account_sid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
auth_token = 'your_auth_token'
@client = Twilio::REST::Client.new account_sid, auth_token


# Loop over smss and print out a property for each one
@client.account.sms.messages.list.each do |sms|
    puts sms.to
end
$ curl -G https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/SMS/Messages.json \
    -u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token'
<?php
// Get the PHP helper library from twilio.com/docs/php/install
require_once('/path/to/twilio-php/Services/Twilio.php'); // Loads the library

// Your Account Sid and Auth Token from twilio.com/user/account
$sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"; 
$token = "your_auth_token"; 
$client = new Services_Twilio($sid, $token);

// Loop over the list of smss and echo a property for each one
foreach ($client->account->sms_messages as $sms) {
    echo $sms->to;
}
$ curl -G https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/SMS/Messages \
    -u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token'
<?php
// Get the PHP helper library from twilio.com/docs/php/install
require_once '/path/to/vendor/autoload.php'; // Loads the library
use Twilio\Rest\Client;

// Your Account Sid and Auth Token from twilio.com/user/account
$sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
$token = "your_auth_token";
$client = new Client($sid, $token);

// Loop over the list of smss and echo a property for each one
foreach ($client->sms->messages->read() as $sms) {
    echo $sms->to;
}
Show Output
  • JSON
  • XML
{
	"page": 0,
	"page_size": 50,
	"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/SMS/Messages.json"
	"first_page_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/SMS/Messages.json?Page=0&PageSize=50",
	"next_page_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/SMS/Messages.json?Page=1&PageSize=50",
	"previous_page_uri": null,
	"sms_messages": [
		{
			"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
			"api_version": "2008-08-01",
			"body": "Hey Jenny why aren't you returning my calls?",
			"date_created": "Mon, 16 Aug 2010 03:45:01 +0000",
			"date_sent": "Mon, 16 Aug 2010 03:45:03 +0000",
			"date_updated": "Mon, 16 Aug 2010 03:45:03 +0000",
			"direction": "outbound-api",
			"from": "+14158141829",
			"price": "-0.02000",
			"sid": "SM800f449d0399ed014aae2bcc0cc2f2ec",
			"status": "sent",
			"to": "+14159978453",
			"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/SMS/Messages/SM800f449d0399ed014aae2bcc0cc2f2ec.json"
		},
		...
	]
}
<TwilioResponse>
	<SMSMessages page="0" pagesize="50" uri="/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/SMS/Messages" firstpageuri="/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/SMS/Messages?Page=0&amp;PageSize=50" previouspageuri="" nextpageuri="/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/SMS/Messages?Page=1&amp;PageSize=50">
		<SMSMessage>
			<Sid>SM800f449d0399ed014aae2bcc0cc2f2ec</Sid>
			<DateCreated>Mon, 16 Aug 2010 03:45:01 +0000</DateCreated>
			<DateUpdated>Mon, 16 Aug 2010 03:45:03 +0000</DateUpdated>
			<DateSent>Mon, 16 Aug 2010 03:45:03 +0000</DateSent>
			<AccountSid>ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</AccountSid>
			<To>+14159978453</To>
			<From>+14158141829</From>
			<Body>Hey Jenny why aren't you returning my calls?</Body>
			<Status>sent</Status>
			<Direction>outbound-api</Direction>
			<Price>-0.02000</Price>
			<ApiVersion>2008-08-01</ApiVersion>
			<Uri>/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/SMS/Messages/SM800f449d0399ed014aae2bcc0cc2f2ec</Uri>
		</SMSMessage>
		...
	</SMSMessages>
</TwilioResponse>

HTTP POST

Sends a new SMS message. For details see the Sending SMS section.

HTTP PUT

Not supported.

HTTP DELETE

Not supported.