(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

Save MMS API

SaveMMS

Synopsis

This API creates an MMS template, transcodes the content, and stores it for later use. The MMS may contain slides embedded with text, video, audio, images, contact, calendar, and PDF. Once the MMS is saved, an mms-id is returned enabling it to be utilized in the future by other API functions such as the SendSavedMMS API. The slides are stored based on the order given in the API call. Please note that not all devices will honor the exact order directed in the MMS message.

If the MMS message is too large to be delivered or the carrier does not support MMS delivery, we will deliver the MMS as fallback SMS. The fallback SMS consists of two parts: the “fallback SMS text” and the “fallback SMS link”.

  • The fallback SMS text is the SMS text that will be sent instead of the MMS along with the Fallback SMS Link to view the MMS Content. You can dynamically change the fallback SMS text by setting up the “FALLBACKSMSTEXT” node. If the “DISABLEFALLBACKSMS” node is set to ‘yes’ then the fallback SMS text is not required.
  • 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 fallback SMS Text is sent. By default, we always send the fallback SMS link along with the fallback SMS text.
  • The fallback SMS can be completely disabled by passing ‘yes’ to the “DISABLEFALLBACKSMS” node. 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.

Special Considerations

  • If the Transcoding is ON for the account, then the API SHALL reformat the content when necessary so that it can be delivered to the end-users handset in the best possible way.
  • Video SHALL be reduced in quality to fit delivery limitations and if it still does not fit it the entire MMS message may be delivered as SMS Fallback, if configured.
  • 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. Unicode characters may not be supported in the Subject. Unicode characters that are not supported will be stripped out. 
  • 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 or audio SHALL support text.
  • Slides with object type (i.e. contact, calendar, PDF) SHALL NOT support other media types (i.e. audio, video, image).
  • Slides with object type (i.e. contact, calendar, PDF) SHALL support text. 
  • 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. In the case when handset is unknown, then by default contact is delivered as binary attachment and calendar/PDF are delivered as downloadable web links in the MMS.
  • Slides with text SHALL support up to 5000 characters in any slide however some devices will not render all 5000 characters. 
  • Slides with text SHALL support characters that can be represented in Unicode including emoji or emoticon. 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 absolute path to the files including http or https. 
  • When retrieving each file from the URLs the content-type header MUST be set to the correct MIME type for the file.
  • If the Transcoding is ON for the account, MMS containing audio/video can be used only when the audio/video encoding is completed.
  • The status of encoding after it has been completed will be sent to your postback URL.
  • Supported media extensions and MIME types:
    • Text: text/plain
    • Image:
      • .jpg = image/jpg, image/jpeg
      • .png = image/png
      • .gif = image/gif
      • .webp = image/webp
    • Audio:
      • .mp3 = audio/mp3, audio/mpeg
      • .wav = audio/x-wave, audio/x-wav
      • .amr = audio/amr
    • Video:
      • .mp4 = video/mp4
      • .mpg, .mpeg = video/mpeg
      • .avi = video/x-msvideo
      • .wmv = video/x-ms-wmv
      • .mov = video/quicktime
      • .3gp = video/3gpp
    • Contact:
      • .vcf, .vcard = text/vcard, text/v-card, text/x-vcard
    • Calendar:
      • .ics, .ical, .ifb, .icalendar = text/calendar
    • Pdf:
      • .pdf = application/pdf, application/x-pdf
  • 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 says. 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.
  • The following content is never transcoded: contact, calendar, PDF.
  • There is a maximum source file size for each supported source file submitted. You can find out what the current maximum is by visiting your API settings.

Request: XML

<REQUEST>
    <ACTION>saveMMS</ACTION>
    <API_KEY>apiKey</API_KEY>
    <SUBJECT>Subject</SUBJECT>
    <NAME>Name to save it as</NAME>
    <FALLBACKSMSTEXT>Fallback Text if this MMS is sent as SMS</FALLBACKSMSTEXT>
    <DISABLEFALLBACKSMS>'yes' to disable fallback SMS</DISABLEFALLBACKSMS>
    <DISABLEFALLBACKSMSLINK>'yes' to disable fallback SMS link</DISABLEFALLBACKSMSLINK>
    <SLIDE>
        <IMAGE>
            <URL>URL</URL> 
        </IMAGE>
        <TEXT>Plain Text</TEXT>
    </SLIDE>
    <SLIDE>
        <AUDIO>
            <URL>*URL</URL>
        </AUDIO>
        <TEXT>Plain Text</TEXT>
    </SLIDE>
    <SLIDE>
        <VIDEO>
            <URL>*URL</URL>
        </VIDEO>
        <TEXT>Plain Text</TEXT>
    </SLIDE>
    <SLIDE>
        <VCARD>
            <URL>URL</URL>
        </VCARD>
        <TEXT>Plain Text</TEXT>
    </SLIDE>
    <SLIDE>
        <ICAL>
            <URL>URL</URL>
        </ICAL>
        <TEXT>Plain Text</TEXT>
    </SLIDE>
    <SLIDE>
        <PDF>
            <URL>URL</URL>
        </PDF>
        <TEXT>Plain Text</TEXT>
    </SLIDE>
    <SLIDE>
        <PERSONALIZED-IMAGE>
            <TEMPLATE-ID>Personalized image template id</TEMPLATE-ID>
        </PERSONALIZED-IMAGE>
        <TEXT>Plain Text</TEXT>
    </SLIDE>
    <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

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.
SUBJECTOptionalMMS Subject text. Limit subject to 40 characters for best deliverability. No unicode (emojis). Toll-Free Numbers may not support a Subject.
NAMEMandatoryMMS template name for internal reference only.
FALLBACKSMSTEXTMandatory if subject is not passedText which gets sent when MMS is sent as SMS fallback. Limit text to 110 characters for best deliverability.
DISABLEFALLBACKSMSOptionalSet to ‘yes’/’no’ to disable the SMS fallback.
DISABLEFALLBACKSMSLINKOptionalSet to ‘yes’/’no’ to disable appending a link to the MMS Content at the end of the SMS fallback text.
SLIDEMandatoryThis represents a single slide within the MMS sequence that could include IMAGE/URL/TEXT/PIC etc. (There are special rules for slides within the ‘saveMMS’ special consideration section).
SLIDE:$CONTENT Optional Slide content node which contains the content URL. Acceptable slide content includes:
image
audio
video
vcard
ical
pdf
text
personalized-image:template-id
SLIDE:$CONTENT:URL Optional Public content URL where the content is accessible.
SLIDE:TEXTOptionalText that is delivered alongside the content if added in a slide of the MMS. Line breaks are supported in the slide texts of the MMS.
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.
ERRORCODEError response onlyError code associated with the error.
ERRORINFOError response onlyError message explaining the error code.

Request Example: XML

<REQUEST>
    <ACTION>saveMMS</ACTION>
    <API_KEY>xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/API_KEY>
    <SUBJECT>The subject</SUBJECT>
    <NAME>The name</NAME>
    <FALLBACKSMSTEXT>Fallback Text if this MMS is sent as SMS</FALLBACKSMSTEXT>
    <SLIDE>
        <IMAGE><URL>https://fake-content-url.com/image.png</URL></IMAGE>
        <AUDIO><URL>https://fake-content-url.com/audio.mp3</URL></AUDIO>
        <TEXT>Here is some text\rHere is some more text</TEXT>
    </SLIDE>
    <SLIDE>
        <TEXT>This is my contact</TEXT>
        <VCARD><URL>https://fake-content-url.com/vcard.vcf</URL></VCARD>
    </SLIDE>
    <CLIENT_REFERENCE>5ZY7Cx1Xy0vs</CLIENT_REFERENCE>
</REQUEST>

Response Example: Success

<RESPONSE>
    <STATUS>Success</STATUS>
    <MMSID>35674</MMSID>
</RESPONSE>

Response Example: Failure

<RESPONSE>
    <STATUS>Failure</STATUS>
    <ERRORCODE>E225</ERRORCODE>
    <ERRORINFO>Too many Slides.</ERRORINFO>
</RESPONSE>

Postback Notification

When an MMS is saved and transcoded successfully, the system will generate a postback notification and unlock the MMS template for sending messages. If an MMS contains audio/video, the postback will be sent when the encoding of the MMS audio/video is finished, otherwise, the postback notification will be sent instantly after the image and other content is transcoded in real-time and stored. If you attempt to send an MMS-ID which has not finished encoding, an API error E626 will be returned.

Please see Delivery Report Postback – saveMMS Encoding Status for more detailed information concerning this postback notification.

Merge Tags

You can save an MMS Template with merge tags and those tags will be replaced during delivery of the MMS as long as you pass the variables in the SendSavedMMS request.

For example, here is a saveMMS request with merge tags in the TEXT node:

<REQUEST>
    <ACTION>saveMMS</ACTION>
    <API_KEY>xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx</API_KEY>
    <SUBJECT>Text with the dynamic variables</SUBJECT>
    <NAME>MMS with DynVars</NAME>
    <SLIDE>
        <IMAGE>
            <URL>https://fake-content-url.com/image.png</URL>
        </IMAGE>
        <TEXT>
            Hello {$firstname|customer}, here is a free coupon to celebrate your birthday {$birthday|today}!
        </TEXT>
    </SLIDE>
</REQUEST>

Then in the sendSavedMMS request, the variables are passed inside the DATA node:

<REQUEST>
    <ACTION>sendsavedMMS</ACTION>
    <API_KEY>xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx</API_KEY>
    <MMSID>43615</MMSID>
    <FROM>00000</FROM>
    <TO>11111111111</TO>
    <CAMPAIGNREF>1807</CAMPAIGNREF>
    <DATA>
        <FIRSTNAME>Bill</FIRSTNAME>
        <BIRTHDAY>1/13/1991</BIRTHDAY>
    </DATA>
</REQUEST>

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 right 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.
CodeDescription
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.
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.
E622The ‘fallbacksmstext’ is required.
E626This content is unavailable at the moment. Encoding is in progress. Please try again later.
E652Incorrect disablefallbacksms value. It is optional, but accepts only ‘yes’, ‘no’ or ‘’ if set.
E1130The personalized image template id in slide X is invalid
E1131Only one personalized image template is allowed per MMS
Go to Top