The sendmms action

This action sends MMS defined in the JSON to a single mobile number. The sent MMS may contain slides embedded with text, images, videos, audios, and/or other objects. The slides are created and sent in the order given in the API call. Not all messaging clients will render the order properly when received. 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).

Unlike the savemms action, which will save and transcode content, the sendmms action will only optimize image content and will not transcode any other content such as audio or video. Therefore, we strongly suggest that you use the savemms API call when sending video content unless you can transcode the video of your sendmms message in advance.

If the sendmms action used to send the same content to multiple users, the content will be retrieved from your server for each request. Please ensure that the server storing your content can serve your files at the same speed as you make API requests.

Important:
Sinch will send an HTTP GET request to the server that is specified in the XML 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.

Fallback SMS considerations

If the MMS message is too large to be delivered or the carrier does not support MMS delivery, the API has an option to facilitate MMS delivery as fallback SMS. The fallback SMS consists of two parts: the fallback SMS text and the fallback SMS link.

The fallback SMS text

The fallback SMS text is the SMS text that will be sent instead of the MMS. The fallback SMS link, used to view the MMS content, is also sent. You can dynamically change the fallback SMS text by populating the fallback-sms-text field. If disable-fallback-sms is set node is set to true, then the fallback SMS text is not required. By default, the fallback SMS is enabled. If the MMS was attempted to be sent as SMS and the fallback SMS is disabled, the message sending will fail.

The fallback SMS link

The fallback SMS link is the link that hosts the MMS content. The fallback SMS link may be disabled by setting disable-fallback-sms-link to true; in this case only the fallback SMS text is sent. By default, we always send the fallback SMS link along with the fallback SMS text.

The fallback SMS link expiration defines how long the MMS sent as SMS using this mms-id is valid and viewable on the mobile browser. By default, it is set to one year if no value is passed. The maximum expiration duration cannot be more than one year.

Content transcoding

Every MMS created using the JSON API will be transcoded for the destination handset based on your Account Settings. Additionally, any MMS which triggers an SMS Fallback containing a link to the MMS content hosted on a web page is optimized for the mobile web browser. To transcode a binary MMS, we must know what type of handset the user has. We are able to obtain this handset type information from delivery receipts, and we store the record in a handset cache for later use. We have a database of attributes which we manually match to every new handset in the cache, allowing us to adapt the content during MMS delivery.

Special considerations

  • Always use international number format. You must use the international format when sending MMS. International format includes both the country code and the phone number. We use the country code to determine routing of the message. There should be no dialing prefixes (for example, no 00 or 001). For example, the US number 774-555-9144 in international number format would be 17745559144 because the USA country code is 1.
  • Each MMS message must include at least one slide. That slide may containt text and an image, video, audio, or other supported object. A maximum of eight slides per submission is supported.
  • Line breaks are supported in the slide texts of the MMS.
  • Provided URLs must contain the full path to the content files.
  • Always set the proper file MIME type headers and extensions. Extensions are optional in the filename as long as the proper MIME type is set in the headers for that content. It is always recommended to use the proper file extension AND set the MIME type header. Query strings are supported for files.
  • Delivery success takes precedence over audio and video content quality. Occasionally, the picture quality will be reduced to fit handset message size requirements.
  • Video content may be reduced in quality to fit delivery limitations and, if it still does not fit, will be delivered as a fallback SMS.
  • If transcoding is ON for the account, MMS containing audio/video can be used only when the audio/video encoding is completed.
    • After message submission, you will not be given a successful acknowledgement of audio/video encoding.
    • The status of audio/video encoding will be sent to your Postback URL after it has been completed.
  • Content validation rules:
    • Supported MIME TYPE and Supported Extension SHALL pass at validation and transcoding.
    • Supported MIME TYPE and Invalid Extension SHALL pass at validation and transcoding.
    • Supported MIME TYPE and No Extension SHALL pass at validation and transcoding.
    • "Octet-stream" MIME TYPE and Supported Extension SHALL pass at validation and transcoding assuming the content is what the extension claims. Otherwise, it SHALL fail at transcoding.
    • "Octet-stream" MIME TYPE and Invalid Extension SHALL fail at validation.
    • "Octet-stream" MIME TYPE and No Extension SHALL fail at validation.
  • On an IOS device, contact, calendar, and pdf objects are delivered as binary attachments in the MMS. On an Android device, only contact is delivered as binary attachment in the MMS and calendar/pdf are delivered as downloadable web links in the MMS. All other devices, contact, calendar, and pdf are delivered as downloadable web links in the MMS. If the handset is unknown, contact is delivered as binary attachment and calendar/pdf are delivered as downloadable web links by default.
  • Each supported source file has a maximum file size. See your API settings to see the current maximum file size value.
  • MMS messages are delivered in B64 encoding. To estimate the final size of Base64 encoded binary data, multiply the file size by 1.37 times the original data size + 814 bytes (for headers).

URL Handling and HTTP Status Code Compliance

The API accepts URLs and retrieves data based on the provided HTTP status codes and Content MIME Types.

In the case of HTTP Status Codes, the API follows specific rules for handling redirections. Accepted Status Codes are 200, 301, 302, 303, 307 and 308. For codes in the 3xx range (301, 302, 303, 307, 308), the API allows a maximum of 1 redirection i.e., if a URL returns a 3xx status code and requires redirection, the API will follow the redirection only once.

More info on HTTP Status Codes below:

  • 200 OK: The request was successful, and the data is returned.
  • 301 Moved Permanently: The requested URL has been permanently moved.
  • 302 Found: The requested URL has been temporarily moved.
  • 303 See Other: The response to the request can be found at another URL.
  • 307 Temporary Redirect: The requested URL has been temporarily moved, and the same method should be used to request the new URL.
  • 308 Permanent Redirect: The requested URL has been permanently moved, and the same method should be used to request the new URL.

Sample payload

{
  • "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": [
    • {
      },
    • {
      },
    • {
      },
    • {
      },
    • {
      },
    • {
      }
    ]
}

Sample response

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

Schema

action
required
string
Default: "sendmms"

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

service-id
required
string

The ID of the campaign.

to
required
string

Destination phone number with country code.

from
required
string

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

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

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.

from-mask
string

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

message-subject
string

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

fallback-sms-text
string

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-link
boolean

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

disable-fallback-sms
boolean

Set to true to prevent delivery of fallback SMS message.

fallback-sms-link-expiration
string <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-timestamp
string <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-reference
string

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

cache-content
boolean

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.

Response schema

status
string

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

status-details
string

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

tracking-id
string

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

to
string

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

mms-id
string

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

from
string

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-code
string

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

error-info
string

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

We'd love to hear from you!
Rate this content:
Still have a question?
 
Ask the community.
SecurityPrivacyLegal & ComplianceCookie Statement
© 2024 Sinch. All rights reserved.