(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 Saved MMS API

sendSavedMMS

Synopsis:

This API sends stored content from a specified account using an MMSID to a single mobile number.

FROM must be one of the shortcodes allowed for your account. In case the number is from a different country than the FROM shortcode is assigned to, the default shortcode for those countries will be used.

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

  • The fallback SMS text is the text used in place of the MMS subject. You can dynamically change the fallback SMS text by setting up the FALLBACKSMSTEXT node.
  • 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.
  • The fallback SMS can be completely disabled by passing ‘yes’ to the DISABLEFALLBACKSMS node. By default the fallback SMS is enabled. If the MMS will be sent as SMS while the fallback SMS is disabled, then the message will fail to send instead.

You can dynamically send custom text for each slide by setting up the CUSTOMTEXT node (CUSTOMTEXT must include mandatory fields: value and slide) and the MMS Subject by setting up the CUSTOMSUBJECT node. Line breaks are supported in the custom slide texts of the MMS.

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.

Content Transcoding:

Every binary MMS we deliver can be transcoded for the destination handset and every web page we deliver is transcoded for the browsing handset. 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 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 so we can adapt the content during MMS delivery.

Passbook Pass:

This API also supports sending MMS with a Passbook Pass.

Personalized Images:

This API also supports sending MMS with embedded Personalized Images. For this, you have to create a Personalized Image Template with merge tag vars in your account and add that to your MMS ID slide on the MMS Composer. You can send the personalized data for this template in the DATA node. Look at the request below to understand. Some additional notes:

  • If the Personalized Image Template contains a barcode and the merge tag var is set as “{$barcodeid}”, then the data for the barcode value can be supplied inside sub node under node.
  • If the Personalized Image Template contains at least one text area and the merge tag var is set to “{$firstname}”, then the data CAN be supplied inside sub node under node. If no data is supplied to the text areas, then the text areas will be empty/blank upon sending.
  • The background image URL in the personalized image supports gif, jpg, and png image file types. The image added in the personalized image will be converted into a jpg file upon sending. If the background image is not a gif, jpg, or png file or if the background image URL is invalid, then the request will fail and no message will be sent. The background image will be resized if the file size is greater than 200 KB or if the width is greater than 640 px. If the dynamic image template already contains a background image, then it will be replaced with the background image passed in the request instead.

Dynamic vCards:

This API also supports sending MMS with embedded Dynamic vCard. The custom Dynamic vCard data can be supplied in the API. Look at the request below to understand. Some additional notes:

  • Only one dynamic vCard per request is allowed. A dynamic vCard must have some data added in the request.
  • The first and last names of the contact are required in the vCard. The first and last names can only contain alphanumeric, space “ “ and period “.” characters. The request will fail and no message will be sent if the first and last names are not included or if they contain special characters. The rest of the contact information are optional and can be empty.
  • Up to four phone numbers, four email addresses, and four physical addresses are supported in the vCard. The request will fail and no message will be sent if the limit is exceeded.
  • Currently the labels ‘work’ and ‘home’ are supported for the phone numbers, email addresses, and physical addresses labels in the vCard. If any other labels are used, then the request will fail and no message will be sent. If no label is added, then the default label ‘work’ is used.
  • The photo URL in the dynamic vCard supports gif, jpg, and png image file types. The image added in the dynamic vCard will be converted into a jpg file upon sending since vCards currently support jpg file type only. If the photo is not a gif, jpg, or png file or if the photo does not exist, then the request will fail and no message will be sent.
  • The order of the request parameters for a dynamic vCard does not matter.
  • Nothing needs to be added in the MMS template in order to send a dynamic vCard.
  • The dynamic vCard generated will automatically be attached to the last slide of the MMS upon sending.

Request: XML

<REQUEST>
    <ACTION>sendSavedMMS</ACTION>
    <API_KEY>apiKey</API_KEY>
    <MMSID>MMSID</MMSID>
    <TO>Number</TO>
    <FROM>Shortcode</FROM>
    <FROM_MASK>*shortcodeMask</FROM_MASK>
    <OPERATORID>OPERATORID</OPERATORID>
    <CAMPAIGNREF>CampaignReferenceID</CAMPAIGNREF>
    <FALLBACKSMSTEXT>This text replaces the MMS subject when MMS is sent as SMS link</FALLBACKSMSTEXT>
    <DISABLEFALLBACKSMS>'yes' to disable fallback SMS</DISABLEFALLBACKSMS>
    <DISABLEFALLBACKSMSLINK>'yes' to disable fallback SMS link</DISABLEFALLBACKSMSLINK>
    <FORCE_SEND_AS_SMS>true/false to send MMS as SMS</FORCE_SEND_AS_SMS>
    <CLIENT_REFERENCE>Client Reference</CLIENT_REFERENCE>
    <CUSTOMTEXT>
        <VALUE>Custom Text for slide</VALUE>
        <SLIDE>Slide ID</SLIDE>
    </CUSTOMTEXT>
    <CUSTOMSUBJECT>MMS Custom Subject</CUSTOMSUBJECT>
    <DATA>
        <BARCODEID>Barcode ID</BARCODE>
        <FIRSTNAME>First Name</FIRSTNAME>
        <LASTNAME>Last Name</LASTNAME>
        <GENDER>Gender</GENDER>
        ...
    </DATA>
    <DYNAMICVCARD>
        <NAME>
            <FIRSTNAME>First Name</FIRSTNAME>
            <LASTNAME>Last Name</LASTNAME>
            <SUFFIX>Suffix Name</SUFFIX>
        </NAME>
        <ORGANIZATION>Organization Name</ORGANIZATION>
        <TITLE>Organization Title</TITLE>
        <PHOTOURL>Photo URL</PHOTOURL>
        <NOTE>Contact Note</NOTE>
        <PHONE>
            <NUMBER>Phone Number 1</NUMBER>
            <LABEL>Phone Label 1 (e.g. 'work' or 'home')</LABEL>
        </PHONE>
        <PHONE>
            <NUMBER>Phone Number 2</NUMBER>
            <LABEL>Phone Label 2 (e.g. 'work' or 'home')</LABEL>
        </PHONE>
        <EMAIL>
            <ID>Email Address</ID>
            <LABEL>Email Address Label (e.g. 'work' or 'home')</LABEL>
        </EMAIL>
        <PHYSICALADDRESS>
            <ADDRESS>Physical Address</ADDRESS>
            <LABEL>Physical Address Label (e.g. 'work' or 'home')</LABEL>
        </PHYSICALADDRESS>
    </DYNAMICVCARD>
</REQUEST>

*ShortcodeMask (Alphanumeric sender) is allowed only in few countries. Not supported in the United States.

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.
CAMPAIGNREFOptional, Mandatory only if the “Enforce Campaign Check” is enabled on the account requiring a number to be actively subscribedDepending 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.
MMSID Mandatory The ID (bigint) of a saved MMS.
CUSTOMSUBJECTOptionalThis is a custom subject that will overwrite the MMS Subject used in a sendSavedMMS function call. Toll-Free Numbers may not support a Subject.
CUSTOMTEXT Optional This is custom text that will overwrite a given slide text used in a sendSavedMMS function call.
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.
FROM_MASKOptionalOnly carriers in certain countries allow Alphanumeric senders. Not supported in the USA.
FALLBACKSMSTEXTOptionalText which gets sent when MMS is sent as SMS fallback. Limit text to 110 characters for best deliverability.
DISABLEFALLBACKSMSOptionalSet to true/false to disable the SMS fallback.
DISABLEFALLBACKSMSLINK Optional Set to true/false to disable appending a link to the MMS Content at the end of the SMS fallback text.
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.
TO Mandatory This is the message recipient’s phone number in an international format.
OPERATORIDOptionalCarrier ID for the Phone Number.
DATAOptionalUsed for merge tags or personalized images.
DYNAMICVCARDOptionalA dynamic contact parent node. Set to add contact.
DYNAMICVCARD:NAME:FIRSTNAMEOptional, Mandatory if the LASTNAME is blankFirst name of the contact.
DYNAMICVCARD:NAME:LASTNAME Optional, Mandatory if the FIRSTNAME is blankLast name of the contact.
DYNAMICVCARD:NAME:SUFFIXOptionalName suffix of the contact.
DYNAMICVCARD:ORGANIZATIONOptionalOrganization or company name. Accepts any text. 
DYNAMICVCARD:TITLEOptionalTitle for the person in the contact. Accepts any text.
DYNAMICVCARD:PHOTOURLOptionalURL of the contact photo. Supports PNG, GIF, and JPEG file types. 
DYNAMICVCARD:NOTEOptionalNotes. Accepts any text.
DYNAMICVCARD:PHONEOptionalPhone(s) of the contact. Max phones supported: 4
DYNAMICVCARD:PHONE:NUMBEROptionalPhone number.
DYNAMICVCARD:PHONE:PHONE:LABELOptionalLabel for the phone. Available labels:
Work
Home
Mobile
Fax
Pager
Main
Other
DYNAMICVCARD:EMAILOptional Email(s) of the contact. Max emails supported: 4
DYNAMICVCARD:EMAIL:IDOptionalEmail address.
DYNAMICVCARD:EMAIL:LABELOptional Label for the email. Available labels:
Work
Home
DYNAMICVCARD:PHYSICALADDRESSOptional Physical address(es) of the contact. Max physical addresses supported: 4
DYNAMICVCARD:PHYSICALADDRESS:ADDRESSOptionalPhysical address.
DYNAMICVCARD:PHYSICALADDRESS:LABELOptionalLabel for the physical address. Available labels:
Work
Home

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.
FROMSuccess response onlyShortcode, or Toll Free / 10DLC with country code.
ERRORCODEError response onlyError code associated with the error.
ERRORINFOError response onlyError message explaining the error code.

Request Example: XML

<REQUEST>
    <ACTION>sendSavedMMS</ACTION>
    <API_KEY>xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx</API_KEY>
    <TO>11111111111</TO>
    <FROM>00000</FROM>
    <CAMPAIGNREF>Campaign123</CAMPAIGNREF>
    <MMSID>35674</MMSID>
    <FALLBACKSMSTEXT>Visit this link for more details</FALLBACKSMSTEXT>
    <CLIENT_REFERENCE>5ZY7Cx1Xy0vs</CLIENT_REFERENCE>
    <CUSTOMTEXT>
        <VALUE>My Custom text in first slide\r\nAnd some more Custom text</VALUE>
        <SLIDE>1</SLIDE>
    </CUSTOMTEXT>
    <CUSTOMSUBJECT>My Custom Subject</CUSTOMSUBJECT>
    <DATA>
        <FIRST_NAME>John</FIRST_NAME>
        <LAST_NAME>Smith</LAST_NAME>
        <AGE>30</AGE>
        <PET>Dog</PET>
    </DATA>
    <DYNAMICVCARD>
        <NAME>
            <FIRSTNAME>John</FIRSTNAME>
            <LASTNAME>Smith</LASTNAME>
            <SUFFIX>Jr.</SUFFIX>
        </NAME>
        <ORGANIZATION>My Organzation Name</ORGANIZATION>
        <TITLE>Agent</TITLE>
        <PHOTOURL>https://yourwebsite.com/contacts/photo1.png</PHOTOURL>
        <NOTE>My agent</NOTE>
        <PHONE>
            <NUMBER>11111111111</NUMBER>
            <LABEL>work</LABEL>
        </PHONE>
        <PHONE>
            <NUMBER>11111111111</NUMBER>
            <LABEL>home</LABEL>
        </PHONE>
        <EMAIL>
            <ID>fake.email@email.com</ID>
            <LABEL>work</LABEL>
        </EMAIL>
        <PHYSICALADDRESS>
            <ADDRESS>Fake Address</ADDRESS>
            <LABEL>work</LABEL>
        </PHYSICALADDRESS>
    </DYNAMICVCARD>
</REQUEST>

Response Example: Success

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

Response Example: Failure

<RESPONSE>
    <STATUS>Failure</STATUS>
    <ERRORCODE>E713</ERRORCODE>
    <TO>11111111111</TO>
    <ERRORINFO>There is billing problem on your account</ERRORINFO>
</RESPONSE>

Postback Notification:

When the MMS delivery is processed successfully the system will generate a Postback notification. When an MMS delivery report is received the system will generate another Postback notification. Not all carriers provide MMS delivery receipts. For more details please visit the MMS MT Delivery Status section of the Delivery Report Postback documentation.

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.
CodeDescription
E110Invalid receiver number.
E111Invalid Sender.
E111Invalid Sender to $country-name.
E241This content does not exist.
E618Carrier lookup failed. Please retry.
E619Carrier not provisioned.
E620The ‘mmsid’ is required.
E621The ‘to’ is required.
E622The ‘fallbacksmstext’ is required.
E626Content unavailable. Encoding in progress, try again later.
E627Invalid serviceid / serviceid is required
E628Operator Not supported.
E629Unrecognized content type.
E650The ‘operator id’ is required.
E652Incorrect disablefallbacksms value. It is optional, but accepts only ‘yes’, ‘no’ or ‘’ if set.
E655FORCE_SEND_AS_SMS node accepts only true/false values.
E713There is billing problem on your account.
E715Number is not subscribed in this campaign
E718The ‘campaignref’ is required
E721Invalid campaignref
E803‘barcodevalue’ is required.
E1501There is no information added for the vCard.
E1502Only jpg, png, and gif images are allowed for the photo in the vCard.
E1506Phone number X added for the vCard is invalid.
E1507Phone number X added for the vCard is blank.
E1508Email id X added for the vCard is invalid.
E1511The photo url in the vCard does not exist.
E1515The first or last name for the vCard is required.
E1516Phone / Email / Physical address X label added for vCard is invalid.
Go to Top