Send a message

Sends a message by submitting an outbound message request.

Field Notes
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

status MDR status field
status MDR delivery_status field
Request
Request Body schema: application/json
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
required
string

Receiving address (+E.164 formatted phone number)

body
required
string

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

delivery_status_webhook_url
string^(https?://)
Default: ""

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

delivery_status_failover_url
string^(https?://)
Default: ""

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

check_sender_health
boolean
Default: false

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

post/messages
Request samples
application/json
{}
Response samples
application/json
{
  • "sms_id": "c51c89d9-68ad-4db2-a471-cf622d21c40d",
  • "gw_sms_id": "",
  • "user_id": "834f3d53-8a3c-4aa0-a733-7f2d682a72df",
  • "status": "sending",
  • "delivery_status": "success",
  • "profile_id": "16fd2706-8baf-433b-82eb-8c7fada847da",
  • "msg": {
    },
  • "delivery_status_webhook_url": "https://mysite.com/7420/updates",
  • "delivery_status_failover_url": "https://mysite.com/7420/backup/updates"
}