Skip to main content
Send SMS and MMS messages using the Telnyx Messaging API. This guide covers the basics of sending messages programmatically.

​
Prerequisites

Before you begin:
  1. Sign up for a Telnyx account
  2. Configure your Portal for messaging
  3. Get your API Key
Use +E.164 format for all phone numbers (e.g., +15551234567 for US/Canada numbers).

​
Send SMS

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!"
  }'

​
Example response

{
  "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"
    }
  }
}
  • Ensure your from number is eligible to send to the destination. Learn about traffic types.
  • For alphanumeric sender IDs, include messaging_profile_id in your request.
  • Webhook URLs default to your messaging profile settings. Override them with webhook_url and webhook_failover_url.

​
Send MMS

MMS messages support media attachments like images. The from 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.
  • Passing an empty media_urls array sends an MMS with subject/text only (no media).
  • The subject field is MMS-only and replaces text content when provided.

​
Next steps