Send MMS API

Legacy documentation

This page documents the v1 XML API. It remains supported, but it is no longer the recommended integration path. New integrations should use the Send MMS API v2, which uses JSON. If you are maintaining an existing v1 integration, the information on this page is still accurate.

sendMMS

Synopsis

This API sends an MMS to a single mobile number without creating an MMS Template. The MMS may contain slides embedded with video, audio, images, and/or text. 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.

Unlike the SaveMMS API which will save and transcode content, the sendMMS API 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 are able to transcode the video of your SendMMS message in advance.

If the sendMMS API is 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 is able to serve your files at the same speed as you make API requests.

When MMS is sent as Fallback SMS, the fallback SMS text and link are sent.

• The fallback SMS text is the text used in place of the MMS subject and is required if the subject is not passed in the request.
• The fallback SMS link is the link that hosts the MMS content. The fallback SMS link may be disabled by passing ‘yes’ to the DISABLEFALLBACKSMSLINK node. In this case only the MMS subject or the fallback SMS Text is sent. By default, we always send the fallback SMS link along with the fallback SMS text or the MMS subject.
• MMS Link Expiration Date is used to expire the link. Depending on this expiration date, the content is disabled on this link. By default it expires 365 days from the date the original MMS was created.

If “Enforce Campaign Check” is turned ON, then this function will require the campaign reference ID of the messaging campaign that the recipient’s phone number is subscribed into to be passed inside the campaignref node.

Line breaks are supported in the slide texts of the MMS.

Request: XML

<REQUEST>
    <ACTION>sendMMS</ACTION>
    <API_KEY>apiKey</API_KEY>
    <TO>Recipient phone number</TO>
    <TO_DISPLAYONLY>FULL-PHONE-NUMBER1,FULL-PHONE-NUMBER2,FULL-PHONE-NUMBER3</TO_DISPLAYONLY>
    <FROM>shortcode</FROM>
    <OPERATORID>OPERATORID</OPERATORID>
    <CAMPAIGNREF>CampaignReferenceID</CAMPAIGNREF>
    <SUBJECT>MMS Subject</SUBJECT>
    <NAME>Internal Name</NAME>
    <SLIDE> 
        <IMAGE>
            <URL>URL</URL> 
        </IMAGE>
        <AUDIO>
            <URL>**URL</URL>
        </AUDIO>
        <VIDEO>
            <URL>**URL</URL>
        </VIDEO>
        <VCARD>
            <URL>URL</URL>
        </VCARD>
        <ICAL>
            <URL>URL</URL>
        </ICAL>
        <PDF>
            <URL>URL</URL>
        </PDF>
        <TEXT>Plain Text</TEXT>
        <DURATION>Duration in seconds</DURATION>
    </SLIDE>
    <SLIDE>
        ...
    </SLIDE>
    <FALLBACKSMSTEXT>This text replaces the MMS subject when MMS is sent as SMS link</FALLBACKSMSTEXT>
    <DISABLEFALLBACKSMSLINK>'yes' to disable fallback SMS link</DISABLEFALLBACKSMSLINK>
    <MMSLINK_EXPIRATION_DATE>Date in ISO8601 format</MMSLINK_EXPIRATION_DATE>
    <FORCE_SEND_AS_SMS>true/false to send MMS as SMS</FORCE_SEND_AS_SMS>
    <CLIENT_REFERENCE>Client Reference</CLIENT_REFERENCE>
</REQUEST>

**Any parameters passed in the URL are not supported and will be stripped out. To pass unique IDs, you must do so in the filename or in the file path.

Request Parameters

