(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start': new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0], j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.data-privacy-src= 'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f); })(window,document,'script','dataLayer','GTM-TT9ZP96');

Knowledge Base

Send MMS API

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>
    <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>
    <FORCE_SEND_AS_SMS>true/false to send MMS as SMS</FORCE_SEND_AS_SMS>
    <CLIENT_REFERENCE>Client Reference</CLIENT_REFERENCE>
</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.

Request Parameters

TermMandatory/OptionalDescription
ACTIONMandatoryThis is the name of the function you want to execute with the API.
API_KEYMandatoryRandom 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.
CAMPAIGNREFMandatory if “Enforce Campaign Check” is enabledDepending 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.
NAMEMandatoryMMS template name for internal reference only.
DURATIONOptionalThe duration of a slide displayed in seconds (integer).
FROMMandatoryA 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.
SLIDEMandatoryThis 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).
TEXTOptionalThe SMS message limit is 160 characters(string).
TOMandatoryThis is the message recipient’s phone number in an international format.
SUBJECTOptionalMMS Subject text. Limit subject to 40 characters for best deliverability. No unicode (emojis). Toll-Free Numbers may not support a Subject.
OPERATORIDOptionalCarrier ID for the Phone Number
FROM_MASKOptionalOnly carriers in certain countries allow Alphanumeric senders. Not supported in the USA.
FALLBACKSMSTEXTMandatory if subject is not passedText which gets sent when MMS is sent as SMS fallback. Limit text to 110 characters for best deliverability.
DISABLEFALLBACKSMSLINKOptionalSet to true/false to disable appending a link to the MMS Content at the end of the SMS fallback text.
SLIDE:$CONTENTOptionalSlide content node which contains the content URL. Acceptable slide content includes:
image
audio
video
vcard
ical
pdf
text
SLIDE:$CONTENT:URLOptionalPublic content URL where the content is accessible.
SLIDE:TEXTOptionalText that is delivered alongside the content if added in a slide of the MMS.
SLIDE:DURATIONOptionalThe duration (seconds) that the slide will remain on screen. Only applicable for feature phones.
MMSLINK_EXPIRATION_DATEOptionalExpiration 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_SMSOptionalSet 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_REFERENCEOptional; StringCustomer 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 NamePresenceDescription
STATUSAlways“Success” or “Failure”.
MMSIDSuccess response onlyThe ID (bigint) of a saved MMS.
TRACKINGIDSuccess response only Transaction ID for the request. Use it to match the postbacks received for this API request.
TOSuccess response onlyDestination phone number with country code.
ERRORCODEError response onlyError code associated with the error.
ERRORINFOError response onlyError 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

CodeDescription
E100Invalid request. Make a valid request via GET/POST/XML with all the required variables.
E104User Authentication Failed.
E105This account has no API rights.
E106You can call API every X seconds.
E107This account has no rights to use this action.
E108XML Parse error: $error.
E109API not activated.
E112IP was not whitelisted. API call rejected.
E113Set throughput exceeded for this API action. API call rejected.
E114Phone number is blacklisted. API call rejected.
E120Account has reached the API request limit.
E503Internal error.

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

CodeDescription
E110Invalid receiver number.
E111Invalid Sender.
E111Invalid Sender to $country-name.
E223More than one object is not allowed in the same slide.
E224MMS audio/video/image are not allowed with object in the same slide.
E225Too many Slides.
E226Audio and Video not allowed in same slide.
E227Video and Image not allowed in same slide.
E228Text more than X characters.
E229Content not allowed.
E230Bad X slide duration.
E241This content does not exist.
E311The ‘name’ is required.
E312No slides.
E313Slide X is empty.
E331Image in slide X is too big.
E332Audio in slide X is too big.
E333Video in slide X is too big.
E334Text in slide X is too long.
E335vCard in slide X is too big.
E336iCal in slide X is too big.
E337PDF in slide X is too big.
E341Image file in slide X is corrupted.
E351Could not copy Image in slide X.
E352Could not copy Audio in slide X.
E353Could not copy Video in slide X.
E355Could not copy vCard in slide X.
E356Could not copy iCal in slide X.
E357Could not copy PDF in slide X.
E617mmslink_expiration_date is invalid.
E618Carrier lookup failed. Please retry.
E619Carrier not provisioned.
E622The ‘fallbacksmstext’ is required.
E627Invalid serviceid / serviceid is required
E628Operator Not supported.
E629Unrecognized content type.
E650The ‘operator id’ is required.
E655FORCE_SEND_AS_SMS node accepts only true/false values.
E715Number is not subscribed in this campaign
E718The ‘campaignref’ is required
E721Invalid campaignref
Go to Top