Table of Contents
Synopsis
This API sends an MMS to a single mobile number without creating an MMS Template. The MMS may contain slides embedded with video, audio, images, and/or text. The slides are created and sent in the order given in the API call. Not all messaging clients will render the order properly when received.
Unlike the SaveMMS API which will save and transcode content, the sendMMS API will only optimize image content and will not transcode any other content such as audio or video. Therefore, we strongly suggest that you use the saveMMS API call when sending video content unless you are able to transcode the video of your SendMMS message in advance.
If the sendMMS API is used to send the same content to multiple users, the content will be retrieved from your server for each request. Please ensure that the server storing your content is able to serve your files at the same speed as you make API requests.
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 is valid and viewable on the mobile browser. By default, it is set to 1 year if no value is passed. The maximum expiration duration cannot be more than 1 year.
- The MMS expiry timestamp defines how long the MMS using this MMSID is valid. By default, it is set to 3 days if no value is passed. The maximum expiration duration cannot be more than 3 days.
- Line breaks are supported in the 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 to be passed inside the “campaign-ref” node.
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 the image and other contents are 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.
Content Transcoding
Every 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. 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 that we manually match to every new handset in the cache so we can adapt the content during MMS delivery.
Dynamic Contact
This API also 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 also 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 also 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 also 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 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, then the API SHALL reformat the content when necessary so that it can be delivered to the end-users handset in the best possible way.
- Delivery success takes precedence over audio and video content quality and occasionally the picture quality will be reduced to fit handset message size requirements.
- Video SHALL be reduced in quality to fit delivery limitations and if it still does not fit it will be delivered as a Fallback SMS.
- Each request MUST contain at least one slide which MAY contain text and MAY contain an image, video, audio or other supported object.
- The API SHALL support up to 80 characters in the MMS subject.
- The API SHALL support up to 9 slides for each MMS submission.
- The API SHALL NOT support multiple files of the same MIME type in the same slide.
- Slides with images SHALL NOT support video but SHALL support audio.
- Slides with audio SHALL NOT support video. Slides with video SHALL only support text.
- Slides with text SHALL support up to 5000 characters in any slide.
- Slide with vCard/iCal/PDF objects SHALL NOT support media type audio/video/image and vice-versa.
- URLs provided MUST contain the full path to the content files.
- If the Transcoding is ON for the account, MMS containing audio/video can be used only when the audio/video encoding is completed.
- After submission, you will not be given a successful acknowledgment of audio/video encoding when a message is submitted.
- 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
- 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.
- There is a maximum source file size for each supported source file submitted. You can find out what the current maximum is by visiting your API settings.
- MMS messages are delivered in B64 encoding. To estimate the final size of Base64 encoded binary data, multiply the file size by 1.37 times the original data size + 814 bytes (for headers).
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)",
"campaign-ref": "CAMPAIGN_REFERENCE",
"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__ADDRESS",
"location-latitude": "MAP_LOCATION_LATITUDE",
"location-longitude": "MAP_LOCATION_LONGITUDE"
},
...
],
"dynamic-image": [
{
"slide-number": "SLIDE_NUBMER",
"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_BARCODE_IN_HEXADECIMAL_VALUE",
"background-color": "BACKGROUND_COLOR_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"
Request Parameters
| Param Name | Optional/Mandatory; Datatype | Description |
| x-api-key | Mandatory; Alphanumeric | Authentication Key for your account to access API service. Unique Alphanumeric Key can be reset under your Account->API Settings. Case-sensitive. |
| action | Mandatory; String | Explains the action for this API Request. Value is Case-Insensitive. |
| to | Mandatory; String | Destination phone number with country code. |
| from | Mandatory; Numeric | Shortcode, or Toll-Free or 10DLC with country code. |
| from-mask | Optional; Alphanumeric | Only carriers in certain countries allow Alphanumeric senders. Not supported in the USA. |
| campaign-ref | Optional, Mandatory only if the “Enforce Campaign Check” is enabled on the account requiring a number to be actively subscribed; Alphanumeric | The campaign reference for which the number is subscribed into. |
| message-subject | Optional; Alphanumeric | MMS Subject text. Limit subject to 40 characters for best deliverability. No unicode (emojis). Toll-Free Numbers may not support a Subject. |
| fallback-sms-text | Optional, Mandatory if “disable-fallback-sms” node is set to “false”; Alphanumeric | Text which gets sent when MMS is sent as SMS fallback. Limit text to 110 characters for best deliverability. |
| disable-fallback-sms | Optional; Boolean | Set to true/false to disable the SMS fallback. |
| disable-fallback-sms-link | Optional; Boolean | Set to true/false to disable appending a link to the MMS Content at the end of the SMS fallback text. |
| fallback-sms-link-expiration | Optional; Date Time | Expiration 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-timestamp | Optional; Date Time | After 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. |
| slide | Mandatory | Slide node containing all the contents of the slides. Max 9 slides. Each slide may contain one content URL and/or a message text. |
| slide:$content | Optional | Slide content node which contains the content URL. Acceptable slide content includes: image audio video contact calendar message-text |
| slide:$content:url | Mandatory; String | Public content URL where the content is accessible. |
| slide:message-text | Optional; Alphanumeric | Text that is delivered alongside the content if added in a slide of the MMS. |
| dynamic-image | Optional | A 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-number | Optional; Numeric | The slide at which the dynamic object will be inserted into the MMS. |
| dynamic-image:background-image-url | Optional; Alphanumeric | Background image URL for the dynamic image. |
| dynamic-image:add-barcode | Optional; String | Pass “yes” or “no” to add a barcode to the dynamic image. |
| dynamic-image:barcode | Optional | Barcode node which contains barcode details if “add-barcode=yes”. |
| dynamic-image:barcode:id | Mandatory; Alphanumeric | Barcode text. |
| dynamic-image:barcode:position-x | Optional; Integer | Integer value expected which will be the starting position of the barcode in pixels along the X (horizontal) coordinate. Default: 0 |
| dynamic-image:barcode:position-y | Optional; Integer | Integer value expected which will be the starting position of the barcode in pixels along the Y (vertical) coordinate. Default: 0 |
| dynamic-image:barcode:width | Optional; Integer | Width of the barcode in pixels. Default: 300 |
| dynamic-image:barcode:height | Optional; Integer | Height of the barcode in pixels. Default: 300 |
| dynamic-image:barcode:foreground-color | Optional; Alphanumeric | Hexadecimal value to set as the color of the foreground of the barcode. Default: #000000 |
| dynamic-image:barcode:background-color | Optional; Alphanumeric | Hexadecimal value to set as the color of the background of the barcode. Default: #ffffff |
| dynamic-image:barcode:border-width | Optional; Integer | Width of the barcode border in pixels. Default: 0 |
| dynamic-image:barcode:type | Optional; String | This 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-text | Optional; Boolean | Boolean value passed to hide/show the barcode text. Default: false |
| dynamic-image:barcode:transparent | Optional; Boolean | Boolean value to enable/disable transparency. Default: false |
| dynamic-image:barcode:font | Optional; String | Font style to be used for barcode text. Available styles: Arvo Arial ArialMT OpenSans LiberationSans Ubuntu Default: OpenSans |
| dynamic-image:barcode:font-size | Optional; Integer | Font size to be used for barcode text. Default: 20 |
| dynamic-image:barcode:alignment | Optional; String | Horizontal alignment options for barcode. Options are Left, Center and Right. Default: Left |
| dynamic-image:barcode:rotate | Optional; Integer | Rotation option in degrees. Available options are 0, 90, 180, 270. Default: 0 |
| dynamic-image:add-text-area | Optional; String | Pass “yes” or “no” to add text areas to the dynamic image. |
| dynamic-image:text-area | Optional | Text area node which contains text area details if “add-text-area=yes”. |
| dynamic-image:text-area:text-area-{n} | Optional | Text area subnode. Max text areas supported: 8 |
| dynamic-image:text-area:text-area-{n}:text | Mandatory; String | Text to be displayed for the text area field. |
| dynamic-image:text-area:text-area-{n}:position-x | Optional; Integer | Integer 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-y | Optional; Integer | Integer 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}:font | Optional; String | Font 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-size | Optional; Integer | Font size to be used for the text area text. Default: 20 |
| dynamic-image:text-area:text-area-{n}:font-color | Optional; Alphanumeric | Hexadecimal color value for the text area font. Default: #000000 |
| dynamic-image:text-area:text-area-{n}:width | Optional; Integer | Width of the text area field in pixels. Default: 200 |
| dynamic-contact | Optional | A dynamic contact parent node. Set to add contact. |
| dynamic-contact:slide-number | Optional; Numeric | The slide at which the dynamic object will be inserted into the MMS. |
| dynamic-contact:name | Mandatory | Name of the contact. |
| dynamic-contact:name:first-name | Optional, Mandatory if the last-name is blank; String | First name of the contact. |
| dynamic-contact:name:last-name | Optional, Mandatory if the first-name is blank; String | Last name of the contact. |
| dynamic-contact:name:suffix | Optional; String | Name suffix of the contact. |
| dynamic-contact:organization | Optional; String | Organization or company name. Accepts any text. |
| dynamic-contact:title | Optional; String | Title for the person in the contact. Accepts any text. |
| dynamic-contact:photo-url | Optional; String | URL of the contact photo. Supports PNG, GIF and JPEG file types. |
| dynamic-contact:note | Optional; String | Notes. Accepts any text. |
| dynamic-contact:phone | Optional; String | Phone(s) of the contact. Max phones supported: 4 |
| dynamic-contact:phone:number | Optional; String | Phone number. |
| dynamic-contact:phone:label | Optional; String | Label for the phone. Available labels: Work Home Mobile Fax Pager Main Other |
| dynamic-contact:email | Optional; String | Email(s) of the contact. Max emails supported: 4 |
| dynamic-contact:email:id | Optional; String | Email address. |
| dynamic-contact:email:label | Optional; String | Label for the email. Available labels: Work Home |
| dynamic-contact:physical-address | Optional; String | Physical address(es) of the contact. Max physical addresses supported: 4 |
| dynamic-contact:physical-address:address | Optional; String | Physical address. |
| dynamic-contact:physical-address:label | Optional; String | Label for the physical address. Available labels: Work Home |
| dynamic-contact:website | Optional; String | Website URL(s) of the contact. Max website URLs supported: 4 |
| dynamic-contact:website:url | Optional; String | Website URL. |
| dynamic-contact:website:label | Optional; String | Custom label for the website URL. Characters > 100 will be truncated. |
| dynamic-calendar:event-title | Mandatory; String | Title of the calendar event. |
| dynamic-calendar:event-description | Mandatory; String | Description of the event. |
| dynamic-calendar:event-location | Mandatory; String | Location of the event. |
| dynamic-calendar:event-start-datetime | Mandatory; Date Time | Event start date time. Accepts ISO8601 Date format. |
| dynamic-calendar:event-end-datetime | Mandatory; Date Time | Event end date time. Accepts ISO8601 Date format. |
| dynamic-calendar:event-timezone | Mandatory; String | Time zone of the event. Accepts tz database time zone names. |
| dynamic-calendar:all-day-event | Optional; Boolean | Set to true if the event is an all day event. Default: false |
| dynamic-map | Optional | A dynamic map parent node. Set to add a map. |
| dynamic-map:slide-number | Optional; Numeric | The slide at which the dynamic object will be inserted into the MMS. |
| dynamic-map:location-name | Mandatory; String | Name of the location. |
| dynamic-map:location-address | Optional, Mandatory if no location latitude/longitude; Alphanumeric | Address of the location. |
| dynamic-map:location-latitude | Optional, Mandatory if no location address; Numeric | Latitude of the location. |
| dynamic-map:location-longitude | Optional, Mandatory if no location address; Numeric | Longitude of the location. |
Response Parameters
| Param Name | Presence | Description |
| status | Always | “success” or “failure”. |
| status-details | Success response only | More details about the status. |
| tracking-id | Success response only | Transaction ID for the request. Use it to match the postbacks received for this API request. |
| to | Success response only | Destination phone number with country code. |
| error-code | Error response only | Error code associated with the error. |
| error-info | Error response only | Error 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",
"campaign-ref": "campaign2345",
"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",
"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": "11111111111",
"label": "Work"
}
],
"email": [
{
"id": "johnappleseedjr@dundermifflinco.com",
"label": "Work"
}
],
"physical-address": [
{
"address": "397 Moody Street #202. Waltham, MA 02453",
"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": "397 Moody Street #202. Waltham, MA 02453",
"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": "397 Moody Street, Waltham, MA, USA",
"location-latitude": "42.3694407",
"location-longitude": "-71.2374387"
}
]
}' \
"API_ENDPOINT_URL"Response Example: Success
{
"status": "success",
"to": "+10000000001",
"tracking-id": "xxxxxx-xxx-xxxxxxx",
"status-details": "MMS request accepted and queued for processing and delivery."
}Response Example: Failure
{
"status": "failure",
"error-code": "E111",
"error-info": "Invalid Sender."
}