Send a message

POST /2010-04-01/Accounts/{AccountSid}/Messages.json

Account sid auth token

A Message resource represents an inbound or outbound message.

Send a message

Path parameters

AccountSid string Required

The SID of the Account creating the Message resource.

Minimum length is 34, maximum length is 34. Format should match the following pattern: ^AC[0-9a-fA-F]{32}$.

application/x-www-form-urlencoded

Body

To string(phone-number) Required

The recipient's phone number in E.164 format (for SMS/MMS) or channel address, e.g. whatsapp:+15552229999.
StatusCallback string(uri)

The URL of the endpoint to which Twilio sends Message status callback requests. URL must contain a valid hostname and underscores are not allowed. If you include this parameter with the messaging_service_sid, Twilio uses this URL instead of the Status Callback URL of the Messaging Service.
ApplicationSid string

The SID of the associated TwiML Application. Message status callback requests are sent to the TwiML App's message_status_callback URL. Note that the status_callback parameter of a request takes priority over the application_sid parameter; if both are included application_sid is ignored.

Minimum length is 34, maximum length is 34. Format should match the following pattern: ^AP[0-9a-fA-F]{32}$.
MaxPrice number

[OBSOLETE] This parameter will no longer have any effect as of 2024-06-03.
ProvideFeedback boolean

Boolean indicating whether or not you intend to provide delivery confirmation feedback to Twilio (used in conjunction with the Message Feedback subresource). Default value is false.
Attempt integer

Total number of attempts made (including this request) to send the message regardless of the provider used
ValidityPeriod integer

The maximum length in seconds that the Message can remain in Twilio's outgoing message queue. If a queued Message exceeds the validity_period, the Message is not sent. Accepted values are integers from 1 to 36000. Default value is 36000. A validity_period greater than 5 is recommended. Learn more about the validity period
ForceDelivery boolean

Reserved
ContentRetention string

Values are retain or discard.
AddressRetention string

Values are retain or obfuscate.
SmartEncoded boolean

Whether to detect Unicode characters that have a similar GSM-7 character and replace them. Can be: true or false.
PersistentAction array[string]

Rich actions for non-SMS/MMS channels. Used for sending location in WhatsApp messages.
TrafficType string

Value is free.
ShortenUrls boolean

For Messaging Services with Link Shortening configured only: A Boolean indicating whether or not Twilio should shorten links in the body of the Message. Default value is false. If true, the messaging_service_sid parameter must also be provided.
ScheduleType string

Value is fixed.
SendAt string(date-time)

The time that Twilio will send the message. Must be in ISO 8601 format.
SendAsMms boolean

If set to true, Twilio delivers the message as a single MMS message, regardless of the presence of media.
ContentVariables string

For Content Editor/API only: Key-value pairs of Template variables and their substitution values. content_sid parameter must also be provided. If values are not defined in the content_variables parameter, the Template's default placeholder values are used.
RiskCheck string

Values are enable or disable.
From string(phone-number)

The sender's Twilio phone number (in E.164 format), alphanumeric sender ID, Wireless SIM, short code, or channel address (e.g., whatsapp:+15554449999). The value of the from parameter must be a sender that is hosted within Twilio and belongs to the Account creating the Message. If you are using messaging_service_sid, this parameter can be empty (Twilio assigns a from value from the Messaging Service's Sender Pool) or you can provide a specific sender from your Sender Pool.
MessagingServiceSid string

The SID of the Messaging Service you want to associate with the Message. When this parameter is provided and the from parameter is omitted, Twilio selects the optimal sender from the Messaging Service's Sender Pool. You may also provide a from parameter if you want to use a specific Sender from the Sender Pool.

Minimum length is 34, maximum length is 34. Format should match the following pattern: ^MG[0-9a-fA-F]{32}$.
Body string

The text content of the outgoing message. Can be up to 1,600 characters in length. SMS only: If the body contains more than 160 GSM-7 characters (or 70 UCS-2 characters), the message is segmented and charged accordingly. For long body text, consider using the send_as_mms parameter.
MediaUrl array[string(uri)]

The URL of media to include in the Message content. jpeg, jpg, gif, and png file types are fully supported by Twilio and content is formatted for delivery on destination devices. The media size limit is 5 MB for supported file types (jpeg, jpg, png, gif) and 500 KB for other types of accepted media. To send more than one image in the message, provide multiple media_url parameters in the POST request. You can include up to ten media_url parameters per message. International and carrier limits apply.
ContentSid string

