Choose:

Sending a Message

In this tutorial, you’ll learn how to send SMS and MMS messages using the Telnyx v1 API and the curl command.

Portal Setup

Follow the setup guide to configure your Portal for sending and receiving messages.

To authorize your requests, you will need get the secret for the Messaging Profile that you will be using. To find your Messaging Profile secret in the Portal, go to the Messaging section and click the edit symbol next to your Messaging Profile. The profile secret can be found under “Outbound” in your settings. (Note that your profile must be configured to use API v1.)

You can replace the current secret at any time by generating a new profile secret.

Development Environment Setup

No development prerequisites are required for this tutorial. You can paste the below snippets into your terminal on Mac and Linux computers. Windows users should install bash on Windows.

Send an SMS or MMS

Follow the steps below to send SMS and MMS messages.

Using the SMS or MMS examples below, write a curl command that will submit an outbound message request. Include your profile secret in the X-Profile-Secret request header, and add the source (from) and destination (to) phone numbers, and the message’s content (body) into the payload. Optionally, your payload may include a delivery_status_webhook_url or delivery_status_failover_url (or both).

Note: Don’t forget to update YOUR_MESSAGING_PROFILE_SECRET in the below commands.

Send SMS

curl -X POST "https://sms.telnyx.com/messages" \
  -H "Content-Type: application/json" \
  -H "X-Profile-Secret: YOUR_MESSAGING_PROFILE_SECRET" \
  -d '{
    "from": "+13125550001",
    "to": "+13129450002",
    "body": "Hello!",
    "delivery_status_webhook_url": "https://example.com/campaign/7214"
}'

Example Response

{
  "sms_id": "834f3d53-8a3c-4aa0-a733-7f2d682a72df",
  "gw_sms_id": "",
  "user_id": "a9b37e61-32bc-4a03-bf90-080c3b55db6f",
  "profile_id": "16fd2706-8baf-433b-82eb-8c7fada847da",
  "status": "queued",
  "delivery_status": "",
  "msg": {
    "src": "+13125550001",
    "dst": "+13129450002",
    "body": "Hello, world!",
    "is_mms": false
  },
  "coding": 0,
  "parts": 1,
  "created": 1522097596060,
  "updated": 1522097596061,
  "delivery_status_webhook_url": "https://example.com/campaign/7214",
  "delivery_status_failover_url": "",
  "errors": [],
  "date_created": "2018-03-26T20:53:16.060000",
  "date_updated": "2018-03-26T20:53:16.061000",
  "carrier": "SOME CARRIER",
  "line_type": "Wireless"
}

Notes:
Make sure you’re using the full +E.164 formatted number for your to and from numbers. In the US and Canada, this typically means adding +1 to the beginning of your 10-digit phone number.
This example includes a delivery status webhook URL. This field is optional, but useful if you want real-time updates about the status of the message.

Send MMS

For MMS messages, the structure of the send request differs, in order to accommodate different types of media.

Send a message with an image URL:

curl -X POST "https://sms.telnyx.com/messages" \
  -H "Content-Type: application/json" \
  -H "X-Profile-Secret: YOUR_MESSAGING_PROFILE_SECRET" \
  -d '{
    "from": "+13125550001",
    "to": "+13129450002",
    "subject": "Picture",
    "media_urls" : [
      {"img": "https://picsum.photos/500.jpg"}
    ]
}'

Notes:
The from number here must be MMS enabled.
The key in each object listed in media_urls is used to specify the type of media. Possible values are img, audio, video, text.
Media URLs must be publicly accessible.

Replace the from number with your Telnyx number. Be sure to remove any delimiters like dashes or spaces.
Replace the to number with the number you want to send a message to. Make sure you’re using the full +E.164 formatted number. In the US and Canada, this typically means adding +1 to the beginning of your 10-digit phone number.
Run the updated curl command.

In a few moments you’ll receive a message at your number on your device. Congrats, you’ve just sent your first SMS or MMS.

Next, learn how to receive messages with Telnyx.

Sending a Message

In this tutorial, you’ll learn how to send SMS and MMS messages using the Telnyx v1 API and Python.

Portal Setup

Follow the setup guide to configure your Portal for sending and receiving messages.

You can replace the current secret at any time by generating a new profile secret.

Development Environment Setup

Check out the development prerequisites to set up your Python development environment for this guide.

Send an SMS or MMS

Follow the steps below to send SMS and MMS messages.

Create a new file called send.py and paste in either the SMS or MMS example code given below.

Note: Don’t forget to update YOUR_MESSAGING_PROFILE_SECRET in the below commands.

Send SMS

import requests

profile_secret = "YOUR_MESSAGING_PROFILE_SECRET"

headers = {
    "X-Profile-Secret": profile_secret,
}
url = "https://sms.telnyx.com/messages"
payload = {
  "from": "+13125550001",
  "to": "+13129450002",
  "body": "Hello, World!",
  "delivery_status_webhook_url": "https://example.com/campaign/7214",
}

response = requests.post(
    url,
    headers=headers,
    json=payload
)

Example Response

