Telnyx Messaging
Send, schedule and track SMS/MMS messages through Telnyx, look up phone numbers before sending, and review messaging profiles, sender numbers and opt-outs. Curated from Telnyx's official OpenAPI specification.
Connect this API to an AI agent Browse all specs
What you can do with Telnyx Messaging via MCP
Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.
| Method | Path | Operation | Description |
|---|---|---|---|
| GET | /messaging_profiles |
listMessagingProfiles | List messaging profiles |
| GET | /messaging_profiles/{id} |
getMessagingProfile | Get one messaging profile |
| GET | /messaging_profiles/{id}/phone_numbers |
listProfilePhoneNumbers | List the phone numbers on a messaging profile |
| GET | /phone_numbers/messaging |
listPhoneNumbersWithMessagingSettings | List your phone numbers with their messaging settings |
| GET | /number_lookup/{phone_number} |
lookupNumber | Look up carrier, line type and caller name for a phone number |
| GET | /messages/{id} |
getMessage | Get a message and its delivery status |
| DELETE | /messages/{id} |
cancelScheduledMessage | Cancel a scheduled message that has not been sent |
| GET | /messaging_optouts |
listOptOuts | List numbers that opted out of messages |
| POST | /messages |
sendMessage | Send an SMS or MMS message |
| POST | /messages/schedule |
scheduleMessage | Schedule an SMS or MMS message for later |
Authentication
BearerAuth
Bearer token — sent as Authorization: Bearer <token>
Telnyx API key sent as Authorization: Bearer <API key>.
How to get a credential
- Sign in to the Telnyx Mission Control Portal (portal.telnyx.com).
- Open Account Settings > Keys & Credentials > API Keys.
- Click Create API Key and copy the key (it starts with
KEY). It is shown only once. - Make sure your sending number is assigned to a messaging profile (Messaging > Messaging Profiles).
Permissions used
| Access | Operations |
|---|---|
| Messaging (read) | getMessage, listMessagingProfiles, getMessagingProfile, listProfilePhoneNumbers, listPhoneNumbersWithMessagingSettings, listOptOuts |
| Messaging (send) | sendMessage, scheduleMessage, cancelScheduledMessage |
| Number Lookup (billed per lookup) | lookupNumber |
Telnyx API keys have full account access; use a dedicated key for this connection.
Common errors
- 401 Unauthorized: the key is wrong, revoked or missing the
Bearerprefix. Create a new key. - 403 Forbidden: the account is not verified for this feature or destination (e.g. level 2 verification, 10DLC campaign). Complete it in the portal.
- 400/422: invalid
from/to(use E.164, e.g.+15551234567) or thefromnumber has no messaging profile. - 429 Too Many Requests: rate or per-number throughput limit hit; wait and retry.
Store the key as a VX Agents credential (Bearer token); never paste it into chat.
Usage guide
Setup
- Add a Telnyx API key as the Bearer credential (Mission Control Portal > Account Settings > Keys & Credentials).
- Your sending number must belong to a messaging profile. Run
listPhoneNumbersWithMessagingSettingsonce and pin your defaultfromnumber (E.164) and, if you use number pools or alphanumeric sender IDs, themessaging_profile_id.
Send and track a message
- If the recipient number is new or unverified, call
lookupNumberto confirm it is valid and see the line type (mobile vs landline). Each lookup is billed. - Check
listOptOuts(filter by messaging profile) when sending marketing or bulk messages; never message a number that opted out. - Show the user the recipient, sender and text, and get confirmation. Then call
sendMessagewithfrom,toandtext(addmedia_urlsfor MMS). For a later send usescheduleMessagewithsend_at. - Save the returned message
id. CallgetMessagewith it to read the delivery status (queued,sent,delivered,sending_failed,delivery_failed) and anyerrors. - To stop a scheduled message before it goes out, confirm with the user, then call
cancelScheduledMessagewith the id.
Review the account
listMessagingProfiles/getMessagingProfile: profiles, webhook URLs and number-pool settings.listProfilePhoneNumbers: which numbers send under a profile.
Good to know
- Phone numbers are E.164 (
+15551234567).send_atis ISO 8601 (UTC, minute precision). - Sending costs money and reaches real people: always confirm
sendMessageandscheduleMessagebefore calling them. - US long codes need a registered 10DLC campaign; unregistered traffic is blocked or filtered.
- Long texts are split into multiple parts and billed per part; the response shows
parts. - List endpoints page with the
pageobject (number,sizeup to 250; default 20). - Delivery status updates take seconds to minutes; poll
getMessagesparingly.
How to use this spec
- Create a free VX Agents account (sandbox tools included).
- Open the marketplace and connect “Telnyx Messaging” to an agent.
- Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.