For Content Editor/API only: The SID of the Content Template to be used with the Message, e.g., HXXXXXXXXXXXXXXXXXXXXXXXXXXXXX. If this parameter is not provided, a Content Template is not used. Find the SID in the Console on the Content Editor page. For Content API users, the SID is found in Twilio's response when creating the Template or by fetching your Templates.

Minimum length is 34, maximum length is 34. Format should match the following pattern: ^HX[0-9a-fA-F]{32}$.

Responses

201 application/json

Created
Hide headers attributes Show headers attributes
- Access-Control-Allow-Origin string
  
  Specify the origin(s) allowed to access the resource
- Access-Control-Allow-Methods string
  
  Specify the HTTP methods allowed when accessing the resource
- Access-Control-Allow-Headers string
  
  Specify the headers allowed when accessing the resource
- Access-Control-Allow-Credentials boolean
  
  Indicates whether the browser should include credentials
- Access-Control-Expose-Headers string
  
  Headers exposed to the client
Hide response attributes Show response attributes object
- body string | null
  
  The text content of the message
- num_segments string | null
  
  The number of segments that make up the complete message. SMS message bodies that exceed the character limit are segmented and charged as multiple messages. Note: For messages sent via a Messaging Service, num_segments is initially 0, since a sender hasn't yet been assigned.
- direction string
  
  The direction of the message. Can be: inbound for incoming messages, outbound-api for messages created by the REST API, outbound-call for messages created during a call, or outbound-reply for messages created in response to an incoming message.
  
  Values are inbound, outbound-api, outbound-call, or outbound-reply.
- from string(phone-number) | null
  
  The sender's phone number (in E.164 format), alphanumeric sender ID, Wireless SIM, short code, or channel address (e.g., whatsapp:+15554449999). For incoming messages, this is the number or channel address of the sender. For outgoing messages, this value is a Twilio phone number, alphanumeric sender ID, short code, or channel address from which the message is sent.
- to string | null
  
  The recipient's phone number (in E.164 format) or channel address (e.g. whatsapp:+15552229999)
- date_updated string(date-time-rfc-2822) | null
  
  The RFC 2822 timestamp (in GMT) of when the Message resource was last updated
- price string | null
  
  The amount billed for the message in the currency specified by price_unit. The price is populated after the message has been sent/received, and may not be immediately availalble. View the Pricing page for more details.
- error_message string | null
  
  The description of the error_code if the Message status is failed or undelivered. If no error was encountered, the value is null. The value returned in this field for a specific error cause is subject to change as Twilio improves errors. Users should not use the error_code and error_message fields programmatically.
- uri string | null
  
  The URI of the Message resource, relative to https://api.twilio.com.
- account_sid string | null
  
  The SID of the Account associated with the Message resource
  
  Minimum length is 34, maximum length is 34. Format should match the following pattern: ^AC[0-9a-fA-F]{32}$.
- num_media string | null
  
  The number of media files associated with the Message resource.
- status string
  
  The status of the Message. Possible values: accepted, scheduled, canceled, queued, sending, sent, failed, delivered, undelivered, receiving, received, or read (WhatsApp only). For more information, See detailed descriptions.
  
  Values are queued, sending, sent, failed, delivered, undelivered, receiving, received, accepted, scheduled, read, partially_delivered, or canceled.
- messaging_service_sid string | null
  
  The SID of the Messaging Service associated with the Message resource. A unique default value is assigned if a Messaging Service is not used.
  
  Minimum length is 34, maximum length is 34. Format should match the following pattern: ^MG[0-9a-fA-F]{32}$.
- sid string | null
  
  The unique, Twilio-provided string that identifies the Message resource.
  
  Minimum length is 34, maximum length is 34. Format should match the following pattern: ^(SM|MM)[0-9a-fA-F]{32}$.
- date_sent string(date-time-rfc-2822) | null
  
  The RFC 2822 timestamp (in GMT) of when the Message was sent. For an outgoing message, this is when Twilio sent the message. For an incoming message, this is when Twilio sent the HTTP request to your incoming message webhook URL.