{
  "sms_id": "834f3d53-8a3c-4aa0-a733-7f2d682a72df",
  "gw_sms_id": "",
  "user_id": "a9b37e61-32bc-4a03-bf90-080c3b55db6f",
  "profile_id": "16fd2706-8baf-433b-82eb-8c7fada847da",
  "status": "queued",
  "delivery_status": "",
  "msg": {
    "src": "+13125550001",
    "dst": "+13129450002",
    "body": "Hello, world!",
    "is_mms": false
  },
  "coding": 0,
  "parts": 1,
  "created": 1522097596060,
  "updated": 1522097596061,
  "delivery_status_webhook_url": "https://example.com/campaign/7214",
  "delivery_status_failover_url": "",
  "errors": [],
  "date_created": "2018-03-26T20:53:16.060000",
  "date_updated": "2018-03-26T20:53:16.061000",
  "carrier": "SOME CARRIER",
  "line_type": "Wireless"
}

Notes:
Make sure you’re using the full +E.164 formatted number for your to and from numbers. In the US and Canada, this typically means adding +1 to the beginning of your 10-digit phone number.
This example includes a delivery status webhook URL. This field is optional, but useful if you want real-time updates about the status of the message.

Send MMS

import requests

profile_secret = 'YOUR_MESSAGING_PROFILE_SECRET'

headers = {
    'x-profile-secret': profile_secret,
}
url = 'https://sms.telnyx.com/messages'
payload = {
    "from": "+13115552368",
    "to": "+13115552367",
    "body": {
        "subject": "Picture",
        "media_urls": [
            {"img": "https://picsum.photos/500.jpg"}
        ]
    }
}

response = requests.post(
    url,
    headers=headers,
    json=payload
)

print(response.text)

Notes:
The from number here must be MMS enabled.
The key in each object listed in media_urls is used to specify the type of media. Possible values are img, audio, video, text.
Media URLs must be publicly accessible.

Replace the from number with your Telnyx number. Be sure to remove any delimiters like dashes or spaces.
Replace the to number with the number you want to send a message to. Make sure you’re using the full +E.164 formatted number. In the US and Canada, this typically means adding +1 to the beginning of your 10-digit phone number.
Customize the text message and save the changes to send.py.
Run the script.

python send.py

In a few moments you’ll receive a message at your number on your device. Congrats, you’ve just sent your first SMS or MMS.

Next, learn how to receive messages with Telnyx.

Sending a Message

In this tutorial, you’ll learn how to send SMS and MMS messages using the Telnyx v1 API and Ruby.

Portal Setup

Follow the setup guide to configure your Portal for sending and receiving messages.

You can replace the current secret at any time by generating a new profile secret.

Development Environment Setup

The Telnyx API v1 works by POSTing JSON data to a REST endpoint. We’ll use the Ruby gem httparty to send the requests:

gem install httparty

Send an SMS or MMS

Follow the steps below to send SMS and MMS messages.

Create a new file called send.rb and paste in either the SMS or MMS example code given below.

Note: Don’t forget to update YOUR_MESSAGING_PROFILE_SECRET in the below commands.

Send SMS

require 'httparty'

profile_secret = "YOUR_MESSAGING_PROFILE_SECRET"

http_headers = {
    "X-Profile-Secret" => profile_secret,
    "Content-Type" => "application/json"
}

payload = {
    "from": "YOUR_TELNYX_NUMBER",
    "to": "DESTINATION_NUMBER",
    "body": "Hello, world!",
    "delivery_status_webhook_url": "https://example.com/campaign/7214"
}

HTTParty.post("https://sms.telnyx.com/messages",
    :body => payload.to_json,
    :headers => http_headers,
)

Example Response

{
  "sms_id": "834f3d53-8a3c-4aa0-a733-7f2d682a72df",
  "gw_sms_id": "",
  "user_id": "a9b37e61-32bc-4a03-bf90-080c3b55db6f",
  "profile_id": "16fd2706-8baf-433b-82eb-8c7fada847da",
  "status": "queued",
  "delivery_status": "",
  "msg": {
    "src": "+13125550001",
    "dst": "+13129450002",
    "body": "Hello, world!",
    "is_mms": false
  },
  "coding": 0,
  "parts": 1,
  "created": 1522097596060,
  "updated": 1522097596061,
  "delivery_status_webhook_url": "https://example.com/campaign/7214",
  "delivery_status_failover_url": "",
  "errors": [],
  "date_created": "2018-03-26T20:53:16.060000",
  "date_updated": "2018-03-26T20:53:16.061000",
  "carrier": "SOME CARRIER",
  "line_type": "Wireless"
}

Notes:
Make sure you’re using the full +E.164 formatted number for your to and from numbers. In the US and Canada, this typically means adding +1 to the beginning of your 10-digit phone number.
This example includes a delivery status webhook URL. This field is optional, but useful if you want real-time updates about the status of the message.

Send MMS

require 'httparty'

profile_secret = "YOUR_MESSAGING_PROFILE_SECRET"

http_headers = {
    "X-Profile-Secret" => profile_secret,
    "Content-Type" => "application/json"
}

