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)
Use E.164 format for phone numbers: + followed by country code and number (e.g., +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.

​
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