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

Synopsis

This API sends an MMS to a single mobile number without creating an MMS Template. The MMS may contain slides embedded with text, video, audio, image, contact, calendar, and PDF. 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.

Content Transcoding

Every image in the MMS created using the SendMMS API will be transcoded for the destination handset based on your Account Settings. 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. All other content types will not be transcoded and sent as is to the destination handset.

Postback Notifications

When an MMS is saved and transcoded successfully, the system will generate a postback notification and unlock the MMS template for further use. 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 image and other content is transcoded in real-time and stored. In the postback you will receive the MMS-ID for the MMS created and the tracking-id that was originally received as the API Request Acknowledgement.

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.
  • The fallback SMS link expiration defines how long the MMS sent as SMS using this MMSID are valid and viewable on the mobile browser. By default, it is set to 1 year if no year is passed. The maximum expiration duration cannot be more than 1 year.

MMS Personalization

This API supports sending personalized MMS with Dynamic Data:

  • Dynamic Contact
  • Dynamic Calendar
  • Dynamic Map
  • Dynamic Image

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

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.

Special Considerations

  • If the Transcoding is ON for the account, this API shall reformat the content 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 objects such as contact, calendar or pdf.
  • The API supports 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 the 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 representable 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 audio/video 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, audio/wav, audio/wave
      • .amr = audio/amr
    • Video:
      • .mp4 = video/mp4
      • .mpg, .mpeg = video/mpeg, video/mpg
      • .avi = video/x-msvideo, video/avi
      • .wmv = video/x-ms-wmv, video/x-ms-asf
      • .mov = video/quicktime
      • .3gp = video/3gpp, video/3gp
    • 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 the current maximum limits from your Account Manager.

Request: JSON

curl -X POST \
     -H "x-api-key: API_KEY" \
     -H "content-type: application/json" -d '
      {
          "action": "sendmms",
          "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-link": true/false,
          "disable-fallback-sms": true/false,
          "fallback-sms-link-expiration": "FALLBACK_SMS_LINK_EXPIRATION_DATE_(UTC)",
          "mms-expiry-timestamp": "MMS_EXPIRY_TIMESTAMP_(UTC)",
          "force-send-as-sms": true/false,
          "client-reference" : "CLIENT_REFERENCE",
          "campaign-ref": "CAMPAIGN_REFERENCE",
          "cache-content": true/false,
          "slide": [
              {
                  "image": {
                      "url": "IMAGE_URL"
                  },
                  "message-text": "SLIDE_MESSAGE_TEXT"
              },
              {
                  "audio": {
                      "url": "AUDIO_URL"
                  },
                  "message-text": "SLIDE_MESSAGE_TEXT"
              },
              {
                  "video": {
                      "url": "VIDEO_URL"
                  },
                  "message-text": "SLIDE_MESSAGE_TEXT"
              },
              {
                  "contact": {
                      "url": "CONTACT_URL"
                  },
                  "message-text": "SLIDE_MESSAGE_TEXT"
              },
              {
                  "calendar": {
                      "url": "CALENDAR_URL"
                  },
                  "message-text": "SLIDE_MESSAGE_TEXT"
              },
              {
                  "pdf": {
                      "url": "PDF_URL"
                  },
                  "message-text": "SLIDE_MESSAGE_TEXT"
              }
          ],
          "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",
    "to": "RECEIVER_PHONE_NUMBER_WITH_COUNTRY_CODE",
    "tracking-id": "TRACKING_ID_OF_REQUEST",
    "status-details": "MMS request accepted and queued for processing and 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.
toMandatory; StringDestination phone number with country code.
fromMandatory; NumericShortcode, or Toll-Free or 10DLC with country code.
from-maskOptional; AlphanumericOnly carriers in certain countries allow Alphanumeric senders. Not supported in the USA.
message-subjectOptional; AlphanumericMMS Subject text. Limit subject to 40 characters for best deliverability. No unicode (emojis). 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 text to 110 characters for best deliverability.
disable-fallback-smsOptional; BooleanSet to true/false to disable the SMS fallback.
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.
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.
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.
cache-contentOptional; BooleanCaching is done for every sendmms request by default unless overridden by the API request by populating this field with false. If cache is found, the original content won’t be downloaded to validate.
slideMandatorySlide node containing all the contents of the slides. Max 9 slides. Each slide may contain one content URL and/or a message text.
slide:$contentOptionalSlide content node which contains the content URL. Acceptable slide content includes:

image
audio
video
contact
calendar
pdf
message-text
slide:$content:urlMandatory; StringPublic content URL where the content is accessible.
slide:message-textOptional; AlphanumericText 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.
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.
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.
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": "sendmms",
          "to": "+10000000001",
          "from": "00000",
          "message-subject": "Deal of the Day",
          "fallback-sms-text": "We could not deliver your message. Click here to read it. ",
          "slide": [
              {
                  "image": {
                      "url": "https://fake-content-url.com/image.png"
                  },
                  "message-text": "Hello member, here is the deal of the day! Click for more details https://www.dundermifflinco.com"
              }
          ]
      }' \
  "API_ENDPOINT_URL"