payload = {
    "from": "YOUR_TELNYX_NUMBER",
    "to": "DESTINATION_NUMBER",
    "body": {
        "subject": "Picture",
        "media_urls": [{
            "img": "https://picsum.photos/500.jpg"
        }]
    }
}

HTTParty.post("https://sms.telnyx.com/messages",
    :body => payload.to_json,
    :headers => http_headers,
)

Notes:
The from number here must be MMS enabled.
The key in each object listed in media_urls is used to specify the type of media. Possible values are img, audio, video, text.
Media URLs must be publicly accessible.

Replace YOUR_TELNYX_NUMBER number with your Telnyx number. Be sure to remove any delimiters like dashes or spaces.
Replace DESTINATION_NUMBER number with the number you want to send a message to. Make sure you’re using the full +E.164 formatted number. In the US and Canada, this typically means adding +1 to the beginning of your 10-digit phone number.
Customize the text message and save the changes to send.rb.
Run the script.

ruby send.rb

In a few moments you’ll receive a message at your number on your device. Congrats, you’ve just sent your first SMS or MMS.

Next, learn how to receive messages with Telnyx.

Sending a Message

In this tutorial, you’ll learn how to send SMS and MMS messages using the Telnyx v1 API and Node.js.

Portal Setup

Follow the setup guide to configure your Portal for sending and receiving messages.

You can replace the current secret at any time by generating a new profile secret.

Development Environment Setup

The Telnyx API v1 works by POSTing JSON data to a REST endpoint. We’ll use the library superagent to send the requests.

# With npm:
npm install superagent --save

# Or with yarn:
yarn add superagent

Send an SMS or MMS

Follow the steps below to send SMS and MMS messages.

Create a new file called send.js and paste in either the SMS or MMS example code given below.

Note: Don’t forget to update YOUR_MESSAGING_PROFILE_SECRET in the below commands.

Send SMS

const superagent = require('superagent');

const headers = {
  'X-Profile-Secret': 'YOUR_MESSAGING_PROFILE_SECRET',
}

const payload = {
  'from': 'YOUR_TELNYX_NUMBER',
  'to': 'DESTINATION_NUMBER',
  'body': 'Hello, world!',
  'delivery_status_webhook_url': 'https://example.com/campaign/7214'
}

superagent
  .set(headers)
  .post('https://sms.telnyx.com/messages')
  .send(payload)
  .then((response) => {
    const body = response.body;
    console.log('body:', body);
  })
  .catch((err) => {
    console.log('error:', err);
  })
});

Example Response

{
  "sms_id": "834f3d53-8a3c-4aa0-a733-7f2d682a72df",
  "gw_sms_id": "",
  "user_id": "a9b37e61-32bc-4a03-bf90-080c3b55db6f",
  "profile_id": "16fd2706-8baf-433b-82eb-8c7fada847da",
  "status": "queued",
  "delivery_status": "",
  "msg": {
    "src": "YOUR_TELNYX_NUMBER",
    "dst": "DESTINATION_NUMBER",
    "body": "Hello, world!",
    "is_mms": false
  },
  "coding": 0,
  "parts": 1,
  "created": 1522097596060,
  "updated": 1522097596061,
  "delivery_status_webhook_url": "https://example.com/campaign/7214",
  "delivery_status_failover_url": "",
  "errors": [],
  "date_created": "2018-03-26T20:53:16.060000",
  "date_updated": "2018-03-26T20:53:16.061000",
  "carrier": "SOME CARRIER",
  "line_type": "Wireless"
}

Notes:
Make sure you’re using the full +E.164 formatted number for your to and from numbers. In the US and Canada, this typically means adding +1 to the beginning of your 10-digit phone number.
This example includes a delivery status webhook URL. This field is optional, but useful if you want real-time updates about the status of the message.

Send MMS

const superagent = require('superagent');

const headers = {
  'X-Profile-Secret': 'YOUR_MESSAGING_PROFILE_SECRET',
}

const payload = {
  'from': 'YOUR_TELNYX_NUMBER',
  'to': 'DESTINATION_NUMBER',
  'subject': 'Picture',
  'media_urls': [{
    'img': 'https://picsum.photos/500.jpg'
  }]
}

superagent
  .set(headers)
  .post('https://sms.telnyx.com/messages')
  .send(payload)
  .then((response) => {
    const body = response.body;
    console.log('body:', body);
  })
  .catch((err) => {
    console.log('error:', err);
  })
});

Notes:
The from number here must be MMS enabled.
The key in each object listed in media_urls is used to specify the type of media. Possible values are img, audio, video, text.
Media URLs must be publicly accessible.

Replace YOUR_TELNYX_NUMBER number with your Telnyx number. Be sure to remove any delimiters like dashes or spaces.
Replace DESTINATION_NUMBER number with the number you want to send a message to. Make sure you’re using the full +E.164 formatted number. In the US and Canada, this typically means adding +1 to the beginning of your 10-digit phone number.
Customize the text message and save the changes to send.js.
Run the script.

node send.js

In a few moments you’ll receive a message at your number on your device. Congrats, you’ve just sent your first SMS or MMS.

Next, learn how to receive messages with Telnyx.