Send a message from the account used to make the request

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

A Message resource represents an inbound or outbound message.

Send a message from the account used to make the request

Path parameters

Body

  • Determines if the address can be stored or obfuscated based on privacy settings

    Value is retain.

  • The SID of the application that should receive message status. We POST a message_sid parameter and a message_status parameter with a value of sent or failed to the application's message_status_callback. If a status_callback parameter is also passed, it will be ignored and the application's message_status_callback parameter will be used.

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

  • Attempt integer

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

  • Body string

    The text of the message you want to send. Can be up to 1,600 characters in length.

  • Determines if the message content can be stored or redacted based on privacy settings

    Value is retain.

  • Reserved

  • From string(phone-number)

    A Twilio phone number in E.164 format, an alphanumeric sender ID, or a Channel Endpoint address that is enabled for the type of message you want to send. Phone numbers or short codes purchased from Twilio also work here. You cannot, for example, spoof messages from a private cell phone number. If you are using messaging_service_sid, this parameter must be empty.

  • MaxPrice number

    The maximum total price in US dollars that you will pay for the message to be delivered. Can be a decimal value that has up to 4 decimal places. All messages are queued for delivery and the message cost is checked before the message is sent. If the cost exceeds max_price, the message will fail and a status of Failed is sent to the status callback. If MaxPrice is not set, the message cost is not checked.

  • MediaUrl array[string(uri)]

    The URL of the media to send with the message. The media can be of type gif, png, and jpeg and will be formatted correctly on the recipient's device. The media size limit is 5MB for supported file types (JPEG, PNG, GIF) and 500KB for other types of accepted media. To send more than one image in the message body, provide multiple media_url parameters in the POST request. You can include up to 10 media_url parameters per message. You can send images in an SMS message in only the US and Canada.

  • The SID of the Messaging Service you want to associate with the Message. Set this parameter to use the Messaging Service Settings and Copilot Features you have configured and leave the from parameter empty. When only this parameter is set, Twilio will use your enabled Copilot Features to select the from phone number for delivery.

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

  • PersistentAction array[string]

    Rich actions for Channels Messages.

  • Whether to confirm delivery of the message. 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 false by default.

  • Indicates your intent to schedule a message. Pass the value fixed to schedule a message at a fixed time.

    Value is fixed.

  • SendAsMms boolean

    If set to True, Twilio will deliver the message as a single MMS message, regardless of the presence of media.

  • SendAt string(date-time)

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

  • Whether to detect Unicode characters that have a similar GSM-7 character and replace them. Can be: true or false.

  • StatusCallback string(uri)

    The URL we should call using the status_callback_method to send status information to your application. If specified, we POST these message status changes to the URL: queued, failed, sent, delivered, or undelivered. Twilio will POST its standard request parameters as well as some additional parameters including MessageSid, MessageStatus, and ErrorCode. If you include this parameter with the messaging_service_sid, we use this URL instead of the Status Callback URL of the Messaging Service. URLs must contain a valid hostname and underscores are not allowed.

  • To string(phone-number) Required

    The destination phone number in E.164 format for SMS/MMS or Channel user address for other 3rd-party channels.

  • How long in seconds the message can remain in our outgoing message queue. After this period elapses, the message fails and we call your status callback. Can be between 1 and the default value of 14,400 seconds. After a message has been accepted by a carrier, however, we cannot guarantee that the message will not be queued after this period. We recommend that this value be at least 5 seconds.

