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.

  1. 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

Copy
Copied
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"
}'

Note: After pasting the above content, Kindly check and remove any new line added

Example Response

Copy
Copied
{
  "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"
}

Note: After pasting the above content, Kindly check and remove any new line added

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:

Copy
Copied
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"}
    ]
}'

Note: After pasting the above content, Kindly check and remove any new line added

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.
  1. Replace the from number with your Telnyx number. Be sure to remove any delimiters like dashes or spaces.
  2. 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.
  3. 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.