Telnyx

Send your first SMS using the Telnyx Messaging API. This guide takes you from zero to sending a message in about 5 minutes by testing between two Telnyx numbers—no carrier registration required.

Prerequisites

A Telnyx account (free to create)

1. Get two phone numbers

Purchase two Telnyx numbers so you can test messaging between them without registration requirements.

Go to Numbers

Navigate to Numbers > Search & Buy in the portal.

Search for numbers

Enter your preferred area code or region, check SMS under features, and click Search.

Purchase two numbers

Click Add to Cart on two numbers, then Place Order.

Having two numbers lets you test on-net (Telnyx-to-Telnyx) messaging immediately, and also test receiving inbound messages.

2. Create a Messaging Profile

Go to Messaging

Navigate to Messaging in the portal.

Create a profile

Click Add new profile, give it a name (e.g., “My App”), and click Save.

Assign both numbers

Go to My Numbers, and for each number, click the Messaging Profile dropdown, select your profile, and save.

3. Get your API key

Go to API Keys and copy your API key (or create one if needed).

4. Send a message

curl -X POST https://api.telnyx.com/v2/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "from": "+15551234567",
    "to": "+15559876543",
    "text": "Hello, world!"
  }'

MMS messages support media attachments. Your number must be MMS-enabled.

curl -X POST https://api.telnyx.com/v2/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "from": "+15551234567",
    "to": "+15559876543",
    "text": "Check out this image!",
    "subject": "Picture",
    "media_urls": ["https://example.com/image.jpg"]
  }'

Media URLs must be publicly accessible.

Replace the placeholder values:

YOUR_API_KEY: Your API key from step 3
from: Your first Telnyx number (the sender)
to: Your second Telnyx number (the recipient)

E.164 format is required. Always include the + prefix, country code, and full number with no spaces or punctuation.

International number format examples

Country	Format	Example
US/Canada	+1 + 10 digits	`+15551234567`
UK	+44 + 10-11 digits (drop leading 0)	`+447911123456`
Germany	+49 + 10-11 digits (drop leading 0)	`+4915123456789`
Australia	+61 + 9 digits (drop leading 0)	`+61412345678`
Brazil	+55 + 10-11 digits	`+5511987654321`
India	+91 + 10 digits	`+919876543210`

Common mistakes:

❌ 15551234567 (missing +)
❌ +1 (555) 123-4567 (contains spaces and punctuation)
❌ +1-555-123-4567 (contains dashes)
✅ +15551234567

Sending to non-Telnyx numbers? Off-net messaging to external carriers typically requires sender registration (10DLC, toll-free verification, etc.). See Next steps for registration guides.

Response

A successful response looks like this:

{
  "data": {
    "record_type": "message",
    "direction": "outbound",
    "id": "b0c7e8cb-6227-4c74-9f32-c7f80c30934b",
    "type": "SMS",
    "messaging_profile_id": "16fd2706-8baf-433b-82eb-8c7fada847da",
    "from": {
      "phone_number": "+15551234567",
      "carrier": "Telnyx",
      "line_type": "Wireless"
    },
    "to": [
      {
        "phone_number": "+15559876543",
        "status": "queued",
        "carrier": "CARRIER",
        "line_type": "Wireless"
      }
    ],
    "text": "Hello, world!",
    "encoding": "GSM-7",
    "parts": 1,
    "cost": {
      "amount": 0.0051,
      "currency": "USD"
    }
  }
}

The status: "queued" means your message is on its way. Save the id to track delivery status.

Error handling

API errors return structured responses with error codes and messages. Handle these gracefully in your application:

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'],
});

try {
  const response = await client.messages.send({
    from: '+15551234567',
    to: '+15559876543',
    text: 'Hello, world!'
  });
  console.log('Message sent:', response.data.id);
} catch (error) {
  if (error.status === 422) {
    console.error('Validation error:', error.message);
    // Common: invalid phone number format, missing required fields
  } else if (error.status === 401) {
    console.error('Authentication failed. Check your API key.');
  } else if (error.status === 403) {
    console.error('Forbidden:', error.message);
    // Common: number not assigned to profile, registration required
  } else {
    console.error('Error:', error.message);
  }
}

Common errors

HTTP Status	Error	Solution
`401`	Invalid API key	Check your API key is correct and active
`403`	Number not enabled for messaging	Assign the `from` number to a messaging profile
`422`	Invalid `from` number format	Use E.164 format: `+15551234567`
`422`	Invalid `to` number format	Use E.164 format: `+15551234567`
`422`	Registration required	Register for 10DLC, toll-free verification, or another sender type
`422`	Message text too long	Split into multiple messages or reduce content
`402`	Insufficient balance	Add funds to your account

For delivery failures (after the message was accepted), check webhook events like message.finalized with status: "delivery_failed".

Webhooks and delivery tracking

After sending a message, Telnyx delivers real-time status updates via webhooks. Configure a webhook URL on your Messaging Profile to receive these events automatically.