Responses

  • Created

    Hide response attributes Show response attributes object
    • account_sid string | null

      The SID of the Account that created the resource

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

    • api_version string | null

      The API version used to process the message

    • body string | null

      The message text

    • date_created string(date-time-rfc-2822) | null

      The RFC 2822 date and time in GMT that the resource was created

    • date_sent string(date-time-rfc-2822) | null

      The RFC 2822 date and time in GMT when the message was sent

    • date_updated string(date-time-rfc-2822) | null

      The RFC 2822 date and time in GMT that the resource was last updated

    • direction string | null

      The direction of the message

      Values are inbound, outbound-api, outbound-call, or outbound-reply.

    • error_code integer | null

      The error code associated with the message

    • error_message string | null

      The description of the error_code

    • from string(phone-number) | null

      The phone number that initiated the message

    • The SID of the Messaging Service used with the message.

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

    • num_media string | null

      The number of media files associated with the message

    • num_segments string | null

      The number of messages used to deliver the message body

    • price string | null

      The amount billed for the message

    • price_unit string(currency) | null

      The currency in which price is measured

    • sid string | null

      The unique string that identifies the resource

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

    • status string | null

      The status of the message

      Values are queued, sending, sent, failed, delivered, undelivered, receiving, received, accepted, scheduled, read, partially_delivered, or canceled.

    • subresource_uris object(uri-map) | null

      A list of related resources identified by their relative URIs

    • to string | null

      The phone number that received the message

    • uri string | null

      The URI of the resource, relative to https://api.twilio.com

POST /2010-04-01/Accounts/{AccountSid}/Messages.json
curl \
 -X POST https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Messages.json \
 --user "username:password" \
 -H "Content-Type: application/x-www-form-urlencoded" \
 -d 'AddressRetention=retain&ApplicationSid=string&Attempt=42&Body=string&ContentRetention=retain&ForceDelivery=true&From=string&MaxPrice=42.0&MediaUrl=https%3A%2F%2Fexample.com&MessagingServiceSid=string&PersistentAction=string&ProvideFeedback=true&ScheduleType=fixed&SendAsMms=true&SendAt=2023-05-04T09%3A42%3A00%2B00%3A00&SmartEncoded=true&StatusCallback=https%3A%2F%2Fexample.com&To=string&ValidityPeriod=42'
Request example
{
  "AddressRetention": "retain",
  "ApplicationSid": "string",
  "Attempt": 42,
  "Body": "string",
  "ContentRetention": "retain",
  "ForceDelivery": true,
  "From": "string",
  "MaxPrice": 42.0,
  "MediaUrl": [
    "https://example.com"
  ],
  "MessagingServiceSid": "string",
  "PersistentAction": [
    "string"
  ],
  "ProvideFeedback": true,
  "ScheduleType": "fixed",
  "SendAsMms": true,
  "SendAt": "2023-05-04T09:42:00+00:00",
  "SmartEncoded": true,
  "StatusCallback": "https://example.com",
  "To": "string",
  "ValidityPeriod": 42
}
Request examples
{
  "AddressRetention": "retain",
  "ApplicationSid": "string",
  "Attempt": 42,
  "Body": "string",
  "ContentRetention": "retain",
  "ForceDelivery": true,
  "From": "string",
  "MaxPrice": 42.0,
  "MediaUrl": [
    "https://example.com"
  ],
  "MessagingServiceSid": "string",
  "PersistentAction": [
    "string"
  ],
  "ProvideFeedback": true,
  "ScheduleType": "fixed",
  "SendAsMms": true,
  "SendAt": "2024-05-04T09:42:00+00:00",
  "SmartEncoded": true,
  "StatusCallback": "https://example.com",
  "To": "string",
  "ValidityPeriod": 42
}
Response examples (201)
{
  "account_sid": "string",
  "api_version": "string",
  "body": "string",
  "date_created": "string",
  "date_sent": "string",
  "date_updated": "string",
  "direction": "inbound",
  "error_code": 42,
  "error_message": "string",
  "from": "string",
  "messaging_service_sid": "string",
  "num_media": "string",
  "num_segments": "string",
  "price": "string",
  "price_unit": "string",
  "sid": "string",
  "status": "queued",
  "subresource_uris": {},
  "to": "string",
  "uri": "string"
}
Response examples (201)
{
  "account_sid": "string",
  "api_version": "string",
  "body": "string",
  "date_created": "string",
  "date_sent": "string",
  "date_updated": "string",
  "direction": "inbound",
  "error_code": 42,
  "error_message": "string",
  "from": "string",
  "messaging_service_sid": "string",
  "num_media": "string",
  "num_segments": "string",
  "price": "string",
  "price_unit": "string",
  "sid": "string",
  "status": "queued",
  "subresource_uris": {},
  "to": "string",
  "uri": "string"
}