> For the complete documentation index, see [llms.txt](https://developers.mobile-text-alerts.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.mobile-text-alerts.com/tutorials/message-sending/send-an-mms-message.md). # Send an MMS Message MMS stands for *Multimedia Messaging Service*. It is used for sending messages that include a media attachment. MMS messages have a 500 KB size limit, a 1550 character limit, and a higher credit cost per send than SMS.

MMS example

### Credit Costs * **1** credit cost per SMS message (160 character limit, no attachment) * **3** credit cost per MMS message (1550 character limit, plus 500KB image attachment) {% hint style="info" %} A message **with** an attachment will be sent as MMS by default (messages without an attachment will be [sent as SMS](/tutorials/message-sending/send-an-sms-message.md)). Messages **without** an attachment can be sent as MMS if `isMMS` is set to `true`. {% endhint %} {% hint style="info" %} Before sending a message, you can calculate the will cost with the [Send](/api-reference/send.md#post-send-cost) endpoint. The `messageCredits` field indicates the number of credits to be consumed. {% endhint %} ### When to use MMS over SMS Some situations where MMS is worth using instead of SMS: * Very long text content * Sales-oriented content, where an image can help drive the call-to-action * Audience is primarily within the US/Canada * A Mobile Text Alerts plan with rollover and/or excess credits * Target audience responds better to media in messages * To include a [contact card](#attach-a-contact-card) with the message ## Supported attachment types The following file types are supported to use as attachments for MMS:
Image file types ``` .jpeg .jpg .gif .png .bmp ```
Audio file types ``` .mp4 .mpeg .ogg .rn-realaudio .wav .3gpp .3gpp2 .ac3 .webm .amr-nb .amr ```
Video file types 
.mpeg
.mp4
.quicktime
.webm
.3gpp
.3gpp2
.3gpp-tt
.h261
.h263
.h264
Other file types ``` .vcard .csv .rtf .pdf ```
## Attachment hosting with `rehost` field You can choose to host the URL of an attachment for an MMS on your own servers, or it can be hosted by Mobile Text Alerts. When sending a request to the `/send` endpoint, if the `rehost` flag is set to `true`, the attachment will be rehosted by Mobile Text Alerts before sending. This can be useful if the recipient isn't receiving your attachment, or you don't want to host the attachment. ## How to send an MMS with the API MMS messages are sent via the API with a `POST` request to the `/send` endpoint, just like SMS. Include the `image` (or `images`) field with the string of the URL of the attachment to send. All requests to this endpoint must contain both **recipient** and **content** information. **Required request fields:** * **Choose recipient(s):** (Must be one of the following) * `subscriberIds: number[]` - List of subscriber IDs of recipients. Messages can be sent to specific subscribers, with each subscriber assigned a unique `subscriberId`. * `subscribers: (number | string)[]` - List of recipient phone numbers or email addresses. A new subscriber will be created for new recipients that are not already subscribers on your account. * To ensure your messages are sent to the intended recipients this field must be formatted correctly based on how your subscribers are stored. E.164 formatted strings are recommended. See [Phone Number Format Guide](/tutorials/phone-number-format-guide.md) to learn more. * `allSubscribers: boolean` - Flag to indicate send message to all subscribers if `true`. When `allSubscribers` is set to `true`, no other recipient fields should be specified. Default value is `false`. * `groups: number[]` - List of group IDs of recipients. Messages can be sent to specific groups, with each group assigned a unique `groupId`. * `threadId: number` - Messages can be sent in reply to a thread, with each thread assigned a unique `threadId`. * **Content:** (Must include at least one of the following) * `message: string` - The content of the message being sent. * `image: string` - The URL of an [attachment](#supported-attachment-types) for a message. This URL needs to be publicly accessible; this ensures Mobile Text Alerts can access it when sending. * `images:string[]` - Use this field when you want multiple attachments, this field is an array of public image attachment URLs. **Overrides `image` when present.** * `templateId: number` - Messages can be saved as pre-set message templates for reuse with saved controlled templates on your account assigned a `templateId`. Visit [Message Templates](/tutorials/message-sending/message-templates.md) tutorial to learn more. * `contactCard: boolean` - When `true`, the system generates a contact card and appends it as an attachment. See [#attach-a-contact-card](#attach-a-contact-card "mention") below to learn more. * `contactCardLogo: string` - A URL for the logo to embed in the generated contact card. Overrides your account's pre-configured contact card logo. (Only used when `contactCard` is `true`.) * **Other fields:** * `rehost: boolean` - If the `rehost` flag is included and is set to `true`, the attachment will be [rehosted by Mobile Text Alerts](#attachment-hosting-with-rehost-field) before being sent to the recipients. ### How to send an MMS with the API {% stepper %} {% step %} ### Indicate the recipient(s) You can send a message to a phone number as a test. Set the `subscribers` field to the recipient phone number. ```json "subscribers": [1112223333] ``` {% endstep %} {% step %} ### Create the message content and attachment The text content of the message should be assigned to the `message` field and the URL of the attachment to the `image` field. ```json "message": "Use promo code TESTMESSAGE for 5% off when you sign up. STOP to end" "image": "https://imgur.com/gallery/example" ``` {% endstep %} {% step %} ### Form API request Create the API request to the `/send` endpoint. Remember to include [Authorization](https://mobile-text-alerts.gitbook.io/developer-center#authentication) header. ```bash curl --location 'https://api.mobile-text-alerts.com/v3/send' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{"subscribers": [1112223333], "message": "Use promo code TESTMESSAGE for 5% off when you sign up. STOP to end", "image": "https://imgur.com/gallery/example" }' ``` {% endstep %} {% step %} ### Receive response The API will return a message about the status of your request. ```json { "data": { "messageId": "uuid", "totalSent": 1, "totalFailedInternationalRecipients": 0 }, "message": "Message Sent to 1 Recipient." } ``` {% endstep %} {% endstepper %}
Send Message endpoint POST /send
## Attach a Contact Card You can send messages with a contact card attachment to the message. Messages with attachments always send as an MMS message type and costs 3 credits per recipient (regardless of the number of attachments). ### Overview To include a contact card in a message, set the optional field `contactCard: true` in [/send](/api-reference/send.md#post-send) message request This will generate a contact card from your account's pre-configured settings and append it as an attachment. > **Note:** If you'd prefer to use your own contact card image, you can pass it directly via `image` or `images` instead — no other special fields are needed. ### Request fields for attachments The following are optional fields that can be included in the [/send](/api-reference/send.md#post-send) request to include attachments for your MMS messages:
FieldTypeDescription
imagestringA single image attachment public URL. Ignored if images is also provided.
imagesstring[]An array of image attachment public URLs. Overrides image when present.
contactCardbooleanWhen true, the system generates a contact card and appends it as an attachment.
contactCardLogostringA URL for the logo to embed in the generated contact card. Overrides your account's pre-configured contact card logo. Only used when contactCard is true.
### How to send the contact card attachment In your send message request set `contactCard: true` to attach a generated Contact Card. To use a specific logo on the card, provide `contactCardLogo` — this overrides the logo set in your account's pre-configured contact card settings. **Example:** ```json { "message": "Save our contact info!", "subscribers": ["3175551234"], "contactCard": true, "contactCardLogo": "https://example.com/logo.png" } ``` You can also attach other images alongside the contact card, using the `images` field. The contact card is always appended **after** the image attachments. **Example:** In the below example, the recipient receives three attachments: two offer images followed by a contact card. ```json { "message": "Here's our info and latest offers.", "subscribers": ["3175551234"], "images": [ "https://example.com/offer-1.jpg", "https://example.com/offer-2.jpg" ], "contactCard": true, "contactCardLogo": "https://example.com/logo.png" } ``` ## Learn More [Mobile Text Alerts - MMS Messaging](https://mobile-text-alerts.com/articles/mms-services) [SMS and MMS: What They Are and When to Use Them](https://mobile-text-alerts.com/articles/sms-and-mms) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://developers.mobile-text-alerts.com/tutorials/message-sending/send-an-mms-message.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.