Message lifecycle events

Messages progress through these statuses:

Event	Status	Description
`message.sent`	`sent`	Message accepted and sent to the carrier
`message.finalized`	`delivered`	Carrier confirmed delivery to the handset
`message.finalized`	`delivery_failed`	Carrier could not deliver the message
`message.finalized`	`delivery_unconfirmed`	No delivery confirmation received from the carrier

Not all carriers return delivery receipts. Some messages may remain in sent status without a finalized event. US carriers generally support delivery receipts for SMS; international coverage varies.

Webhook payload example

{
  "data": {
    "event_type": "message.finalized",
    "id": "e6e3e550-4e3f-4b3a-9e10-1c2d3e4f5a6b",
    "occurred_at": "2026-03-05T18:30:00.000+00:00",
    "payload": {
      "id": "b0c7e8cb-6227-4c74-9f32-c7f80c30934b",
      "record_type": "message",
      "direction": "outbound",
      "type": "SMS",
      "from": { "phone_number": "+15551234567" },
      "to": [
        {
          "phone_number": "+15559876543",
          "status": "delivered"
        }
      ],
      "text": "Hello, world!",
      "parts": 1,
      "cost": { "amount": "0.0051", "currency": "USD" },
      "errors": [],
      "completed_at": "2026-03-05T18:30:00.000+00:00"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://example.com/webhooks"
  }
}

Processing webhooks

Set up an endpoint to receive webhook POST requests and return a 200 response. Telnyx retries failed deliveries with exponential backoff.

import express from 'express';

const app = express();
app.use(express.json());

app.post('/webhooks/messaging', (req, res) => {
  const event = req.body.data;

  switch (event.event_type) {
    case 'message.sent':
      console.log(`Message ${event.payload.id} sent`);
      break;
    case 'message.finalized': {
      const status = event.payload.to[0].status;
      if (status === 'delivered') {
        console.log(`Message ${event.payload.id} delivered`);
      } else if (status === 'delivery_failed') {
        console.error(`Message ${event.payload.id} failed:`, event.payload.errors);
      }
      break;
    }
  }

  res.sendStatus(200);
});

app.listen(3000, () => console.log('Webhook server listening on port 3000'));

Retrieve message status via API

You can also check a message’s current status by its ID:

curl -X GET "https://api.telnyx.com/v2/messages/b0c7e8cb-6227-4c74-9f32-c7f80c30934b" \
  -H "Authorization: Bearer YOUR_API_KEY"

Delivery failure error codes

When a message fails delivery, the errors array in the webhook payload contains error codes:

Code	Description	Action
`30003`	Unreachable destination	Verify the number is active and can receive SMS
`30004`	Message blocked by carrier	Check content compliance and sender registration
`30005`	Unknown destination	Number may be disconnected or invalid
`30006`	Landline or unreachable	Number cannot receive SMS (landline, VoIP)
`30007`	Carrier violation	Message rejected due to content filtering
`30008`	Destination capacity exceeded	Retry after a delay

For a complete error code reference, see the Messaging Error Codes guide.

Webhook security

Validate incoming webhooks to ensure they’re from Telnyx:

IP allowlisting — Telnyx sends webhooks from 192.76.120.192/27
HTTPS endpoints — Always use HTTPS for your webhook URL
Respond quickly — Return 200 within 5 seconds to prevent retries

If your endpoint consistently fails to respond, Telnyx will retry with exponential backoff and eventually disable the webhook. Monitor your endpoint health to avoid missing delivery events.

Sending Messages

Messaging Profiles

Short Code

RCS

Hosted Numbers

Opt Outs

Phone Numbers

Toll Free Verification

10 DLC

Send Your First Message

Prerequisites

1. Get two phone numbers

2. Create a Messaging Profile

3. Get your API key

4. Send a message

Response

Error handling

Common errors

Webhooks and delivery tracking

Message lifecycle events

Webhook payload example

Processing webhooks

Retrieve message status via API

Delivery failure error codes

Webhook security

Next steps

Receive Messages

Choose a Sender Type

10DLC Registration

API Reference

Sending Messages

Messaging Profiles

Short Code

RCS

Hosted Numbers

Opt Outs

Phone Numbers

Toll Free Verification

10 DLC

​Prerequisites

​1. Get two phone numbers

​2. Create a Messaging Profile

​3. Get your API key

​4. Send a message

​Response

​Error handling

​Common errors

​Webhooks and delivery tracking

​Message lifecycle events

​Webhook payload example

​Processing webhooks

​Retrieve message status via API

​Delivery failure error codes

​Webhook security

​Next steps

Receive Messages

Choose a Sender Type

10DLC Registration

API Reference

Prerequisites

1. Get two phone numbers

2. Create a Messaging Profile

3. Get your API key

4. Send a message

Response

Error handling

Common errors

Webhooks and delivery tracking

Message lifecycle events

Webhook payload example

Processing webhooks

Retrieve message status via API

Delivery failure error codes

Webhook security

Next steps