Example 2:
curl -X POST \ 
     -H "x-api-key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
     -H "content-type: application/json" -d '
      {
          "action": "sendmms",
          "to": "+10000000001",
          "from": "00000",
          "from-mask": "Dunder Mifflin",
          "message-subject": "Deal of the Day",
          "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",
          "campaign-ref": "campaign2345",
          "cache-content": true,
          "slide": [
              {
                  "image": {
                      "url": "https://fake-content-url.com/image.png"
                  },
                  "message-text": "Hello member, here is the deal of the day! "
              },
              {
                  "video": {
                      "url": "https://fake-content-url.com/video.mp4"
                  },
                  "Message-text": "Click for more details https://www.dundermifflinco.com"
              }
          ]
      }' \
  "API_ENDPOINT_URL"

Example 3 with dynamic image:
curl -X POST \ 
     -H "x-api-key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
     -H "content-type: application/json" -d '
      {
          "action": "sendmms",
          "to": "+10000000001",
          "from": "00000",
          "message-subject": "Deal of the Day",
          "fallback-sms-text": "We could not deliver your message. Click here to read it. ",
          "slide": [
              {
                  "image": {
                      "url": "https://fake-content-url.com/image.png"
                  },
                  "message-text": "Hello member, here is the deal of the day! Click for more details https://www.dundermifflinco.com"
              }
          ],
          "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": "sendmms",
          "to": "+10000000001",
          "from": "00000",
          "message-subject": "Deal of the Day",
          "fallback-sms-text": "We could not deliver your message. Click here to read it. ",
          "slide": [
              {
                  "image": {
                      "url": "https://fake-content-url.com/image.png"
                  },
                  "message-text": "Hello member, here is the deal of the day! Click for more details https://www.dundermiffflin.com"
              }
          ],
          "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": "sendmms",
          "to": "+10000000001",
          "from": "00000",
          "message-subject": "Deal of the Day",
          "fallback-sms-text": "We could not deliver your message. Click here to read it. ",
          "slide": [
              {
                  "image": {
                      "url": "https://fake-content-url.com/image.png"
                  },
                  "message-text": "Hello member, here is the deal of the day! Click for more details https://www.dundermifflinco.com"
              }
          ],
          "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": "sendmms",
          "to": "+10000000001",
          "from": "00000",
          "message-subject": "Deal of the Day",
          "fallback-sms-text": "We could not deliver your message. Click here to read it. ",
          "slide": [
              {
                  "image": {
                      "url": "https://fake-content-url.com/image.png"
                  },
                  "message-text": "Hello member, here is the deal of the day! Click for more details https://www.dundermifflinco.com"
              }
          ],
          "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",
    "to": "+10000000001",
    "tracking-id": "xxxxxxxxxxxx",
    "status-details": "MMS request accepted and queued for processing and delivery."
}

Response Example: Failure

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