Just as in the case of SMS, one needs to make a POST request to https://sms.telnyx.com/send. The request must have the following structure:

  • Request header: x-profile-secret - same as in the case of SMS
  • Request fields: must be provided as a JSON object
  • from: the source number, in e164 format. This number must be attached to a messaging profile.
  • to: The destination number, in e164 format.
  • body: a JSON object describing the multimedia content (see below).

Note that the main feature distinguishing an MMS request from an SMS request is the type of body. If body is a string, then an SMS will be sent. If body is a JSON object, then an MMS will be sent.

The body must have one of the following forms:


"body": {
"subject": "",
"media_urls": [
{"": ""}, {"": ""}, ...
}]] >


"body": {
"subject": "",
"smil": ""
}]] >


"body": {
"subject": "",
"text": ""
}]] >

In the first case the user must prepare publicly accessible URLs with multimedia. 

If you do not see the file you wish to send on the list above, please feel free to ask the NOC if your file is supported.

Then the list of the multimedia URLs will go into "media_urls" list. Example:

"body": {
"subject": "Cat Pictures",
"media_urls": [
{"img": "http://www.test.com/path/to/cat/picture1.jpg"},
{"img": "http://www.test.com/path/to/cat/picture2.jpg"}
}]] >

The above will send an MMS containing two images. Note that in each media_url object, the type of multimedia must be specified ("img" in the above example). Other allowable types are: "text", "audio", and "video".  Also note that you may only include a maximum of 10 files, and that total size of all files must be below the allotted amount.  
In the second case, the body object contains a "smil" field whose value should be a SMIL description of the multimedia message. Just like in the first case all media URLs in the SMIL description must be publicly accessible.

The third case will create a text-only MMS (note that a text-only MMS is different than SMS!).

Sample request:

curl -X POST -H 'Content-Type: application/json'
-H 'x-profile-secret:'
-d '{"from": "+15555555555", "to": "+15556666666", "body": { "subject": "Cat", "media_urls" : [{"img": "http://www.test.com/cat/picture.jpg"}] }}'
https://sms.telnyx.com/send]] >

MMS File Types and Sizes

Telnyx accepts a variety of file types, including:

  • image files: jpeg, png, gif
  • audio files: MP3, OGG, AMR
  • text files: PDF, vcard, txt 
  • video files: mp4 

The destination carrier determines the maximum allowable size an MMS attachment can be:  

  • Tier 1 Carriers -- Verizon, T-Mobile, AT&T, Spring -- all MMS content up to about 1 MB.  
  • Tier 2 Carriers allow MMS content of 600 KB.  
  • Tier 3 Carriers allow MMS content of 300 KB. 

To discover the carrier a phone number belongs to, you may utilize the Extended LRN Look-up's spid_carrier_name.  Alternatively, if the file size is too large for the destination carrier, Telnyx will convert it into a link.  

Receiving MMS

Your DID's settings will determine if the number is SMS or MMS capable with a checkmark.

Please note that currently it is up to the user to distinguish MMS and SMS messages arriving at the webhook. One way to distinguish them is to check the Content-Type header (it will be multipart/form-data for MMS).

Did this answer your question?