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.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
- SMS
- MMS
YOUR_API_KEY: Your API key from step 3from: 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
International number format examples
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:status: "queued" means your message is on its way. Save the id to track delivery status.
Error handling
API errors return structured JSON responses with an error code, title, and detail message. Handle these in your application to provide clear feedback and enable automatic recovery.Error response format
SDK error handling examples
HTTP error codes
Error codes returned by this endpoint
POST /v2/messages request-validation errors return general API error codes, not messaging-specific codes. Codes verified against the live API:
Notes:
- The number-pool check runs before destination validation: with an empty profile pool, an invalid
tois never reported — you get40321instead. fromis optional whenmessaging_profile_idis present; sending with only a profile and a pool number succeeds.- Self-sends (
fromequal toto) are rejected with40310(Source and destination cannot be the same number). - Recipient opt-outs (
40300) are returned synchronously by this endpoint: a send to a blocked recipient is rejected with40300(Blocked due to STOP message), matching Opt-in/opt-out. Opt-out rules apply at the messaging profile level. See also the current request-error reference for40300in the Messaging Error Codes guide, which classifies it under API request errors returned immediately.
This endpoint’s request errors currently do not use the
40001/42200-series codes documented here and in the Messaging Error Codes guide. Code against the general codes above until the API and that guide are reconciled.Legacy error codes not returned by this endpoint
The codes below are not returned by this endpoint — kept for reference until the API and the Messaging Error Codes guide are reconciled:
For delivery failure codes and the full error reference, see the Messaging Error Codes guide. Note that guide and this page currently disagree on
40300 (STOP opt-out vs number not assigned to a messaging profile).
Rate limiting
The Telnyx Messaging API enforces rate limits to ensure platform stability. When you exceed the limit, the API returns429 Too Many Requests with a retry-after header.
Rate limit headers:
Best practices for high-volume sending:
- Implement exponential backoff: wait
2^attemptseconds between retries (1s, 2s, 4s, 8s…) - Add jitter to prevent thundering herd:
wait = base_wait * (0.5 + random()) - Set a maximum retry count (3–5 attempts) to avoid infinite loops
- Use a message queue (Redis, RabbitMQ, SQS) to buffer outbound messages and control throughput
- Monitor
x-ratelimit-remainingand slow down before hitting the limit
Troubleshooting checklist
If your message fails to send, work through this checklist:1
Verify API key
Confirm your API key is active at API Keys. Revoked or expired keys return
401.2
Check number assignment
Verify your
from number is assigned to a messaging profile at My Numbers. Unassigned numbers return 403.3
Confirm E.164 format
Both
from and to must be in E.164 format: +15551234567. No spaces, dashes, or parentheses.4
Check sender registration
Sending to US carriers off-net requires registration. Check your registration status:
- 10DLC: 10DLC Registration
- Toll-free: Toll-Free Verification
- Short code: Short Codes
5
Verify account balance
Insufficient balance returns
402. Check and top up at Billing.6
Check message content
- SMS body must not exceed 1,600 characters
- MMS media URLs must be publicly accessible HTTPS URLs
- Content must comply with carrier guidelines (no SHAFT content without proper registration)
7
Review webhook events
If the API returns
200 but the message doesn’t arrive, check message.finalized webhook events for delivery failure details. See Webhooks and delivery tracking.Still stuck? Check the Telnyx Status Page for platform issues, or contact support with your message ID from the API response.
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: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
Processing webhooks
Set up an endpoint to receive webhookPOST requests and return a 200 response. Telnyx retries failed deliveries with exponential backoff.
Retrieve message status via API
You can also check a message’s current status by its ID:Delivery failure error codes
When a message fails delivery, theerrors array in the webhook payload contains error codes:
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
200within 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.
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