--- updatedAt: 2025-10-20T18:26:43.000Z agentTools: projectIndex: https://marketing.developer.dotdigital.com/llms.txt --- # MMS > 🚧 You need a MMS-enabled number before you can use MMS > > You must have an MMS-enabled phone number to be able to send MMS from your account. Contact your Customer Success representative to arrange one. Send MMS messages to recipients in supported countries with text and up to 10 images. ## Channel Identifier In the API, this channel can be referenced using: **mms** This identifier can be used in the **rules** array, and **customBody** sections. ## Supported countries The MMS channel can deliver messages to phone numbers registered in the following countries only: * Canada * USA ## Sending an MMS To send an MMS through the API you must: * ensure that your channel rules include the **mms** channel. * specify either a **phoneNumber** in international format or a **profileId** with a phone number in the **to** section of your request, and provide a **body** message to send the MMS to. This would need to be number registered in one of the supported countries for the MMS channel. * define a `text/plain` message part with the text element of your MMS. * define 1-10 image parts to be delivered with the text message. ```json Sending an MMS { "to": { "phoneNumber": "17123123123" }, "channelOptions": { "mms": { "from": "15166668399" } }, "rules": [ "mms" ], "messageParts": [ { "name": "Body text", "type": "text/plain", "data": "Check out our latest laptop deals!" }, { "name": "Laptop", "type": "image/png", "url": "http://cdn.dnky.co/3rdparty/comapi/images/laptop.png" } ] } ``` ## Sending a vCard vCard's can be sent via MMS to distribute contact cards. To send a vCard you will need to create a compliant vCard `.vcf` file and ensure it is hosted on a publicly accessible secure (HTTPS) url. ### Recommended .vcf file structure You need to create a text file and save it with the `.vcf` extension.\ To be a valid VCF file it needs to contain the following properties: ``` BEGIN:VCARD VERSION:3.0 ... END:VCARD ``` Example fully formed VCF file: ``` BEGIN:VCARD VERSION:3.0 FN:{company-name} ORG:{company-name} PHOTO;TYPE=JPEG;ENCODING=BASE64:{base64-encoded-logo} TEL;TYPE=WORK,VOICE:{phone-number} EMAIL:{email-address} URL:{url} ADR;TYPE=WORK:{address};;;;;;; END:VCARD ``` Where the following variables are present, data should be adherant to the [VCF 3.0 specifications](https://datatracker.ietf.org/doc/html/rfc2426) | Variable | Description | | :--------------------- | :---------------------------------------------------------------------------------------------- | | \{company-name} | Name of the company | | \{base64-encoded-logo} | A JPEG or PNG logo which has been encoded with base64 and is no larger than 750KB and 800x800px | | \{phone-number} | Company phone number in E.164 format | | \{email-address} | Company email address | | \{url} | Company web site | To send simply include the vCard as a message part of type `text/vcard` in your send request as demonstrated below: ```json Sending a vCard { "to": { "phoneNumber": "17123123123" }, "channelOptions": { "mms": { "from": "15166668399" } }, "rules": [ "mms" ], "messageParts": [ { "type": "text/plain", "data": "Hello 👋 this is a contact card MMS" }, { "name": "Dotdigital", "type": "image/png", "url": "https://upload.wikimedia.org/wikipedia/en/c/c4/Dotdigital_logo_2019.png" }, { "name": "Dotdigital.vcf", "type": "text/vcard", "url": "{URL to hosted .vcf file}" } ] } ```
## MMS Message Limits When sending MMS messages you must stay within the following constraints: * The maximum length of text part of the MMS is 1600 characters. * Only a single `text/plain` part can be included. * A minimum of one and a maximum of ten image parts can be included. * The maximum size of each image sent through MMS cannot exceed 750,000 bytes or 732KB. * You can only send to phone numbers registered in [supported countries](#supported-countries). ## Channel Options The following additional channel options can be used to control the MMS channel's most common options. To use the channel options, create an object with your options in the requests **channelOptions** section in the **mms** property: | Property | Type | Description | | :-------------------- | :----------------------------------- | :---------------------------------------------------------------------------------------------------- | | **from** | string | The MMS enabled phone number you are sending from. | | **allowUnicode** | boolean | This toggles whether having Unicode characters in the text part of the MMS message is allowed or not. | | **unicodeConversion** | *Unicode conversion settings object* | The settings for controlling automatic Unicode conversion. | **Unicode conversion settings object** | Property | Type | Description | | :---------------------- | :--------------------------- | :---------------------------------------------------------------------------------------------------------------- | | **convertUnicodeToGsm** | boolean | This toggles whether we try to convert Unicode characters to their closest match in the GSM character set or not. | | **customReplacements** | array (*Replacement object*) | A list of specific Unicode character mappings to apply to the Unicode conversion overriding the default mappings. | **Replacement object** | Property | Type | Description | | :------- | :----- | :---------------------------------------- | | **from** | string | The single Unicode character to map from. | | **to** | string | The GSM character to map to. | ```json Channel options for SMS { "body": "Sending MMS with the One API is easy!", "to": { "phoneNumber": "447123123123" }, "channelOptions": { "mms": { "from": "15166668399", "allowUnicode": true } }, "rules": [ "mms" ] } ``` ```json Unicode conversion { "body": "Dzień dobry, w czym mogę pomóc?", "to": { "phoneNumber": "447123123123" }, "channelOptions": { "mms": { "from": "Comapi", "allowUnicode": false, "unicodeConversion": { "convertUnicodeToGsm": true } } }, "rules": [ "mms" ] } ``` ```json Unicode conversion (Custom replacements) { "body": "Dzień dobry, w czym mogę pomóc?", "to": { "phoneNumber": "447990766636" }, "channelOptions": { "mms": { "from": "Comapi", "allowUnicode": false, "unicodeConversion": { "convertUnicodeToGsm": true, "customReplacements": [ { "from": "ó", "to": "o" }, { "from": "ń", "to": "n" } ] } } }, "rules": [ "mms" ] } ``` ### How to remove Unicode characters automatically We offer an optional feature for the MMS channel to convert Unicode characters to GSM based characters. This feature tries to map Unicode characters to a visually similar character in the GSM alphabet, for example, the character **ą** would be mapped to **a**, or **ś** to **s**. To enable this feature, specify a **unicodeConversion** object and ensure the **convertUnicodeToGsm** is set to *true*, and specify custom replacement character mappings if required. With the option enabled the following message is converted from *"Dzień dobry, w czym mogę pomóc?"* to *"Dzien dobry, w czym moge pomoc?"* removing all the Unicode characters automatically. > ❗️ Replacements not guaranteed > > The library tries to convert most common Unicode characters used in Latin based character sets to a GSM equivalent, but we cannot guarantee it can detect and replace them all. You may however add your own character mappings if there are specific mappings you want to address by specifying an array of mappings in the **customReplacements** array under the **unicodeConversion** node. A custom set of mappings **replaces the default set**. ## Receipts and inbounds ## [Inbound MMS](https://marketing.developer.dotdigital.com/reference/webhooks) We don't support **receiving** MMS; usually if a customer replies to an MMS, it's text based and therefore sent as an SMS. ## [Receipts](https://marketing.developer.dotdigital.com/reference/webhooks) If you need to to know the status of messages you've sent using one of our APIs, you can request that delivery receipts are forwarded to a URL of your choosing using [the webhook system](https://marketing.developer.dotdigital.com/reference/webhooks). See the events in the [*Message Events* section](https://marketing.developer.dotdigital.com/reference/message-events) for more details on the receipt events you can receive. You can receive the following types of receipts: * **Sent** * **Delivered** * **Expired** * **Failed** # Sibling pages * [SMS](https://marketing.developer.dotdigital.com/reference/channel-sms.md) * [Push](https://marketing.developer.dotdigital.com/reference/channel-push.md) * [WhatsApp](https://marketing.developer.dotdigital.com/reference/channel-whatsapp.md) * [App Messaging](https://marketing.developer.dotdigital.com/reference/channel-app-messaging.md)