Term	Mandatory/Optional	Description
ACTION	Mandatory	This is the name of the function you want to execute with the API.
API_KEY	Mandatory	Random key that is assigned to an account that can be used for authorization instead of USER/PASS. You can find and regenerate this key on the ‘API Settings’ page.
CAMPAIGNREF	Mandatory if “Enforce Campaign Check” is enabled	Depending on your API settings, you may be required to subscribe users into a campaign first before sending them messages. If you are required to subscribe a user first, then a valid Campaign Reference is required. This would be the campaign reference ID (string) to which the user is subscribed.
NAME	Mandatory	MMS template name for internal reference only.
DURATION	Optional	The duration of a slide displayed in seconds (integer).
FROM	Mandatory	A valid shortcode or longcode for the sender address(string). When sending to a list of many numbers using the ‘sendSavedContent’ function and if the ‘FROM’ value cannot be used for a certain country, then the system will re-write the sender address to use a valid shortcode for those numbers.
SLIDE	Mandatory	This represents a single slide within the MMS sequence the could include IMAGE/URL/TEXT/PIC etc. (There are special rules for slides within the ‘saveMMS’ special consideration section).
TEXT	Optional	The SMS message limit is 160 characters(string).
TO	Mandatory	This is the message recipient’s phone number in an international format.
TO_DISPLAYONLY	Optional	Multiple recipients are supported by adding the comma-separated phone numbers with country code.
SUBJECT	Optional	MMS Subject text. Limit subject to 40 characters for best deliverability. No unicode (emojis). Toll-Free Numbers may not support a Subject.
OPERATORID	Optional	Carrier ID for the Phone Number
FALLBACKSMSTEXT	Mandatory if subject is not passed	Text which gets sent when MMS is sent as SMS fallback. Limit text to 110 characters for best deliverability.
DISABLEFALLBACKSMSLINK	Optional	Set to true/false to disable appending a link to the MMS Content at the end of the SMS fallback text.
SLIDE:$CONTENT	Optional	Slide content node which contains the content URL. Acceptable slide content includes: image audio video vcard ical pdf text
SLIDE:$CONTENT:URL	Optional	Public content URL where the content is accessible.
SLIDE:TEXT	Optional	Text that is delivered alongside the content if added in a slide of the MMS.
SLIDE:DURATION	Optional	The duration (seconds) that the slide will remain on screen. Only applicable for feature phones.
MMSLINK_EXPIRATION_DATE	Optional	Expiration for SMS fallback link. If not passed, it is defaulted to 1 year from the date of this API request being made. The maximum duration is 1 year. Accepts ISO8601 Date format. Applies to only fallback SMS.
FORCE_SEND_AS_SMS	Optional	Set the value to Boolean “true” to force sending the MMS as SMS. In this scenario, the DISABLEFALLBACKSMS field value will be ignored. Additionally, if the OPERATORID/SPID value is not passed, the Operator Lookup is bypassed, and SMS is enforced, provided that the SMS Route is configured for that sender. If no value is passed, it defaults to Boolean “false.”
CLIENT_REFERENCE	Optional; String	Customer Transaction ID for the request. Use it to match the postbacks received for this API request. It accepts a maximum length of 64 characters.

Response Parameters

Param Name	Presence	Description
STATUS	Always	“Success” or “Failure”.
MMSID	Success response only	The ID (bigint) of a saved MMS.
TRACKINGID	Success response only	Transaction ID for the request. Use it to match the postbacks received for this API request.
TO	Success response only	Destination phone number with country code.
ERRORCODE	Error response only	Error code associated with the error.
ERRORINFO	Error response only	Error message explaining the error code.

Request Example: XML

<REQUEST>
    <ACTION>sendMMS</ACTION>
    <API_KEY>xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx</API_KEY>
    <TO>11111111111</TO>
    <FROM>00000</FROM>
    <OPERATORID>000189</OPERATORID>
    <SUBJECT>Free coupon!</SUBJECT>
    <CAMPAIGNREF>Campaign123</CAMPAIGNREF>
    <NAME>Membership coupon</NAME>
    <SLIDE>
        <IMAGE>
            <URL>https://fake-content-url.com/image.png</URL>
        </IMAGE>
        <TEXT>Hi! Thank you for joining us!</TEXT>
        <DURATION>5</DURATION>
    </SLIDE>
    <CLIENT_REFERENCE>5ZY7Cx1Xy0vs</CLIENT_REFERENCE>
</REQUEST>

Response Example: Success

<RESPONSE>
    <STATUS>Success</STATUS>
    <TO>11111111111</TO>
    <MMSID>35674</MMSID>
    <TRACKINGID>xxxxxxxxxxxx</TRACKINGID>
    <STATUSDETAILS>MMS request accepted and queued for delivery</STATUSDETAILS>
</RESPONSE>

Response Example: Failure

<RESPONSE>
    <STATUS>Failure</STATUS>
    <ERRORCODE>E111</ERRORCODE>
    <TO>11111111111</TO>
    <ERRORINFO>Invalid shortcode</ERRORINFO>
</RESPONSE>

Special considerations for sendMMS

