Send a message

POST /messages

Send a message with a Phone Number, Alphanumeric Sender ID, Short Code or Number Pool.

This endpoint allows you to send a message with any messaging resource. Current messaging resources include: long-code, short-code, number-pool, and alphanumeric-sender-id.

Request

application/json

Body

Message payload

from address

Sending address (+E.164 formatted phone number, alphanumeric sender ID, or short code).

Required if sending with a phone number, short code, or alphanumeric sender ID.

messaging_profile_id string

Unique identifier for a messaging profile.

Required if sending via number pool or with an alphanumeric sender ID.

to addressrequired

Receiving address (+E.164 formatted phone number or short code).

text string

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

Required for SMS

subject string

Subject of multimedia message

media_urls url[]

A list of media URLs. The total media size must be less than 1 MB.

Required for MMS

webhook_url url

The URL where webhooks related to this message will be sent.

webhook_failover_url url

The failover URL where webhooks related to this message will be sent if sending to the primary URL fails.

use_profile_webhooks boolean

Default value: true

If the profile this number is associated with has webhooks, use them for delivery notifications. If webhooks are also specified on the message itself, they will be attempted first, then those on the profile.

type string

Possible values: [SMS, MMS]

The protocol for sending the message, either SMS or MMS.

auto_detect boolean

Automatically detect if an SMS message is unusually long and exceeds a recommended limit of message parts.

send_at date-timenullable

ISO 8601 formatted date indicating when to send the message - accurate up till a minute.

Responses

200: Successful response with details about a message.

application/json

Schema

data

object

record_type string

Possible values: [message]

Identifies the type of the resource.

direction string

Possible values: [outbound]

The direction of the message. Inbound messages are sent to you whereas outbound messages are sent from you.

id uuid

Identifies the type of resource.

type string

Possible values: [SMS, MMS]

The type of message.

messaging_profile_id string

Unique identifier for a messaging profile.

organization_id uuid

The id of the organization the messaging profile belongs to.

from

object

phone_number address

Sending address (+E.164 formatted phone number, alphanumeric sender ID, or short code).

carrier string

The carrier of the receiver.

line_type string

Possible values: [Wireline, Wireless, VoWiFi, VoIP, Pre-Paid Wireless, ``]

The line-type of the receiver.

object[]

Array [

phone_number address

Receiving address (+E.164 formatted phone number or short code).

status string

Possible values: [queued, sending, sent, expired, sending_failed, delivery_unconfirmed, delivered, delivery_failed]

The delivery status of the message.

carrier string

The carrier of the receiver.

line_type string

Possible values: [Wireline, Wireless, VoWiFi, VoIP, Pre-Paid Wireless, ``]

The line-type of the receiver.

]

text string

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

Required for SMS

subject stringnullable

Subject of multimedia message

media

object[]

Array [

url url

The url of the media requested to be sent.

content_type mime-typenullable

The MIME type of the requested media.

sha256 stringnullable

The SHA256 hash of the requested media.

size integernullable

The size of the requested media.

]

webhook_url urlnullable

The URL where webhooks related to this message will be sent.

webhook_failover_url urlnullable

The failover URL where webhooks related to this message will be sent if sending to the primary URL fails.

encoding string

Encoding scheme used for the message body.

parts integer

Possible values: >= 1 and <= 10

Number of parts into which the message's body must be split.

tags string[]

Tags associated with the resource.

cost

object

nullable

amount decimal

The amount deducted from your account.

currency iso4217

The ISO 4217 currency identifier.

cost_breakdown

object

nullable

Detailed breakdown of the message cost components.

carrier_fee

object

amount decimal

The carrier fee amount.

currency iso4217

The ISO 4217 currency identifier.

rate

object

amount decimal

The rate amount applied.

currency iso4217

The ISO 4217 currency identifier.

Detailed breakdown of the message cost components.

tcr_campaign_id stringnullable

The Campaign Registry (TCR) campaign ID associated with the message.

tcr_campaign_billable boolean

Indicates whether the TCR campaign is billable.

tcr_campaign_registered stringnullable

The registration status of the TCR campaign.

received_at date-time

ISO 8601 formatted date indicating when the message request was received.

sent_at date-time

ISO 8601 formatted date indicating when the message was sent.

completed_at date-time

ISO 8601 formatted date indicating when the message was finalized.

valid_until date-timenullable

Message must be out of the queue by this time or else it will be discarded and marked as 'sending_failed'. Once the message moves out of the queue, this field will be nulled

errors

Error[]

These errors may point at addressees when referring to unsuccessful/unconfirmed delivery statuses.

Array [

code integerrequired

title stringrequired

detail string

source

object

pointer json-pointer

JSON pointer (RFC6901) to the offending entity.

parameter string

Indicates which query parameter caused the error.

meta object

]

These errors may point at addressees when referring to unsuccessful/unconfirmed delivery statuses.

