Sending a Message' fill-rule='evenodd'%3E %3Cpath d='M7.778 7.975a2.5 2.5 0 0 0 .347-3.837L6.017 2.03a2.498 2.498 0 0 0-3.542-.007 2.5 2.5 0 0 0 .006 3.543l1.153 1.15c.07-.29.154-.563.25-.773.036-.077.084-.16.14-.25L3.18 4.85a1.496 1.496 0 0 1 .002-2.12 1.496 1.496 0 0 1 2.12 0l2.124 2.123a1.496 1.496 0 0 1-.333 2.37c.16.246.42.504.685.752z'/%3E %3Cpath d='M5.657 4.557a2.5 2.5 0 0 0-.347 3.837l2.108 2.108a2.498 2.498 0 0 0 3.542.007 2.5 2.5 0 0 0-.006-3.543L9.802 5.815c-.07.29-.154.565-.25.774-.036.076-.084.16-.14.25l.842.84c.585.587.59 1.532 0 2.122-.587.585-1.532.59-2.12 0L6.008 7.68a1.496 1.496 0 0 1 .332-2.372c-.16-.245-.42-.503-.685-.75z'/%3E %3C/g%3E %3C/svg%3E)
In this tutorial, you’ll learn how to send SMS and MMS messages using the Telnyx
v1 API and the curl command.
Portal Setup' fill-rule='evenodd'%3E %3Cpath d='M7.778 7.975a2.5 2.5 0 0 0 .347-3.837L6.017 2.03a2.498 2.498 0 0 0-3.542-.007 2.5 2.5 0 0 0 .006 3.543l1.153 1.15c.07-.29.154-.563.25-.773.036-.077.084-.16.14-.25L3.18 4.85a1.496 1.496 0 0 1 .002-2.12 1.496 1.496 0 0 1 2.12 0l2.124 2.123a1.496 1.496 0 0 1-.333 2.37c.16.246.42.504.685.752z'/%3E %3Cpath d='M5.657 4.557a2.5 2.5 0 0 0-.347 3.837l2.108 2.108a2.498 2.498 0 0 0 3.542.007 2.5 2.5 0 0 0-.006-3.543L9.802 5.815c-.07.29-.154.565-.25.774-.036.076-.084.16-.14.25l.842.84c.585.587.59 1.532 0 2.122-.587.585-1.532.59-2.12 0L6.008 7.68a1.496 1.496 0 0 1 .332-2.372c-.16-.245-.42-.503-.685-.75z'/%3E %3C/g%3E %3C/svg%3E)
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' fill-rule='evenodd'%3E %3Cpath d='M7.778 7.975a2.5 2.5 0 0 0 .347-3.837L6.017 2.03a2.498 2.498 0 0 0-3.542-.007 2.5 2.5 0 0 0 .006 3.543l1.153 1.15c.07-.29.154-.563.25-.773.036-.077.084-.16.14-.25L3.18 4.85a1.496 1.496 0 0 1 .002-2.12 1.496 1.496 0 0 1 2.12 0l2.124 2.123a1.496 1.496 0 0 1-.333 2.37c.16.246.42.504.685.752z'/%3E %3Cpath d='M5.657 4.557a2.5 2.5 0 0 0-.347 3.837l2.108 2.108a2.498 2.498 0 0 0 3.542.007 2.5 2.5 0 0 0-.006-3.543L9.802 5.815c-.07.29-.154.565-.25.774-.036.076-.084.16-.14.25l.842.84c.585.587.59 1.532 0 2.122-.587.585-1.532.59-2.12 0L6.008 7.68a1.496 1.496 0 0 1 .332-2.372c-.16-.245-.42-.503-.685-.75z'/%3E %3C/g%3E %3C/svg%3E)
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' fill-rule='evenodd'%3E %3Cpath d='M7.778 7.975a2.5 2.5 0 0 0 .347-3.837L6.017 2.03a2.498 2.498 0 0 0-3.542-.007 2.5 2.5 0 0 0 .006 3.543l1.153 1.15c.07-.29.154-.563.25-.773.036-.077.084-.16.14-.25L3.18 4.85a1.496 1.496 0 0 1 .002-2.12 1.496 1.496 0 0 1 2.12 0l2.124 2.123a1.496 1.496 0 0 1-.333 2.37c.16.246.42.504.685.752z'/%3E %3Cpath d='M5.657 4.557a2.5 2.5 0 0 0-.347 3.837l2.108 2.108a2.498 2.498 0 0 0 3.542.007 2.5 2.5 0 0 0-.006-3.543L9.802 5.815c-.07.29-.154.565-.25.774-.036.076-.084.16-.14.25l.842.84c.585.587.59 1.532 0 2.122-.587.585-1.532.59-2.12 0L6.008 7.68a1.496 1.496 0 0 1 .332-2.372c-.16-.245-.42-.503-.685-.75z'/%3E %3C/g%3E %3C/svg%3E)
Follow the steps below to send SMS and MMS messages.
- 1Using the SMS or MMS examples below, write a
curl
command that will submit an outbound message request. Include your profile secret in theX-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 adelivery_status_webhook_url
ordelivery_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
andfrom
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 areimg
,audio
,video
,text
.- Media URLs must be publicly accessible.
- 2Replace the
from
number with your Telnyx number. Be sure to remove any delimiters like dashes or spaces. - 3Replace 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. - 4Run 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.