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


Resource Properties

An Message resource is represented by the following properties:

SidA 34 character string that uniquely identifies this resource.
DateCreatedThe date that this resource was created, given in RFC 2822 format.
DateUpdatedThe date that this resource was last updated, given in RFC 2822 format.
DateSentThe 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.
AccountSidThe unique id of the Account that sent this message.
MessagingServiceSidThe unique id of the Messaging Service used with the message. The value will be null if a Messaging Service was not used.
FromThe phone number (in E.164 format) or alphanumeric sender ID that initiated the message. For incoming messages, this will be the remote phone. For outgoing messages, this will be one of your Twilio phone numbers or the alphanumeric sender ID used.
ToThe 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.
BodyThe text body of the message. Up to 1600 characters long.
NumMediaThis property indicates the number of media files associated with the message. Each message may send up to 10 media files.
NumSegmentsThis property indicates the number of segments that make up the message. If your body is too large to be sent as a single SMS message, it will be segmented and charged accordingly. Inbound message over 160 characters will be reassembled when the message is received.
StatusThe status of this message. Either accepted, queued, sending, sent,failed, delivered, undelivered, receiving or received. See detailed descriptions of these statuses below.
ErrorCodeThe 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.
ErrorMessageThe 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.
DirectionThe 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.
PriceThe 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.
PriceUnitThe currency in which Price is measured, in ISO 4127 format (e.g. usd, eur, jpy).
ApiVersionThe version of the Twilio API used to process the message.
UriThe URI for this resource, relative to
SubresourceUriThe URIs for any subresources associate with this resource, relative to
Message Status Values

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

acceptedTwilio has received your API request to send a message with a Messaging Service and a From number is being dynamically selected. This is still the initial status when sending with a Messaging Service and the From parameter.
queuedThe API request to send a message was successful and the message is queued to be sent out. This is the initial status when you are not using a Messaging Service.
sendingTwilio is in the process of dispatching your message to the nearest upstream carrier in the network.
sentThe message was successfully accepted by the nearest upstream carrier.
receivingThe inbound message has been received by Twilio and is currently being processed.
receivedOn inbound messages only. The inbound message was received by one of your Twilio numbers.
deliveredTwilio has received confirmation of message delivery from the upstream carrier, and, where available, the destination handset.
undeliveredTwilio 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.
failedThe message could not be sent. This can happen for various reasons including queue overflows, account suspensions and media errors (in the case of MMS). 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. A full list of Twilio Error Codes can be viewed here.

30001Queue overflowYou tried to send too many messages too quickly and your message queue overflowed. Try sending your message again after waiting some time.
30002Account suspendedYour account was suspended between the time of message send and delivery. Please contact Twilio.
30003Unreachable destination handsetThe destination handset you are trying to reach is switched off or otherwise unavailable.
30004Message blockedThe destination number you are trying to reach is blocked from receiving this message (e.g. due to blacklisting).
30005Unknown destination handsetThe destination number you are trying to reach is unknown and may no longer exist.
30006Landline or unreachable carrierThe 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.
30007Carrier violationYour message was flagged as objectionable by the carrier. In order to protect their subscribers, many carriers have implemented content or spam filtering. Learn more about carrier filtering
30008Unknown errorThe error does not fit into any of the above categories.
30009Missing segmentOne or more segments associated with your multi-part inbound message was not received.
30010Message price exceeds max price.The price of your message exceeds the max price parameter.

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

For outbound messages, 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.

For inbound messages, this property indicates the number of SMS messages that make up the message received. If the body of the message is greater than 160 GSM-7 characters (or 70 UCS-2 characters), Twilio will attempt to reassemble the message received on your Twilio phone number (not supported by all carriers and handsets).

Your account will be charged for each segment sent or received.


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



To redact the message-body from a message record, you may POST to the message instance resource with an empty Body.



Not supported.


Deletes a message record from your account. Once the record is deleted, it will no longer appear in the API and Account Portal logs. However, deleting a message does not delete any media associated with the message. That media is still available at its original uri.

If successful, returns HTTP 204 (No Content) with no body.

Note that it is an error to delete an in-progress message record.

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

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

Media Instance Subresource

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

Messages List Resource

Resource URI



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:

ToOnly show messages to this phone number.
FromOnly show messages from this phone number or alphanumeric sender ID.
DateSentOnly 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.

Grab the whole list of messages.


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


Not supported.


Not supported.