Get Started

REST API: Messages

A Message instance resource represents an inbound or outbound message. When you send an SMS or MMS message via the REST API, use the <Message> verb in TwiML, or someone sends a message to one of your Twilio numbers Twilio creates a Message instance resource.

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

If you are looking for documentation on the deprecated SMS/Messages resource, that documentation is available here.

Message Instance Resource

This resource represents an individual SMS or MMS message.

Resource URI

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

Resource Properties

An 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 message was sent. For incoming messages, this is the date that Twilio received the message. The date is given in RFC 2822 format.
AccountSid The unique id of the Account that sent this 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 message. Up to 1600 characters long.
NumSegments This property indicates the number of sms messages used to deliver the body specified. If your body is too large to be sent as a single SMS message, it will be segmented and charged accordingly.
Status The status of this message. Either queued, sending, sent,failed, delivered, undelivered, receiving or received. See detailed descriptions of these statuses below.
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. The value will be null if the message was delivered successfully.
ErrorMessage The human readable description of the ErrorCode above. If the message status is failed or undelivered it will have one of the values described below, otherwise it will be null.
Direction The direction of this 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 message.
Price The amount billed for the message, in the currency associated with the account. Note that your account will be charged for each segment sent to the handset.
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 message.
Uri The URI for this resource, relative to https://api.twilio.com
Message Status Values

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

Status Description
queued The API request to send an 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 network.
sent The message was successfully accepted by the nearest upstream carrier.
receiving The inbound message has been received by Twilio and is currently being processed.
received On inbound messages only. The message was received by one of your Twilio numbers.
delivered Twilio has received confirmation of message delivery from the upstream carrier, and, where available, the destination handset.
undelivered Twilio has received a delivery receipt indicating that the message was not delivered. This can happen for a number of reasons including carrier content filtering, availability of the destination handset, etc.
failed The message could not be sent. This can happen for various reasons including carrier failures, queue overflows and account suspensions. Twilio does not charge you for failed messages.
Delivery Related Errors

When the message status is failed or undelivered, the ErrorCode and ErrorMessage properties will be populated with one of the following values. This property will be null otherwise.

ErrorCode ErrorMessage Description
30001 Queue overflow You tried to send too many messages too quickly and your message queue overflowed. Try sending your message again after waiting some time.
30002 Account suspended Your account was suspended between the time of message send and delivery. Please contact Twilio.
30003 Unreachable destination handset The destination handset you are trying to reach is switched off or otherwise unavailable.
30004 Message blocked The destination number you are trying to reach is blocked from receiving this message (e.g. due to blacklisting).
30005 Unknown destination handset The destination number you are trying to reach is unknown and may no longer exist.
30006 Landline or unreachable carrier The destination number is unable to receive this message. Potential reasons could include trying to reach a landline or, in the case of short codes, an unreachable carrier.
30007 Carrier violation Your message content was flagged as going against carrier guidelines.
30008 Unknown error The error does not fit into any of the above categories.

Note that ErrorMessage property is meant to be a human readable description so the values returned are subject to change in the future.

NumSegments Property

This property indicates the number of sms messages used to deliver the body specified. If your body is greater than 160 GSM-7 characters (or 70 UCS-2 characters), Twilio will segment and annotate your messages to attempt proper reassembly on the recipient's handset (not supported by all carriers and handsets). This ensures your body text is transmitted with the highest fidelity. Your account will be charged for each segment sent to the handset.

HTTP GET

Returns a single message specified by the provided {MessageSid}.

Example

HTTP POST

Not supported.

HTTP PUT

Not supported.

HTTP DELETE

Not supported.

Message Instance Subresources

Each Message instance resource has a Media subresource which represents the set of media associated with the message (if any).

Media List Subresource
/2010-04-01/Accounts/{AccountSid}/Messages/{MessageSid}/Media

Message instance resources also have a Media list resource that represents the set of media elements included with a given Message.

Media Instance Subresource
/2010-04-01/Accounts/{AccountSid}/Messages/{MessageSid}/Media/{MediaSid}

Message instance resources have Media instance subresources where information about images and other media can be retrieved if available.

Messages List Resource

Resource URI

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

HTTP GET

Returns a list of 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 messages to this phone number.
From Only show messages from this phone number.
DateSent Only show 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 messages that were sent on or before midnight on a date, and DateSent>=YYYY-MM-DD for messages sent on or after midnight on a date.
Example

Grab the whole list of messages.

HTTP POST

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

HTTP PUT

Not supported.

HTTP DELETE

Not supported.