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

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"
}