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> <ACTION>sendMMS</ACTION> <API_KEY>apiKey</API_KEY> <TO>Recipient phone number</TO> <FROM>shortcode</FROM> <FROM_MASK>*shortcodeMask</FROM_MASK> <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> </REQUEST> *ShortcodeMask (Alphanumeric sender) is allowed only in few countries. Not supported in the United States. **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.
|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.|
|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|
|FROM_MASK||Optional||Only carriers in certain countries allow Alphanumeric senders. Not supported in the USA.|
|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:|
|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.|
|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> </REQUEST>
Response Example: Success
<RESPONSE> <STATUS>Success</STATUS> <TO>11111111111</TO> <MMSID>35674</MMSID> <TRACKINGID>xxxxxx-xxxxx-xx</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), 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:
|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.|
Related Error Codes:
All saveMMS Error Codes plus E110, E111, E241, E617, E618, E619, E627, E628, E629, E650
|E110||Invalid receiver number.|
|E111||Invalid Sender to $country-name.|
|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.|
|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.|
|E715||Number is not subscribed in this campaign|
|E718||The ‘campaignref’ is required|