Skip to main content
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

​
1. Get two phone numbers

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

Go to Numbers

Navigate to Numbers > Search & Buy in the portal.
2

Search for numbers

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

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

1

Go to Messaging

Navigate to Messaging in the portal.
2

Create a profile

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

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!"
  }'
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.
CountryFormatExample
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 StatusErrorSolution
401Invalid API keyCheck your API key is correct and active
403Number not enabled for messagingAssign the from number to a messaging profile
422Invalid from number formatUse E.164 format: +15551234567
422Invalid to number formatUse E.164 format: +15551234567
422Registration requiredRegister for 10DLC, toll-free verification, or another sender type
422Message text too longSplit into multiple messages or reduce content
402Insufficient balanceAdd funds to your account
For delivery failures (after the message was accepted), check webhook events like message.finalized with status: "delivery_failed".

​
Next steps

Receive Messages

Set up webhooks to receive incoming SMS

Choose a Sender Type

Learn about long codes, toll-free, and short codes

10DLC Registration

Register your brand for US messaging compliance

API Reference

Explore all messaging parameters