Skip to content
MMS/
/MMS

Sinch Messaging and Content APIs | Sinch (2.0)

Send and receive MMS messages using the JSON API.

Download OpenAPI description
mms.json
mms.yaml
Overview
support at sinch
support@sinch.com
License
MIT
Languages
Servers
https://api.ci.mblox.com/ep/v2/

MMS

This API sends, saves, or sends a saved MMS defined in the JSON to a single mobile number. The sent or saved MMS may contain slides embedded with text, images, videos, audios, and/or other objects. Calls to the API are made in the form of HTTP requests using the POST request method with UTF-8 encoded JSON data passed inside the request body. All requests are expected to include a content-type HTTP header (for example, Content-Type: application/json; charset=utf-8).

Important:

Sinch will send an HTTP GET request to the server that is specified in the JSON slide of the embedded images, videos, audios, and/or other object URIs to retrieve the contents of the media file. The HTTP response header Sinch receives from the server MUST contain the Content-Length field indicating the size of the resource. Otherwise, the API request will fail. Customers using CDNs that employ chunked transfer encoding may run into problems in which the server returns a Transfer-Encoding field with a value of "chunked" specified in the HTTP GET response, rather than the server returning Content-Length. If a Transfer-Encoding field with a value of "chunked" is specified in an HTTP, the API request will be rejected.

Important:

All media files are expected to serve a valid content-type header (for example, text/plain, image/gif, audio/mp3, video/mp4, etc.). If a file server serves a file using the application/octet-stream content-type header instead, it may be rejected if the MIME type cannot be determined by other means.

Operations

Send, save, or send a saved MMS

Request

This request is used to send, save, or send a saved MMS message.

Security
ApiKey
Bodyapplication/jsonrequired

This request is used to send, save, or send a saved MMS message.

actionstringrequired

The action for this API request. In this case, to send an MMS.

ValueDescription
sendmms

Send an MMS

Discriminator
service-idstringrequired

The ID of the campaign.

tostringrequired

Destination phone number with country code.

fromstringrequired

Shortcode, or Toll Free, or 10DLC with country code.

slideArray of image (object) or audio (object) or video (object) or contact (object) or calendar (object) or pdf (object)required

Slide content node which contains the content URL. Must contain at least one slide object. A maximum of 8 slides may be specified for a single MMS message. Acceptable slide content includes:

  • image (cannot be used with video, contact, calendar, or pdf)
  • audio (cannot be used with video, contact, calendar, or pdf)
  • video (cannot be used with image, audio, contact, calendar, or pdf)
  • contact (cannot be used with image, audio, or video)
  • calendar (cannot be used with image, audio, or video)
  • pdf (cannot be used with image, audio, or video)
  • message-text (maximum of 5000 characters)

Note that you cannot include multiple files of the same MIME type on the same slide. Also note that, if transcoding is ON for the account, the API shall reformat the content when necessary, so it can be delivered to the end-users handset in the best possible way.

Any of:

Supports .jpg (image/jpg, image/jpeg), .png (image/png), and .gif (image/gif).

slide[].​imageobject
slide[].​message-textstring

Text that is delivered alongside the content if added in a slide of the MMS. Supports plain text. Maximum of 5000 characters.

Example: "This is an example of message text."
from-maskstring

Only carriers in certain countries allow Alphanumeric senders. Not supported in the USA.

message-subjectstring

MMS subject text. Limit to 40 characters for best deliverability. Maximum of 80 characters.

fallback-sms-textstring

Must be included if disable-fallback-sms is set to false. Text to be included when SMS sent as a fallback. For best deliverability, limit string to 110 characters.

disable-fallback-sms-linkboolean

Set to true to prevent a link to the MMS content from being included in the SMS fallback message.

disable-fallback-smsboolean

Set to true to prevent delivery of fallback SMS message.

fallback-sms-link-expirationstring(date-time)

Expiration for the SMS fallback link. If not populated, defaults to 1 year from the time and date at which the API request was made. Maximum of 1 year. Accepts ISO8601 Date format. Only applies to fallback SMS messages.

mms-expiry-timestampstring(date-time)

MMS delivery attempts will stop after the date and time specified in this field. If the MMS is already delivered to the device, it will remain in the device's inbox. If not populated, the expiration value defaults to 3 days from the time and date at which the API request was made. Maximum of 3 days. Accepts ISO8601 Date format.

client-referencestring

Customer transaction ID of the request. Passed back in all postbacks for this transaction. Maximum length of 64 characters.

cache-contentboolean

Caching is done for every sendmms request by default unless overridden by the API request by populating this field with false. If cache is found, the original content won't be downloaded to validate.

curl -i -X POST \
  https://api.ci.mblox.com/ep/v2/ \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -d '{
    "action": "sendmms",
    "service-id": "YOUR_CAMPAIGN_ID",
    "to": "RECIPIENT_PHONE_NUMBER_WITH_COUNTRY_CODE",
    "from": "YOUR_PHONE_NUMBER",
    "from-mask": "YOUR_MASK",
    "message-subject": "YOUR_SUBJECT_TEXT",
    "fallback-sms-text": "TEXT_OF_FALLBACK_SMS",
    "disable-fallback-sms-link": false,
    "disable-fallback-sms": false,
    "fallback-sms-link-expiration": "EXPIRATION_DATE_UTC",
    "mms-expiry-timestamp": "ISO8601_DATE_FORMAT",
    "client-reference": "CLIENT_SUPPLIED_IDENTIFIER",
    "cache-content": true,
    "slide": [
      {
        "image": {
          "url": "{Image URL}"
        },
        "message-text": "{Slide message text}"
      },
      {
        "audio": {
          "url": "{Audio URL}"
        },
        "message-text": "{Slide message text}"
      },
      {
        "video": {
          "url": "{Video URL}"
        },
        "message-text": "{Slide message text}"
      },
      {
        "contact": {
          "url": "{Contact URL}"
        },
        "message-text": "{Slide message text}"
      },
      {
        "calendar": {
          "url": "{PDF URL}"
        },
        "message-text": "{Slide message text}"
      },
      {
        "pdf": {
          "url": "{PDF URL}"
        },
        "message-text": "{Slide message text}"
      }
    ]
  }'

Responses

Response

Bodyapplication/json
statusstring

Indicates the status of the action. Either success or failure.

Enum ValueDescription
success

A response indicating success.

failure

A response indicating failure.

status-detailsstring

More details about the status of the action. Returned with success status for any action.

tracking-idstring

Transaction ID for the request. Used for identifying postbacks received for this API request. Returned with success status for any action.

tostring

Destination phone number with country code. Returned when sendmms or sendsavedmms have a success status.

mms-idstring

The ID of the sent MMS template. Returned when sendsavedmms has a success status.

fromstring

Shortcode or Toll Free/10DLC number with country code that will be used to send a saved MMS. Returned when sendsavedmms has a success status.

error-codestring

Code that identifies the specific error that was encountered. Returned with failure status for any action.

error-infostring

Message that explains the error code. Returned with failure status for any action.

Response
application/json
{
  "status": "success",
  "to": "DESTINATION_PHONE_NUMBER",
  "tracking-id": "UNIQUE-TRANSACTION-ID",
  "status-details": "MMS request accepted and queued for processing and delivery."
}