The Sinch SMS REST API supports MMS messages in some circumstances. MMS support is currently available in the following destinations:
- US
- Canada
- Australia
- Puerto Rico
To enable MMS support in SMS, contact your account manager.
Just as with standard SMS messages and message batches, you can send an MMS message or a batch of MMS messages using the MediaRequest body, recieve corresponding callbacks, and poll for delivery reports related to those batches of MMS messages.
This document provides general guidance for using the SMS API to send MMS messages. For more thorough recommendations and information on MMS support and constraints, see the sinch MMS channel best practices documentation.
The operation to send an MMS message, or a batch of MMS messages, has many of the same parameters and fields as the operation to send SMS messages. However, there are a few fields that require special attention when sending MMS messages using the SMS REST API:
- The
typefield of the request must always be set tomt_media - You must always populate the
urlfield of thebodyobject. To include text with your media, populate themessagefield of thebodyas well - The
strict_validationfield, which is optional, allows you to enable message validation against sinch MMS channel best practices
For example, consider the following message, which includes media and text:
In order to send this message, you would make a call to the SMS REST API's batch send endpoint with the following payload:
Cannot find OpenAPI operation by operationId or pointer
There are other optional objects and fields you can populate in the request as well. These are documented in both the API reference and the Parameters and properties section below.
Below are the supported media types and corresponding constraints for sending and receiving an MMS message using the SMS REST API:
image: .jpg, .png (please observe that .jpg files have wider support on mobile devices than .png files)
video: .mp4, .gif, .mov
vCard (Virtual Contact File): .vcf
PDF files: .pdf
We recommend you to keep media file sizes under 1MB as MMS providers usually use this limit.
The following image gives an example of a media message.
Note that the above message includes media and no text. In this case, the body object does not include a populated message field.
For more recommendations and information on MMS support and constraints, see the sinch MMS channel best practices documentation.
The full list and description of the parameters and properties that can be included in the request body for sending a batch of MMS messages is below:
List of Phone numbers and group IDs that will receive the batch. More info
Sender number. Must be valid phone number, short code or alphanumeric. Required if Automatic Default Originator not configured.
The message content, including a URL to the media file
The subject text
The message text. Text only media messages will be rejected, please use SMS instead.
URL to the media file
Contains the parameters that will be used for customizing the message for each recipient.
MMS
| Value | Description |
|---|---|
| mt_media | MMS |
Kind of delivery report
| Enum Value | Description |
|---|---|
| none | No delivery report callback will be sent. |
| summary | A single delivery report callback will be sent. |
| full | A single delivery report callback will be sent which includes a list of recipients per delivery status. |
| per_recipient | A delivery report callback will be sent for each status change of a message. This could result in a lot of callbacks and should be used with caution for larger batches. These delivery reports also include a timestamp of when the Delivery Report originated from the SMSC. |
| per_recipient_final | A delivery report callback representing the final status of a message will be sent for each recipient. This will send only one callback per recipient, compared to the multiple callbacks sent when using |
If set in the future, the message will be delayed until send_at occurs. Must be before expire_at. If set in the past, messages will be sent immediately. Formatted as ISO-8601: YYYY-MM-DDThh:mm:ss.SSSZ.
If set, the system will stop trying to deliver the message at this point. Must be after send_at. Default and max is 3 days after send_at. Formatted as ISO-8601: YYYY-MM-DDThh:mm:ss.SSSZ.
Override the default callback URL for this batch. Must be valid URL.
The client identifier of a batch message. If set, the identifier will be added in the delivery report/callback of this batch
If set to true, then feedback is expected after successful delivery.
Whether or not you want the media included in your message to be checked against Sinch MMS channel best practices. If set to true, your message will be rejected if it doesn't conform to the listed recommendations, otherwise no validation will be performed.
Incoming MMS messages can be received in two ways:
Media attached to the incoming message will be uploaded to the Sinch-provided or customer-provided storage (you must contact your account manager to have custom storage provisioned to your account) and the URL(s) to download the media will be returned. In the event of an error, an error code will be returned.
Any text content included in attached .txt files will be added to the message itself, rather than being included in a separate downloadable file.
Cannot find OpenAPI operation by operationId or pointer
If you run into an issue while using the SMS REST API to send MMS messages, ensure that:
- You have MMS functionality enabled on your account. If do not, contact your account manager
- All required fields are populated, including the
urlfield in thebodyobject - The
typefield is set tomt_media - The HTTP server that provides the media sets
Content-Typein the header of the response - Downloading the media from that HTTP server takes less than 60 seconds