- date_created string(date-time-rfc-2822) | null
  
  The RFC 2822 timestamp (in GMT) of when the Message resource was created
- error_code integer | null
  
  The error code returned if the Message status is failed or undelivered. If no error was encountered, the value is null. The value returned in this field for a specific error cause is subject to change as Twilio improves errors. Users should not use the error_code and error_message fields programmatically.
- price_unit string(currency) | null
  
  The currency in which price is measured, in ISO 4127 format (e.g. usd, eur, jpy).
- api_version string | null
  
  The API version used to process the Message
- subresource_uris object(uri-map) | null
  
  A list of related resources identified by their URIs relative to https://api.twilio.com

POST /2010-04-01/Accounts/{AccountSid}/Messages.json

curl \
 --request POST 'https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Messages.json' \
 --user "username:password" \
 --header "Content-Type: application/x-www-form-urlencoded" \
 --data 'To=%2B14155552345&Body=Hello%21+%F0%9F%91%8D&From=%2B14155552345&Tags=%7B%22campaign_name%22%3A+%22Spring+Sale+2022%22%2C%22message_type%22%3A+%22cart_abandoned%22%7D&MediaUrl=https%3A%2F%2Fc1.staticflickr.com%2F3%2F2899%2F14341091933_1e92e62d12_b.jpg&ApplicationSid=APaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&StatusCallback=https%3A%2F%2Fexample.com&PersistentAction=mailto%3Atest%40example.com'

Request examples