{
  "data": {
    "record_type": "message",
    "direction": "outbound",
    "id": "40385f64-5717-4562-b3fc-2c963f66afa6",
    "type": "MMS",
    "messaging_profile_id": "4000eba1-a0c0-4563-9925-b25e842a7cb6",
    "organization_id": "b448f9cc-a842-4784-98e9-03c1a5872950",
    "from": {
      "phone_number": "+18445550001",
      "carrier": "TELNYX LLC",
      "line_type": "VoIP"
    },
    "to": [
      {
        "phone_number": "+18665550001",
        "status": "queued",
        "carrier": "T-MOBILE USA, INC.",
        "line_type": "Wireless"
      }
    ],
    "cc": [],
    "text": "Hello, World!",
    "subject": "From Telnyx!",
    "media": [
      {
        "url": "https://pbs.twimg.com/profile_images/1142168442042118144/AW3F4fFD_400x400.png",
        "content_type": null,
        "sha256": null,
        "size": null
      }
    ],
    "webhook_url": "https://www.example.com/hooks",
    "webhook_failover_url": "https://backup.example.com/hooks",
    "encoding": "GSM-7",
    "parts": 1,
    "tags": [
      "Greetings"
    ],
    "cost": {
      "amount": 0.0051,
      "currency": "USD"
    },
    "cost_breakdown": {
      "carrier_fee": {
        "amount": 0.00305,
        "currency": "USD"
      },
      "rate": {
        "amount": 0.00205,
        "currency": "USD"
      }
    },
    "tcr_campaign_id": "TCPA3X7",
    "tcr_campaign_billable": true,
    "tcr_campaign_registered": "REGISTERED",
    "received_at": "2019-01-23T18:10:02.574Z",
    "sent_at": null,
    "completed_at": null,
    "valid_until": null,
    "errors": []
  }
}

default: Unexpected error

application/json

Schema

errors

Error[]

Array [

code integerrequired

title stringrequired

detail string

source

object

pointer json-pointer

JSON pointer (RFC6901) to the offending entity.

parameter string

Indicates which query parameter caused the error.

meta object

]

{
  "errors": [
    {
      "code": "string",
      "title": "string",
      "detail": "string",
      "source": {
        "pointer": "string",
        "parameter": "string"
      },
      "meta": {}
    }
  ]
}

Callbacks

Request samples

curl -L 'https://api.telnyx.com/v2/messages' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
-d '{
  "from": "+18445550001",
  "messaging_profile_id": "abc85f64-5717-4562-b3fc-2c9600000000",
  "to": "+18445550001",
  "text": "Hello, World!",
  "subject": "From Telnyx!",
  "media_urls": [
    "http://example.com"
  ],
  "webhook_url": "http://example.com/webhooks",
  "webhook_failover_url": "https://backup.example.com/hooks",
  "use_profile_webhooks": true,
  "type": "MMS"
}'

Response samples

{
  "data": {
    "record_type": "message",
    "direction": "outbound",
    "id": "40385f64-5717-4562-b3fc-2c963f66afa6",
    "type": "MMS",
    "messaging_profile_id": "4000eba1-a0c0-4563-9925-b25e842a7cb6",
    "organization_id": "b448f9cc-a842-4784-98e9-03c1a5872950",
    "from": {
      "phone_number": "+18445550001",
      "carrier": "TELNYX LLC",
      "line_type": "VoIP"
    },
    "to": [
      {
        "phone_number": "+18665550001",
        "status": "queued",
        "carrier": "T-MOBILE USA, INC.",
        "line_type": "Wireless"
      }
    ],
    "cc": [],
    "text": "Hello, World!",
    "subject": "From Telnyx!",
    "media": [
      {
        "url": "https://pbs.twimg.com/profile_images/1142168442042118144/AW3F4fFD_400x400.png",
        "content_type": null,
        "sha256": null,
        "size": null
      }
    ],
    "webhook_url": "https://www.example.com/hooks",
    "webhook_failover_url": "https://backup.example.com/hooks",
    "encoding": "GSM-7",
    "parts": 1,
    "tags": [
      "Greetings"
    ],
    "cost": {
      "amount": 0.0051,
      "currency": "USD"
    },
    "cost_breakdown": {
      "carrier_fee": {
        "amount": 0.00305,
        "currency": "USD"
      },
      "rate": {
        "amount": 0.00205,
        "currency": "USD"
      }
    },
    "tcr_campaign_id": "TCPA3X7",
    "tcr_campaign_billable": true,
    "tcr_campaign_registered": "REGISTERED",
    "received_at": "2019-01-23T18:10:02.574Z",
    "sent_at": null,
    "completed_at": null,
    "valid_until": null,
    "errors": []
  }
}

{
  "errors": [
    {
      "code": "string",
      "title": "string",
      "detail": "string",
      "source": {
        "pointer": "string",
        "parameter": "string"
      },
      "meta": {}
    }
  ]
}

Send a message

Request ​

Body

Responses ​

Callbacks ​

Request

Responses

Callbacks