# 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.

<div align="left"><figure><img src="https://879775583-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FM0P3gHFFZE4c6PMaPvHm%2Fuploads%2FaJxuDDvz1UijOhtJpT2b%2Fmms_holiday_example_c673426406.webp?alt=media&#x26;token=425ffc73-1e36-4bb1-96aa-279ecd35d67d" alt="" width="325"><figcaption><p>MMS example</p></figcaption></figure></div>

### 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](https://developers.mobile-text-alerts.com/tutorials/message-sending/send-an-sms-message)).  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 [#post-send-cost](https://developers.mobile-text-alerts.com/api-reference/send#post-send-cost "mention") endpoint. The `messageCredits` field indicates the number of credits to be consumed.
{% endhint %}

### When to use MMS over SMS <a href="#when-should-you-use-mmswhen-should-you-use-mms" id="when-should-you-use-mmswhen-should-you-use-mms"></a>

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

## Supported attachment types

The following file types are supported to use as attachments for MMS:

<details>

<summary>Image file types</summary>

```
.jpeg
.jpg
.gif
.png
.bmp
```

</details>

<details>

<summary>Audio file types</summary>

```
.mp4
.mpeg
.ogg
.rn-realaudio
.wav
.3gpp
.3gpp2
.ac3
.webm
.amr-nb
.amr
```

</details>

<details>

<summary>Video file types</summary>

<pre><code>.mpeg
<strong>.mp4
</strong>.quicktime
.webm
.3gpp
.3gpp2
.3gpp-tt
.h261
.h263
.h264
</code></pre>

</details>

<details>

<summary>Other file types</summary>

```
.vcard
.csv
.rtf
.pdf
```

</details>

## 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 <mark style="color:blue;">`/send`</mark> endpoint, just like SMS. Include the `image` field with 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](https://developers.mobile-text-alerts.com/tutorials/phone-number-format-guide "mention") 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. By default, messages with attachments (`image`) will be sent as an MMS. This URL needs to be publicly accessible; this ensures Mobile Text Alerts can access it when sending.
  * `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](https://developers.mobile-text-alerts.com/tutorials/message-sending/message-templates) tutorial to learn more.
* **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 89fa747a-e01b-5940-99c2-4e96fa996258' \
--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 %}

<details>

<summary>Send Message endpoint <mark style="color:orange;background-color:yellow;">POST</mark> <code>/send</code></summary>

</details>

## 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)