{"To"=>"+14155552345", "Body"=>"Hello! 👍", "From"=>"+14155552345", "Tags"=>"{\"campaign_name\": \"Spring Sale 2022\",\"message_type\": \"cart_abandoned\"}", "MediaUrl"=>["https://c1.staticflickr.com/3/2899/14341091933_1e92e62d12_b.jpg"], "ApplicationSid"=>"APaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "StatusCallback"=>"https://example.com", "PersistentAction"=>["mailto:test@example.com"]}

{"To"=>"+14155552345", "Body"=>"Hello! 👍", "From"=>"+14155552345", "MediaUrl"=>["https://example.com"], "ApplicationSid"=>"APaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "StatusCallback"=>"https://example.com", "PersistentAction"=>["mailto:test@example.com"]}

{"To"=>"+14155552345", "Body"=>"Hello! 👍", "MediaUrl"=>["https://example.com"], "ContentSid"=>"HXaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "ApplicationSid"=>"APaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "StatusCallback"=>"https://example.com", "PersistentAction"=>["mailto:test@example.com"], "MessagingServiceSid"=>"MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}

{"To"=>"+14155552345", "Body"=>"Hello! 👍", "From"=>"+14155552345", "MediaUrl"=>["https://example.com"], "ApplicationSid"=>"APaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "StatusCallback"=>"https://example.com", "PersistentAction"=>["mailto:test@example.com"]}

{"To"=>"+15558675310", "Body"=>"Hello! 👍", "ScheduleType"=>"fixed", "StatusCallback"=>"https://example.com", "MessagingServiceSid"=>"MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}

{"To"=>"+15558675310", "Body"=>"Hello! 👍", "MediaUrl"=>["https://example.com"], "ScheduleType"=>"fixed", "StatusCallback"=>"https://example.com", "MessagingServiceSid"=>"MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}

{"To"=>"94287277+15558675310", "Body"=>"Hello! 👍", "ScheduleType"=>"fixed", "StatusCallback"=>"https://example.com", "MessagingServiceSid"=>"MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}

Response examples (201)

{
  "to": "+14155552345",
  "sid": "SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json",
  "body": "Hello! 👍",
  "from": "+14155552345",
  "tags": {
    "message_type": "cart_abandoned",
    "campaign_name": "Spring Sale 2022"
  },
  "price": null,
  "status": "queued",
  "date_sent": "Thu, 24 Aug 2023 05:01:45 +0000",
  "direction": "outbound-api",
  "num_media": "0",
  "error_code": null,
  "price_unit": null,
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "api_version": "2010-04-01",
  "date_created": "Thu, 24 Aug 2023 05:01:45 +0000",
  "date_updated": "Thu, 24 Aug 2023 05:01:45 +0000",
  "num_segments": "1",
  "error_message": null,
  "subresource_uris": {
    "media": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Media.json"
  },
  "messaging_service_sid": "MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}

{
  "to": "+14155552345",
  "sid": "SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json",
  "body": "Hello! 👍",
  "from": "+14155552345",
  "tags": null,
  "price": null,
  "status": "queued",
  "date_sent": "Thu, 30 Jul 2015 20:12:33 +0000",
  "direction": "outbound-api",
  "num_media": "0",
  "error_code": null,
  "price_unit": null,
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "api_version": "2010-04-01",
  "date_created": "Thu, 30 Jul 2015 20:12:31 +0000",
  "date_updated": "Thu, 30 Jul 2015 20:12:33 +0000",
  "num_segments": "1",
  "error_message": null,
  "subresource_uris": {
    "media": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Media.json"
  },
  "messaging_service_sid": "MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}

{
  "to": "+14155552345",
  "sid": "SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json",
  "body": "Hello! 👍",
  "from": null,
  "tags": null,
  "price": null,
  "status": "queued",
  "date_sent": "Thu, 30 Jul 2015 20:12:33 +0000",
  "direction": "outbound-api",
  "num_media": "0",
  "error_code": null,
  "price_unit": null,
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "api_version": "2010-04-01",
  "date_created": "Thu, 30 Jul 2015 20:12:31 +0000",
  "date_updated": "Thu, 30 Jul 2015 20:12:33 +0000",
  "num_segments": "1",
  "error_message": null,
  "subresource_uris": {
    "media": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Media.json"
  },
  "messaging_service_sid": "MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}

{
  "to": "+14155552345",
  "sid": "SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json",
  "body": "Hello! 👍",
  "from": "+14155552345",
  "tags": null,
  "price": null,
  "status": "queued",
  "date_sent": "Thu, 30 Jul 2015 20:12:33 +0000",
  "direction": "outbound-api",
  "num_media": "0",
  "error_code": null,
  "price_unit": null,
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "api_version": "2010-04-01",
  "date_created": "Thu, 30 Jul 2015 20:12:31 +0000",
  "date_updated": "Thu, 30 Jul 2015 20:12:33 +0000",
  "num_segments": "1",
  "error_message": null,
  "subresource_uris": {
    "media": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Media.json"
  },
  "messaging_service_sid": "MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}

{
  "to": "+15558675310",
  "sid": "SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json",
  "body": "Hello! 👍",
  "from": null,
  "tags": null,
  "price": null,
  "status": "queued",
  "date_sent": null,
  "direction": "outbound-api",
  "num_media": "0",
  "error_code": null,
  "price_unit": null,
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "api_version": "2010-04-01",
  "date_created": "Mon, 29 Nov 2021 22:40:10 +0000",
  "date_updated": "Mon, 29 Nov 2021 22:40:10 +0000",
  "num_segments": "0",
  "error_message": null,
  "subresource_uris": {
    "media": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Media.json"
  },
  "messaging_service_sid": "MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}

{
  "to": "+15558675310",
  "sid": "MMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/MMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json",
  "body": "Hello! 👍",
  "from": null,
  "tags": null,
  "price": null,
  "status": "accepted",
  "date_sent": null,
  "direction": "outbound-api",
  "num_media": "1",
  "error_code": null,
  "price_unit": null,
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "api_version": "2010-04-01",
  "date_created": "Mon, 29 Nov 2021 22:40:10 +0000",
  "date_updated": "Mon, 29 Nov 2021 22:40:10 +0000",
  "num_segments": "1",
  "error_message": null,
  "subresource_uris": {
    "media": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/MMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Media.json"
  },
  "messaging_service_sid": "MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}

{
  "to": "whatsapp:+15558675310",
  "sid": "SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json",
  "body": "Hello! 👍",
  "from": null,
  "tags": null,
  "price": null,
  "status": "scheduled",
  "date_sent": null,
  "direction": "outbound-api",
  "num_media": "0",
  "error_code": null,
  "price_unit": null,
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "api_version": "2010-04-01",
  "date_created": "Mon, 29 Nov 2021 22:40:10 +0000",
  "date_updated": "Mon, 29 Nov 2021 22:40:10 +0000",
  "num_segments": "0",
  "error_message": null,
  "subresource_uris": {
    "media": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Media.json"
  },
  "messaging_service_sid": "MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}