• The API SHALL transcode the image content when necessary so that it can be delivered to the end user’s handset in the best possible way.
• The API SHALL NOT transcode Video/Audio content. If the total MMS Size exceeds the handset or carrier size, it may be delivered as SMS Fallback depending on your account type setting.
• Each request MUST contain at least one slide which MAY contain text and MAY contain an image, video, audio or other supported object.
• The API SHALL support up to 80 characters in the MMS subject. Extra characters MAY be cut-off from the MMS subject.
• The API SHALL support up to 9 slides for each MMS submission.
• The API SHALL NOT support multiple files of similar type on the same slide. In case, if multiple files of similar type are passed then by default only the first file is considered and the rest are ignored.
• Slides with images SHALL NOT support video but SHALL support audio.
• Slides with audio SHALL NOT support video.
• Slides with video SHALL support text.
• Slides with object type (i.e., vcard / ical / pdf ) SHALL NOT support other media types (i.e., audio, video, image).
• Slides with object type (i.e., vcard / ical / pdf ) SHALL support text. The text can be utilized to have fallback text or web link in the case of objects not supported on the device.
• The IOS device supports all the object types (i.e., vcard / ical / pdf ) in the MMS and the device will show the objects attached to the MMS as well as the fallback text/web link whereas the Androids/other devices which do not support these object types will only show the fallback text/web links.
• Slides with text SHALL support up to 5000 characters in any slide..
• Slides with text SHALL support characters that can be represented in Unicode. It should however be noted that destination devices may have limited Unicode capabilities. The preferred encoding is UTF-8.
• URLs provided MUST contain the full path to the files.
• When retrieving each file from the URLs the content-type header MUST be set to the correct MIME type for the file.
• MMS containing audio/video will be sent after audio/video encoding is completed.
• After submission you will not be given a successful acknowledgement of audio/video encoding immediately.
• The HTTP status of audio/video encoding after it has been completed will be sent to your postback URL.
• Supported Media: Text (text/plain), Image (gif, jpg, png, webp), Audio (mp3), and Video (3gp, mp4, mpeg).
• Supported Objects: VCF (text/vcard), ICS (text/calendar), PDF (application/pdf). There is a maximum source file size for each supported source file submitted.
• MMS messages are delivered in B64 encoding. To estimate the final size of Base64-encoded binary data, multiply the message size of the original data (including file attachments) by 1.37 + 814 bytes (for headers).

General Error Codes

Code	Description
E100	Invalid request. Make a valid request via GET/POST/XML with all the required variables.
E104	User Authentication Failed.
E105	This account has no API rights.
E106	You can call API every X seconds.
E107	This account has no rights to use this action.
E108	XML Parse error: $error.
E109	API not activated.
E112	IP was not whitelisted. API call rejected.
E113	Set throughput exceeded for this API action. API call rejected.
E114	Phone number is blacklisted. API call rejected.
E120	Account has reached the API request limit.
E503	Internal error.

Related Error Codes

All saveMMS Error Codes plus E110, E111, E241, E617, E618, E619, E627, E628, E629, E650

Code	Description
E110	Invalid receiver number.
E111	Invalid Sender.
E111	Invalid Sender to $country-name.
E116	Invalid display only phone number. {TO_DISPLAYONLY value}
E223	More than one object is not allowed in the same slide.
E224	MMS audio/video/image are not allowed with object in the same slide.
E225	Too many Slides.
E226	Audio and Video not allowed in same slide.
E227	Video and Image not allowed in same slide.
E228	Text more than X characters.
E229	Content not allowed.
E230	Bad X slide duration.
E241	This content does not exist.
E311	The ‘name’ is required.
E312	No slides.
E313	Slide X is empty.
E331	Image in slide X is too big.
E332	Audio in slide X is too big.
E333	Video in slide X is too big.
E334	Text in slide X is too long.
E335	vCard in slide X is too big.
E336	iCal in slide X is too big.
E337	PDF in slide X is too big.
E341	Image file in slide X is corrupted.
E351	Could not copy Image in slide X.
E352	Could not copy Audio in slide X.
E353	Could not copy Video in slide X.
E355	Could not copy vCard in slide X.
E356	Could not copy iCal in slide X.
E357	Could not copy PDF in slide X.
E617	mmslink_expiration_date is invalid.
E618	Carrier lookup failed. Please retry.
E619	Carrier not provisioned.
E622	The ‘fallbacksmstext’ is required.
E627	Invalid serviceid / serviceid is required
E628	Operator Not supported.
E629	Unrecognized content type.
E650	The ‘operator id’ is required.
E655	FORCE_SEND_AS_SMS node accepts only true/false values.
E715	Number is not subscribed in this campaign
E718	The ‘campaignref’ is required
E721	Invalid campaignref