Skip to main content

Send a message

POST 
/messages

Sends a message by submitting an outbound message request.

FieldNotes
from

The sending phone number (i.e., source of the message) can be one of your existing SMS-enabled phone numbers or blank if using the Number Pool feature.

delivery_status_webhook_url
delivery_status_failover_url

Default: ""

Delivery status webhooks are configured on a per request basis (i.e., included in the payload of each request).

When configured, the Telnyx Messaging Services will attempt to POST to it each time the state (i.e., status) changes. The current MDR is included as the request's payload.

A valid webhook URL sting must include the HTTP(S) scheme. Using HTTPS is highly encouraged.
i.e., Begins with "http[s]://"

SUCCESS RESPONSE ​

Extended documentation

statusMDR status field
statusMDR delivery_status field

Request ​

Body

required

Details of the outbound message requested

    from string

    Sending address (+E.164 formatted phone number, alphanumeric sender, or short code). If you wish to send from a long code or short code, the number must be assigned to the messaging profile for this request. If you wish to send using an alphanumeric sender, supply any valid alphanumeric sender value in this field. This field is optional if Number Pool feature is enabled. When enabled, the Number Pool algorithm will fill in a from number for you.

    to stringrequired

    Receiving address (+E.164 formatted phone number)

    body stringrequired

    Message body (i.e., content) as non-empty string

    delivery_status_webhook_url string

    Possible values: Value must match regular expression ^(https?://)

    Webhook to call when the message's 'status' changes

    delivery_status_failover_url string

    Possible values: Value must match regular expression ^(https?://)

    Failover webhook to call when the message's 'status' changes

    check_sender_health boolean

    Check the sender's health status before accepting the request. When set to true, Telnyx will reject requests using an unhealthy sending address.

Responses ​

200: Details the submitted request

Schema

    sms_id uuidrequired

    ID of message (Telnyx-specific)

    gw_sms_id uuid

    ID of message used off-network (Unlikely to be used, unless contacting Telnyx Support)

    user_id uuidrequired

    ID of user who owns the sending phone number

    status string

    Possible values: [sending, gw_timeout, sent, dlr_timeout, delivered, failed]

    State of the POST /messages request

    delivery_status string

    NOTE: 'status' refers to the state of the message [request].

    'delivery_status' is used to pass back to you miscellaneous information, which often relates to the delivery status webhooks.

    profile_id uuidrequired

    ID of messaging profile to which the sending phone number is assigned

    msg

    object

    required

    src stringrequired

    Sending address (+E.164 formatted phone number, alphanumeric sender, or short code). This corresponds to the 'from' payload field of the POST /messages request.

    dst stringrequired

    Receiving address (+E.164 formatted phone number). This corresponds to the 'to' payload field of the POST /messages request.

    body stringrequired

    Message body (i.e., content) as a non-empty string

    is_mms boolean

    A flag indicating whether the message is a multimedia message

    delivery_status_webhook_url string

    Possible values: Value must match regular expression ^(https?://)

    Webhook to call when the message's 'status' changes

    delivery_status_failover_url string

    Possible values: Value must match regular expression ^(https?://)

    Failover webhook to call when the message's 'status' changes

Request samples

curl -L 'https://sms.telnyx.com/messages' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
  "from": "+18665550001",
  "to": "+18445550001",
  "body": "Hello!",
  "delivery_status_webhook_url": "https://mysite.com/7420/updates",
  "delivery_status_failover_url": "https://mysite.com/7420/backup/updates",
  "check_sender_health": true
}'

Response samples

{
  "sms_id": "c51c89d9-68ad-4db2-a471-cf622d21c40d",
  "gw_sms_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "user_id": "834f3d53-8a3c-4aa0-a733-7f2d682a72df",
  "status": "sending",
  "delivery_status": "success",
  "profile_id": "16fd2706-8baf-433b-82eb-8c7fada847da",
  "msg": {
    "src": "+18665550001",
    "dst": "+18005550001",
    "body": "Hello!",
    "is_mms": true
  },
  "delivery_status_webhook_url": "https://mysite.com/7420/updates",
  "delivery_status_failover_url": "https://mysite.com/7420/backup/updates"
}