(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 V2

Synopsis

This API sends a stored MMS template from your account using an mms-id to a single mobile number. The sender number must be one of the short codes, toll free numbers or 10 DLC provisioned to your account. The receiver number must be within the same country as the selected sender number. If you have more than one account you must use the API key from the account where the mms-id is saved. If “Enforce Campaign Check” is turned ON for the account, then this function will require the campaign reference ID of the messaging campaign that the recipient’s phone number is subscribed to to be passed inside the campaign reference node.

Content Transcoding

Every MMS template stored using the SaveMMS API and sent using the SendSavedMMS API will be transcoded for the destination handset. Additionally, any MMS which triggers an SMS Fallback containing a link to the MMS content hosted on a web page is optimized for the mobile web browser. We are sometimes able to obtain this handset type information from delivery receipts and store the record in a handset cache for use with transcoding. We have a database of attributes which we manually match to each handset so we can optimize certain content for MMS delivery if necessary.

Fallback SMS

There is a ‘fallback-sms-text’ node whose value is used as the SMS text in the case of MMS is delivered as SMS with an embedded link. If your account is allowed to send fallback SMS then this field becomes mandatory. Otherwise, it’s optional.

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 “fallback-sms-text” node. If the “disable-fallback-sms” node is set to boolean value true 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 the boolean value true to the “disable-fallback-sms-link” 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 the boolean value true to the “disable-fallback-sms” 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.

MMS Personalization

This API supports sending personalized MMS with Dynamic Data:

  • Dynamic Subject
  • Dynamic Text
  • Merge Tags
  • Embedded Dynamic Image Template
  • Dynamic Contact
  • Dynamic Calendar
  • Dynamic Map
  • Dynamic Image

Please refer to the rest of the documentation below for more details.

Dynamic Subject

This API supports dynamically changing the MMS Subject by setting up the optional “message-subject” node. Defining a custom subject in the “message-subject” node will override the subject string for the MMS template object.

Dynamic Text

This API supports dynamically changing the text of each slide by setting up the optional “custom-slides” node. The “custom-slides” node must include mandatory fields “custom-message-text” and “custom-slide”. Defining a “custom-slides” node will override the slide text string in a specific slide of the MMS Template object. Line breaks are supported in the custom slide texts of the MMS.

Merge Tags

This API supports sending MMS with Dynamic Data in the message text using merge tags. For this, you have to add merge tags in the message text in this format: {$variable|default}. You can send the dynamic data in the “merge-tag-data” node. Then our system will replace the tag with the dynamic data before delivery. If no dynamic data is present, we will replace the tag with the default value. You can also skip adding a default value (i.e. {$variable|}). The tag is case insensitive.

For example, let’s say your message text includes the following text with merge tag: Hi {$first-name|customer}. For personal text messages, clients can use dynamic merge text to say, “Hi John!” for a particular phone number that has the personal data ‘John’ as the first name. The dynamic data can be supplied to the “merge-tag-data” node by passing the merge tag variable as the key and the data as the value (i.e. “first-name”:”John”). And if there is no personal data supplied, the recipient will receive the text “Hi customer”.

Embedded Dynamic Image Template

This API supports sending MMS with embedded Dynamic Image Templates. For this, you have to create a Dynamic 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 dynamic data for this template in the “merge-tag-data” node. Some additional notes:

  • If the Image Template contains a barcode with a merge tag variable (i.e. {$barcodeid}) in the barcode value, then the personalized barcode data can be supplied to the “merge-tag-data” node by passing the merge tag variable as the key and the barcode data as the value (i.e. “barcodeid”:”1234″). If no data is supplied to the barcode, then the text areas will be empty/blank upon sending.
  • If the Personalized Image Template contains at least one text area with a merge tag variable (i.e. {$firstname}) in the text area value, then the personalized text area data can be supplied to the “merge-tag-data” node by passing the merge tag variable as the key and the text area data as the value (i.e. “firstname”:”Bob”). If no data is supplied to the text areas, then the text areas will be empty/blank upon sending.

Dynamic Contact

This API supports sending MMS with embedded Dynamic Contact. The custom Dynamic Contact data can be supplied in the API. Some additional notes:

  • A dynamic contact must have some data added in the request.
  • The first and last names of the contact are required in the contact. 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 is optional and can be empty.
  • Up to four phone numbers, four email addresses, four physical addresses, and four websites are supported in the contact. The request will pass and the message will be sent, ignoring the rest of the options passed in the contact, if the limit is exceeded.
  • Currently the labels “work” and “home” are supported for the phone number, email address, and physical address labels in the vCard. Additionally the labels “mobile”, “fax”, “pager”, “main”, and “other” are supported for the phone number labels only. 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.
  • Currently custom labels are supported for website labels in the vCard. If no label is added, then the default label “homepage” is used. There is a total limit of 100 characters per website label. Any characters > 100 will be truncated in the vCard.
  • The photo URL in the contact supports gif, jpg, and png image file types. If the photo validation fails, then the request will fail and no message will be sent.
  • The dynamic contact can be sent at a particular slide order in the MMS if the slide number for it is set. By default it will automatically be attached to the last slide of the MMS upon sending.
  • Multiple dynamic contacts can be added to one MMS. There is a total limit of 9 slides per MMS. Any slide > 9 will be skipped for processing and will be truncated in the final MMS sent to the device.

Dynamic Calendar

This API supports sending MMS with embedded Dynamic Calendar. The custom Dynamic Calendar data can be supplied in the API. Some additional notes:

  • A dynamic calendar must have some data added in the request.
  • All calendar information is mandatory except “all-day-event”. The request will fail and no message will be sent if any of the required information is missing.
  • The date and time added in the “event-start-datetime” and “event-end-datetime” are converted to UTC and used in the iCalendar file. 
  • If the datetime value contains the timezone offset or any indication of timezone, then the timezone part of the datetime string is ignored and the event-timezone value is considered. 
  • The event can be set for the entire day by setting the “all-day-event” to the boolean value true i.e. the event will start at 12:00am UTC of the event start date and will end at 11:59pm UTC of the event end date.
  • The dynamic calendar can be sent at a particular slide order in the MMS if the slide number for it is set. By default it will automatically be attached to the last slide of the MMS upon sending.
  • Multiple dynamic calendars can be added to one MMS. There is a total limit of 9 slides per MMS. Any slide > 9 will be skipped for processing and will be truncated in the final MMS sent to the device.

Dynamic Map

This API supports sending MMS with embedded Dynamic Map. The custom Dynamic Map data can be supplied in the API. Some additional notes:

  • A dynamic map must have some data added in the request.
  • The name of the location in the map is required. The request will fail and no message will be sent if the name is not included.
  • Either the physical address of the location or the latitude/longitude of the location is required. The request will fail and no message will be sent if neither are not included.
  • If both the “location-address” and the “location-latitude/location-longitude” values are passed, the “location-latitude/location-longitude” value will take precedence over the “location-address”.
  • The dynamic map can be sent at a particular slide order in the MMS if the slide number for it is set. By default it will automatically be attached to the last slide of the MMS upon sending.
  • Multiple dynamic map objects can be added to one MMS. There is a total limit of 9 slides per MMS. Any slide > 9 will be skipped for processing and will be truncated in the final MMS sent to the device.

Dynamic Image

This API supports sending MMS with embedded Dynamic Image. The custom Dynamic Image data can be supplied in the API. Some additional notes:

  • A dynamic image must have some data added in the request.
  • At least one of the following is required for an image: background image, barcode, and/or text area. The request will fail and no message will be sent if none are included.
  • The background image URL in the image supports jpg image file type. If the background image is not a jpg or if the image does not exist, then the request will fail and no message will be sent. Recommendations for background image are jpg image type, 640x1138px size, and 200 KB file size.
  • If a barcode is added in the image, then the barcode id is required. The request will fail and no message will be sent if a barcode is added without a barcode id. The barcode id will appear at the bottom center of the barcode by default and can be hidden by passing the boolean value true to “hide-text”. Both the barcode and the barcode id can be customized based on the details passed in the request. Barcode customizations include barcode type, x/y position, width/height, foreground/background color, border width, transparency, alignment, and rotation. Barcode id customizations include font style/size, and the color of the barcode id is based on the foreground color.
  • A dynamic image supports up to 8 text areas. Each text area requires text to be added. The request will fail and no message will be sent if a text area is added without text. Text area customizations include x/y position, font style/size/color, and width.
  • The dynamic image can be sent at a particular slide order in the MMS if the slide number for it is set. By default it will automatically be attached to the last slide of the MMS upon sending.
  • Multiple dynamic images can be added to one MMS. There is a total limit of 9 slides per MMS. Any slide > 9 will be skipped for processing and will be truncated in the final MMS sent to the device.

Request: JSON

curl -X POST \
     -H "x-api-key: API_KEY" \
     -H "content-type: application/json" -d '
      {
          "action": "sendsavedmms",
          "mms-id": "MMS_ID",
          "to": "RECEIVER_PHONE_NUMBER_WITH_COUNTRY_CODE",                    
          "from": "SENDER_NUMBER",
          "from-mask": "SENDER_MASK",
          "message-subject": "MMS_SUBJECT_TEXT",
          "fallback-sms-text": "FALLBACK_SMS_TEXT",
          "disable-fallback-sms": true/false,
          "disable-fallback-sms-link": true/false,
          "fallback-sms-link-expiration": "EXPIRATION_DATE_(UTC)",
          "mms-expiry-timestamp": "MMS_EXPIRY_TIMESTAMP_(UTC)",
          "force-send-as-sms": true/false,
          "client-reference": "CLIENT_REFERENCE",
          "campaign-ref": "CAMPAIGN_REFERENCE",
          "custom-slides": [
              {
                  "custom-message-text": "CUSTOM_MESSAGE_TEXT",
                  "custom-slide": "CUSTOM_SLIDE_NUMBER"
              },
              ...
          ],
          "merge-tag-data": {
              "VARIABLE_KEY_1": "VARIABLE_VALUE_1",
              "VARIABLE_KEY_2": "VARIABLE_VALUE_2",
              ...
              "VARIABLE_KEY_N": "VARIABLE_VALUE_N"
          },
          "dynamic-contact": [
              {
                  "slide-number": "SLIDE_NUMBER",
                  "name": {
                      "first-name": "FIRST_NAME",
                      "last-name": "LAST_NAME",
                      "suffix": "NAME_SUFFIX"
                  },
                  "organization": "ORGANIZATION_NAME",
                  "title": "ORGANIZATION_TITLE",
                  "photo-url": "PROFILE_PHOTO_URL",
                  "note": "CONTACT_NOTE",
                  "phone": [
                      {
                          "number": "PHONE_NUMBER",
                          "label": "PHONE_NUMBER_LABEL"
                      },
                      ...
                  ],
                  "email": [
                      {
                          "id": "EMAIL_ADDRESS",
                          "label": "EMAIL_ADDRESS_LABEL",
                      },
                      ...
                  ],
                  "physical-address": [
                      {
                          "address": "PHYSICAL_ADDRESS",
                          "label": "PHYSICAL_ADDRESS_LABEL"
                      },
                      ...
                  ],
                  "website": [
                      {
                          "url": "WEBSITE_URL",
                          "label": "WEBSITE_URL_LABEL"
                      },
                      ...
                  ]
              },
              ...
          ],
          "dynamic-calendar": [
              {
                  "slide-number": "SLIDE_NUMBER",
                  "event-title": "EVENT_TITLE",
                  "event-description": "EVENT_DESCRIPTION",
                  "event-location": "EVENT_LOCATION",
                  "event-start-datetime": "EVENT_START_DATE_AND_TIME",
                  "event-end-datetime": "EVENT_END_DATE_AND_TIME",
                  "event-timezone": "EVENT_TIMEZONE",
                  "all-day-event": true/false
              },
              ...
          ],
          "dynamic-map": [
              {
                  "slide-number": "SLIDE_NUMBER",
                  "location-name": "MAP_LOCATION_NAME",
                  "location-address": "MAP_LOCATION_ADDERSS",
                  "location-latitude": "MAP_LOCATION_LATITUDE",
                  "location-longitude": "MAP_LOCATION_LONGITUDE"
              },
              ...
          ],
          "dynamic-image": [
              {
                  "slide-number": "SLIDE_NUMBER",
                  "background-image-url": "BACKGROUND_IMAGE_URL",
                  "add-barcode": "YES/NO",
                  "barcode": {
                      "id": "BARCODE_TEXT",
                      "position-x": "X_COORDINATE_VALUE_IN_PIXELS",
                      "position-y": "Y_COORDINATE_VALUE_IN_PIXELS",
                      "width": "WIDTH_OF_BARCODE_IN_PIXELS",
                      "height": "HEIGHT_OF_BARCODE_IN_PIXELS",
                      "foreground-color": "FOREGROUND_COLOR_OF_BARCODE_IN_HEXADECIMAL_VALUE",
                      "background-color": "BACKGROUND_COLOR_OF_BARCODE_IN_HEXADECIMAL_VALUE",
                      "border-width": "WIDTH_OF_BARCODE_BORDER_IN_PIXELS",
                      "type": "BARCODE_TYPE",
                      "hide-text": true/false,
                      "transparent": true/false,
                      "font": "FONT_STYLE",
                      "font-size": "FONT_SIZE",
                      "alignment": "LEFT/CENTER/RIGHT",
                      "rotate": "0/90/180/270"
                  },
                  "add-text-area": "YES/NO",
                  "text-area": {
                      "text-area-1": {
                          "text": "TEXT_WITHIN_THE_TEXT_AREA_FIELD",
                          "position-x": "X_COORDINATE_VALUE_IN_PIXELS",
                          "position-y": "Y_COORDINATE_VALUE_IN_PIXELS",
                          "font": "FONT_STYLE",
                          "font-size": "FONT_SIZE",
                          "font-color": "FONT_COLOR_IN_HEXADECIMAL_VALUE",
                          "width": "WIDTH_OF_THE_TEXT_AREA_FIELD"
                      },
                      ...
                  }
              },
              ...
          ]
      }' \
  "API_ENDPOINT_URL"

Success Response: JSON

{
    "status": "Success",
    "mms-id": "MMS_ID_OF_MMS_TEMPLATE",
    "tracking-id": "TRACKING_ID_OF_REQUEST",
    "to": "RECEIVER_PHONE_NUMBER_WITH_COUNTRY_CODE",
    "from": "SENDER_NUMBER",
    "status-details": "MMS request accepted and queued for delivery."
}

Failure Response: JSON

{
    "status": "failure",
    "error-code": "ERROR_CODE",
    "error-info": "ERROR_INFO",
}

Request Parameters

Param NameOptional/Mandatory; DatatypeDescription
x-api-keyMandatory; AlphanumericAuthentication Key for your account to access API service. Unique Alphanumeric Key can be reset under your Account->API Settings. Case-sensitive.
actionMandatory; StringExplains the action for this API Request. Value is Case-Insensitive.
mms-idMandatory; NumericMMS Template ID.
toMandatory; StringDestination phone number with country code.
fromMandatory; NumericShortcode, or Toll Free or 10 DLC with country code.
from-maskOptional; AlphanumericOnly carriers in certain countries allow Alphanumeric senders. Not supported in the USA.
campaign-refOptional, Mandatory only if the “Enforce Campaign Check” is enabled on the account requiring a number to be actively subscribed; AlphanumericThe campaign reference for which the number is subscribed into.
message-subjectOptional; AlphanumericMMS Subject text. Limit subject to 40 characters for best deliverability. No unicode (emojis). Overrides the saved setting in the MMS template. Toll-Free Numbers may not support a Subject.
fallback-sms-textOptional, Mandatory if “disable-fallback-sms” node is set to “false”; AlphanumericText which gets sent when MMS is sent as SMS fallback. Limit the text between 20 and 110 characters for best deliverability. Overrides the saved setting in the MMS Template.
disable-fallback-smsOptional; BooleanSet to true/false to disable the SMS fallback. Overrides the saved setting in the MMS Template.
disable-fallback-sms-linkOptional; BooleanSet to true/false to disable appending a link to the MMS Content at the end of the SMS fallback text. Overrides the saved setting in the MMS Template.
fallback-sms-link-expirationOptional; Date TimeExpiration 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.
mms-expiry-timestampOptional; Date TimeAfter this date time, the MMS will stop delivery attempts if it has not been delivered. If the MMS is already delivered to the device, it will remain in the inbox. If not passed, the expiration is defaulted to 3 days from the date of this API request being made. The maximum expiration duration that can be passed is 3 days. Accepts only ISO8601 Date format.
force-send-as-smsOptional; BooleanSet the value to Boolean “true” to force sending the MMS as SMS. In this scenario, the disable-fallback-sms field value will be ignored. Additionally, if the operator-id 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.
custom-slidesOptionalCustom slides to be dynamically inserted into the MMS during sending.
custom-slides:custom-message-textOptional; AlphanumericExisting text in the slide of a message will be replaced with this text.
custom-slides:custom-slideOptional; NumericSlide number where this custom text or slide will be added on the MMSID.
merge-tag-dataOptionalDynamic merge tags and data are passed in this json node.
Example: Pass “fullname”:”John Appleseed” in the API to replace the dynamic merge tag “{$fullname|customer}” in the MMS text slide.
dynamic-imageOptionalA dynamic image parent node. Set to create a jpeg image used as a background with personalized text, and a transparent barcode image layered on top of it.
dynamic-image:slide-numberOptional; NumericThe slide at which the dynamic object will be inserted into the MMS.
dynamic-image:background-image-urlOptional; AlphanumericBackground image URL for the dynamic image.
dynamic-image:add-barcodeOptional; StringPass “yes” or “no” to add a barcode to the dynamic image.
dynamic-image:barcodeOptionalBarcode node which contains barcode details if “add-barcode=yes”.
dynamic-image:barcode:idMandatory; AlphanumericBarcode text.
dynamic-image:barcode:position-xOptional; IntegerInteger value expected which will be the starting position of the barcode in pixels along the X (horizontal) coordinate. Default: 0
dynamic-image:barcode:position-yOptional; IntegerInteger value expected which will be the starting position of the barcode in pixels along the Y (vertical) coordinate. Default: 0
dynamic-image:barcode:widthOptional; IntegerWidth of the barcode in pixels. Default: 300
dynamic-image:barcode:heightOptional; IntegerHeight of the barcode in pixels. Default: 300
dynamic-image:barcode:foreground-colorOptional; AlphanumericHexadecimal value to set as the color of the foreground of the barcode. Default: #000000
dynamic-image:barcode:background-colorOptional; AlphanumericHexadecimal value to set as the color of the background of the barcode. Default: #ffffff
dynamic-image:barcode:border-widthOptional; IntegerWidth of the barcode border in pixels. Default: 0
dynamic-image:barcode:typeOptional; StringThis is the type of barcode which should be created. Available types:

Aztec Code
Code 11
Code 128
Code 39
Data Matrix
EAN
Interleaved 2of5
PDF417
QR Code
UPC-A

Default: QR Code
dynamic-image:barcode:hide-textOptional; BooleanBoolean value passed to hide/show the barcode text. Default: false
dynamic-image:barcode:transparentOptional; BooleanBoolean value to enable/disable transparency. Default: false
dynamic-image:barcode:fontOptional; StringFont style to be used for barcode text. Available styles:

Arvo
Arial
ArialMT
OpenSans
LiberationSans
Ubuntu

Default: OpenSans
dynamic-image:barcode:font-sizeOptional; IntegerFont size to be used for barcode text. Default: 20
dynamic-image:barcode:alignmentOptional; StringHorizontal alignment options for barcode. Options are Left, Center and Right. Default: Left
dynamic-image:barcode:rotateOptional; IntegerRotation option in degrees. Available options are 0, 90, 180, 270. Default: 0
dynamic-image:add-text-areaOptional; StringPass “yes” or “no” to add text areas to the dynamic image.
dynamic-image:text-areaOptionalText area node which contains text area details if “add-text-area=yes”.
dynamic-image:text-area:text-area-{n}OptionalText area subnode. Max text areas supported: 8
dynamic-image:text-area:text-area-{n}:textMandatory; StringText to be displayed for the text area field.
dynamic-image:text-area:text-area-{n}:position-xOptional; IntegerInteger value expected which will be the starting position of the text area field in pixels along the X (horizontal) coordinate. Default: 50
dynamic-image:text-area:text-area-{n}:position-yOptional; IntegerInteger value expected which will be the starting position of the text area field in pixels along the Y (vertical) coordinate. Default: 400
dynamic-image:text-area:text-area-{n}:fontOptional; StringFont style to be used for the text area text. Available styles:

Arvo
Arial
ArialMT
OpenSans
LiberationSans
Ubuntu

Default: OpenSans
dynamic-image:text-area:text-area-{n}:font-sizeOptional; IntegerFont size to be used for the text area text. Default: 20
dynamic-image:text-area:text-area-{n}:font-colorOptional; AlphanumericHexadecimal color value for the text area font. Default: #000000
dynamic-image:text-area:text-area-{n}:widthOptional; IntegerWidth of the text area field in pixels. Default: 200
dynamic-contactOptionalA dynamic contact parent node. Set to add contact.
dynamic-contact:slide-numberOptional; NumericThe slide at which the dynamic object will be inserted into the MMS.
dynamic-contact:nameMandatoryName of the contact.
dynamic-contact:name:first-nameOptional, Mandatory if the last-name is blank; StringFirst name of the contact.
dynamic-contact:name:last-nameOptional, Mandatory if the first-name is blank; StringLast name of the contact.
dynamic-contact:name:suffixOptional; StringName suffix of the contact.
dynamic-contact:organizationOptional; StringOrganization or company name. Accepts any text. 
dynamic-contact:titleOptional; StringTitle for the person in the contact. Accepts any text.
dynamic-contact:photo-urlOptional; StringURL of the contact photo. Supports PNG, GIF and JPEG file types. 
dynamic-contact:noteOptional; StringNotes. Accepts any text.
dynamic-contact:phoneOptional; StringPhone(s) of the contact. Max phones supported: 4
dynamic-contact:phone:numberOptional; StringPhone number.
dynamic-contact:phone:labelOptional; StringLabel for the phone. Available labels:

Work
Home
Mobile
Fax
Pager
Main
Other
dynamic-contact:emailOptional; StringEmail(s) of the contact. Max emails supported: 4
dynamic-contact:email:idOptional; StringEmail address.
dynamic-contact:email:labelOptional; StringLabel for the email. Available labels:

Work
Home
dynamic-contact:physical-addressOptional; StringPhysical address(es) of the contact. Max physical addresses supported: 4
dynamic-contact:physical-address:addressOptional; StringPhysical address.
dynamic-contact:physical-address:labelOptional; StringLabel for the physical address. Available labels:

Work
Home
dynamic-contact:websiteOptional; StringWebsite URL(s) of the contact. Max website URLs supported: 4
dynamic-contact:website:urlOptional; StringWebsite URL.
dynamic-contact:website:labelOptional; StringCustom label for the website URL. Characters > 100 will be truncated.
dynamic-calendar:event-titleMandatory; StringTitle of the calendar event.
dynamic-calendar:event-descriptionMandatory; StringDescription of the event.
dynamic-calendar:event-locationMandatory; StringLocation of the event.
dynamic-calendar:event-start-datetimeMandatory; Date TimeEvent start date time. Accepts ISO8601 Date format.
dynamic-calendar:event-end-datetimeMandatory; Date TimeEvent end date time. Accepts ISO8601 Date format.
dynamic-calendar:event-timezoneMandatory; StringTime zone of the event. Accepts tz database time zone names.
dynamic-calendar:all-day-eventOptional; BooleanSet to true if the event is an all day event. Default: false
dynamic-mapOptionalA dynamic map parent node. Set to add a map.
dynamic-map:slide-numberOptional; NumericThe slide at which the dynamic object will be inserted into the MMS.
dynamic-map:location-nameMandatory; StringName of the location.
dynamic-map:location-addressOptional, Mandatory if no location latitude/longitude; AlphanumericAddress of the location.
dynamic-map:location-latitudeOptional, Mandatory if no location address; NumericLatitude of the location.
dynamic-map:location-longitudeOptional, Mandatory if no location address; NumericLongitude of the location.

Response Parameters

Param NamePresenceDescription
statusAlways“Success” or “failure”.
status-detailsSuccess response onlyMore details about the status.
mms-idSuccess response onlyMMS Template ID.
tracking-idSuccess 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.
error-codeError response onlyError code associated with the error.
error-infoError response onlyError message explaining the error code.

Request Examples

Example 1:
curl -X POST \
     -H "x-api-key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
     -H "content-type: application/json" -d '
      {
          "action": "sendsavedmms",
          "mms-id": "123456",
          "to": ”+10000000001",
          "from": "00000"
      }' \
  "API_ENDPOINT_URL"

Example 2:
curl -X POST \
     -H "x-api-key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
     -H "content-type: application/json" -d '
      {
          "action": "sendsavedmms",
          "mms-id": ”123456”,
          "to": "+10000000001",
          "from": "00000",
          "message-subject": "Deal just for you!",
          "fallback-sms-text": "We could not deliver your message. Click here to read it.",
          "disable-fallback-sms": false,
          "disable-fallback-sms-link": false,
          "fallback-sms-link-expiration": "2021-12-20T21:21:52+00:00",
          "mms-expiry-timestamp": "2021-12-20T21:21:52+00:00",
          "force-send-as-sms": false,
          "client-reference": "5ZY7Cx1Xy0vs",
          "custom-slides": [
              {
                  "custom-message-text": "Here is a special deal for you {$fullname|customer}",
                  "custom-slide": 1
              }
          ],
          "merge-tag-data": {
              "fullname": "John Appleseed",
              "age": 30
          }
      }' \
  "API_ENDPOINT_URL"

Example 3 with dynamic image:
curl -X POST \
     -H "x-api-key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
     -H "content-type: application/json" -d '
      {
          "action": "sendsavedmms",
          "mms-id": "123456",
          "to": "+10000000001",
          "from": "00000",
          "dynamic-image": [
              {
                  "background-image-url": "https://fake-content-url.com/background.png",
                  "add-barcode": "yes",
                  "barcode": {
                      "id": "QR Code",
                      "position-x": 0,
                      "position-y": 0,
                      "width": 11,
                      "height": 11,
                      "foreground-color": "#000000",
                      "background-color": "#ffffff",
                      "border-width": 0,
                      "type": "QR Code",
                      "hide-text": false,
                      "transparent": false,
                      "font": "OpenSans",
                      "font-size": 20,
                      "alignment": "Left",
                      "rotate": 0
                  },
                  "add-text-area": "yes",
                  "text-area": {
                      "text-area-1": {
                          "text": "Text to be used in the text area",
                          "position-x": 10,
                          "position-y": 10,
                          "font": "OpenSans",
                          "font-size": 20,
                          "font-color": "#000000",
                          "width": 100
                      }
                  }
              }
          ]
      }' \
  "API_ENDPOINT_URL"

Example 4 with dynamic contact:
curl -X POST \
     -H "x-api-key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
     -H "content-type: application/json" -d '
      {
          "action": "sendsavedmms",
          "mms-id": "123456",
          "to": "+10000000001",
          "from": "00000",
          "dynamic-contact": [
              {
                  "name": {
                      "first-name": "John",
                      "last-name": "Appleseed",
                      "suffix": "Jr."
                  },
                  "organization": "Dunder Mifflin",
                  "title": "Account Manager",
                  "photo-url": "https://dundermifflinco.com/johnappleseedjr.png",
                  "note": "Manage account campaigns.",
                  "phone": [
                      {
                          "number": "10000000000",
                          "label": "Work"
                      }
                  ],
                  "email": [
                      {
                          "id": "fake.email@email.com",
                          "label": "Work"
                      }
                  ],
                  "physical-address": [
                      {
                          "address": "Fake Address",
                          "label": "Work"
                      }
                  ],
                  "website": [
                      {
                          "url": "https://www.dundermifflinco.com/",
                          "label": "Dunder Mifflin"
                      }
                  ]
              }
          ]
      }' \
  "API_ENDPOINT_URL"

Example 5 with dynamic calendar:
curl -X POST \
     -H "x-api-key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
     -H "content-type: application/json" -d '
      {
          "action": "sendsavedmms",
          "mms-id": "123456",
          "to": "+10000000001",
          "from": "00000",
          "dynamic-calendar": [
              {
                  "event-title": "Dunder Mifflin Christmas Party",
                  "event-description": "Ugly sweaters encouraged! Also bring a gift for Yankee Swap!",
                  "event-location": "Fake Address",
                  "event-start-datetime": "2021-12-17T11:30:00Z",
                  "event-end-datetime": "2021-12-17T13:30:00Z",
                  "event-timezone": "America/New_York",
                  "all-day-event": false
              }
          ]
      }' \
  "API_ENDPOINT_URL"

Example 6 with dynamic map:
curl -X POST \
     -H "x-api-key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
     -H "content-type: application/json" -d '
      {
          "action": "sendsavedmms",
          "mms-id": "123456",
          "to": "+10000000001",
          "from": "00000",
          "dynamic-map": [
              {
                  "location-name": "Dunder Mifflin",
                  "location-address": "Fake Address",
                  "location-latitude": "42.3694407",
                  "location-longitude": "-71.2374387"
              }
          ]
      }' \
  "API_ENDPOINT_URL"

Response Example: Success

{
    "status": "Success",
    "mms-id": "123456",
    "tracking-id": "xxxxxxxxxxxx",
    "to": "+10000000001",
    "from": "00000",
    "status-details": "MMS request accepted and queued for delivery."
}

Response Example: Failure

{
    "status": "failure",
    "error-code": "E111",
    "error-info": "Invalid Sender."
}
Go to Top