Send an MMS Message

Learn more about sending an MMS with Mobile Text Alerts

MMS stands for Multimedia Messaging Service 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)

A message with an attachment will be sent as MMS by default (messages without an attachment will be sent as SMS). Messages without an attachment can be sent as MMS if isMMS is set to true.

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 would 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:

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 MTA. When sending a request to the /send endpoint, if the rehost flag is set to true, the attachment will be rehosted by MTA 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 are sent via the API with a POST request to the /send endpoint just like SMS, but include the image field for the URL of the attachment that will be sent. 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.

  • 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 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 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 MTA before being sent to the recipients.

How to send an MMS with the API

1

Indicate the recipients(s)

You can send a message to a phone number as a test. Here you would set the subscribers field to the recipient phone number.

"subscribers": [1112223333]

2

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.

"message": "Use promo code TESTMESSAGE for 5% off when you sign up. STOP to end"
"image": "https://imgur.com/gallery/example"

3

Form API request

Create the API request to the /send endpoint. Remember to include Authorization header.

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"
        }'

4

Receive response

The API will return a message about the status of your request.

{
  "data": {
    "messageId": "uuid",
    "totalSent": 1,
    "totalFailedInternationalRecipients": 0
  },
  "message": "Message Sent to 1 Recipient."
}

Send Message endpoint POST /send

Send Message from API

post

Overview

Request Fields

• message: string

  • The body of the message.

• image: string

  • An attachment for the message in the form of a URL.

  • See Send as MMS for more details.

• rehost: boolean

  • An indicator to specify if the attached image should be rehosted by MTA before being sent.

  • See Send as MMS for more details.

• templateId: number

  • A template id corresponding to the controlled template that should be used as the body of the message.

• linkId: number

  • If the message content is specified using a templateId and the template includes a link, this field is used to find the correspinding link.

• subscriberIds: number[]

  • A list of subscriber ids to send the message to.

• subscribers: (number | string)[]

  • A list of phone numbers and/or emails to send the message to. Phone numbers can be provided in the number or string type.

• allSubscribers: boolean

  • An indicator to send the message to all subscribers if true.

  • Default: false.

• groups: number[]

  • A list of group ids to send the message to.

• threadId: number

  • A thread id to send the message to.

• isMMS: boolean

  • An indicator to send the message as MMS instead of SMS.

  • Default behavior: False for messages without an attachment. True for messages with an attachment.

  • See Send as MMS for more details.

• header: string

  • A message to include before the message body. A newline will be added between the header and message body.

• footer: string

  • A message to include at the end of the message body. A space will be added between the message body and footer.

• longcodeId: number

  • The longcode id corresponding to the dedicated number to send the message from.

• senderName: string

  • If your account is enabled for iMessage sending, specify your desired sender name using this field.

• externalId: string

  • An external id to include with the metadata of your message. The externalId will be included in webhook notifications.

• properties: { [key: string]: string }

  • Properties are used to populate the liquid template variables in your message.

  • See Using Properties for details.

• scheduledDate: string

  • The date and time a message should be scheduled to send.

  • Must be in ISO8601 format (eg. "20230302T173000-0500").

• repeat: IRepeat

  • If a scheduled message should go out repeatedly, repeat indicates how.

  • Default behavior: If repeat is not provided, the scheduled message will not repeat.

  • interface IRepeat {
        monday: boolean;
        tuesday: boolean;
        wednesday: boolean;
        thursday: boolean;
        friday: boolean;
        saturday: boolean;
        sunday: boolean;
        type: "week" | "month";
        frequency: RepeatFrequency;
    }

  • enum RepeatFrequency {
        NEVER = 0,
        DAILY = 1,
        WEEKLY = 2,
        BIWEEKLY = 3,
        MONTHLY = 4,
        ANNUALLY = 5
    }

• tags

  • Tags is a map of custom data to be included with your webhook notifications.

Required Fields

• Content to Send: One of the following

  • message

  • image

  • templateId

• Recipients: One of the following

  • subscriberIds

  • subscribers

  • allSubscribers

  • groups

  • threadId

• If templateId is used and corresponds to a template that requires a link, linkId is required.

Notes

• The subscribers field is a list of recipient phone numbers or email addresses. If a provided recipient is not already a subscriber on your account, one will be created.

• Messages will be sent to a subscriber's phone number if one is set, otherwise, the message will be sent to the subscriber via email.

Features

Send to All Subscribers

The allSubscribers request field can be set to true in order to send the message to all subscribers. When allSubscribers is set to true, no other recipient fields should be specified.

Send as MMS

A message with an attachment (image) will be sent as MMS by default. A messages without an attachment will be sent as SMS by default. A message without an attachment can be sent as MMS by setting the isMMS request field to true.

If the rehost flag is provided and is set to true, the attachment will be rehosted on an MTA server before being sent to the recipients. You may prefer to do this in the event that the recipient isn't receiving your attachment or you simply don't want to host the attachment yourself.

Credit Costs

• SMS messages cost 1 credit per 160 characters

• MMS messages cost 3 credits

Template-Only Sending

• Accounts configured for template-only sending should provide a templateId rather than a message.

• If the template corresponding to templateId requires a link, a linkId should also be provided.

• All available controlled templates can be queried via the Controlled Template endpoints.

• Links can be created using the Create Short Link endpoint.

Using Properties

By inserting one or more Liquid Template variables into your message and using the properties field, you can send a unique message to each subscriber with a single API call.

The properties field is a map between the individual subscribers you're sending your message to, and the values of the variables in your message.

Example:

{
    "subscribers": ["3175551111", "3175552222"],
    "message": "Hello {{firstName}}! Visit {{link}}",
    "properties": {
        "3175551111": {
            "firstName": "Bob",
            "link": "https://example.com/abc"
        },
        "3175552222": {
            "firstName": "Tony",
            "link": "https://example.com/def"
        }
    }
}

Duplicate Requests (Idempotency)

The send endpoint is idempotent which means that it handles de-duplicating requests in the event of networking issues or other issues that might cause a request to be in an unknown state.

When sending your request to the endpoint, simply include an X-Request-Id header with an alphanumeric value. If you're unsure if the request succeeded or not, you can simply re-send the request with the same X-Request-Id and the send endpoint will detect if it's a duplicate or not.

If the request is a duplicate, you'll receive a 409 Conflict error response.

iMessage Sending

Introduction

Please Note: This feature is currently in beta and is not yet generally available. If you're interested in sending iMessages and want to participate in our beta program, please reach out to your account manager to notify them of your interest.

What is iMessage?

iMessage is an Apple designed and built messaging service available to users of iOS, iPadOS, macOS and watchOS devices. Users can send and receive messages with each other, much like they can via SMS, MMS or email and it is widely known for its "blue bubbles". Apple has designed iMessage to be a secure message ecosystem thus increasing user trust when they send and receive iMessages. It is estimated that there are over 1 billion iMessage users across the globe.

Why send via iMessage?

Due to the security features and ubiquity of iMessage, it has quickly become a highly trusted method of communication for users around the globe. As a result, you can expect to have broader reach and better engagement from those recipients that you contact via iMessage using an identity that is synonymous with your brand (see below). iMessage also has a much higher throughput in terms of media sizes for attachments, enabling higher resolution photos and even videos.

---

Sender Identities

When communicating with subscribers via iMessage, you'll use a unique, dedicated "Sender Identity" that helps identify your brand.

What is a Sender Identity?

A Sender Identity is the sequence of characters that appears at the top of an iMessage conversation when you send a message to any of your iMessage enabled recipients. In other words, it is the "contact" that your recipients will receive messages from and reply to when interacting with your brand via iMessage. Sender Identities look like an email address and consist of the sending name and a domain. When sending messages via Mobile Text Alerts, you can use one or more Sender Identities to send iMessages and can select which to use in the same way you select an outbound longcode for SMS messaging.

Provisioning and Using Sender Identities

Upon enrollment in the iMessage sending program, a Sender Identity will be provisioned for your account. You'll be able to supply a desired name for your Sender Identity but it will come with a preconfigured domain that we've configured and verified for iMessage sending. Mobile Text Alerts also provides support for Custom Domains for Sender Identities (more below). You can request additional Sender Identities be provisioned for your account. It may take up to 3 days to complete the provisioning process depending on the number of identities requested. Once provisioned, our team will attach each Sender Identity to an outbound longcode on your account. When sending messages, selection of a particular longcode will correspond to a particular Sender Identity. If Mobile Text Alerts detects that a recipient is iMessage enabled, it will use the Sender Identity associated with the outbound longcode and send via iMessage instead of SMS.

Custom Domains

Mobile Text Alerts is capable of supporting custom domains for your Sender Identities but it requires some additional configuration and set up before you can begin using them. When you submit a request for a Custom Domain to our team, we will discuss and identify the particular domain you'd like to use. Depending on your particular use case, Mobile Text Alerts will either purchase and maintain the domain on your behalf, or you can purchase one and provide it to us. We'll need to configure a few DNS entries to properly set up your custom domain. Once initial configuration is complete, you can provision all future Sender Identities using this domain.

---

Subscriber Opt In

As with SMS, capturing the proper consent and opt-ins from your recipients is critical to the successful usage of the iMessage capabilities offered by Mobile Text Alerts. Capturing opt-ins ensures that your recipients are expecting to hear from you via iMessage and it gives you an opportunity to identify yourself to the recipient. In doing so, you can be sure that your messages are safely delivered without being marked as spam by the recipient.

iMessage Opt In

In order to send iMessages to your recipients, you must receive an inbound opt-in message from them before you send your first outbound message. Regardless of whether an opt-in was collected for communications via SMS or email, an explicit iMessage opt-in is required. This can be as simple as sending in "Sign me up" to your Sender Identity one time. Mobile Text Alerts provides a useful feature for accomplishing this and automatically tracks iMessage opt-ins for you when using this system: deeplinks.

Deeplinks

A deeplink looks and works like any other website link but behaves differently depending on the user's browser, device or operating system. Mobile Text Alerts provides a powerful deeplinking technology that can both identify if a recipient is capable of sending iMessages and link to a prompt to send their first inbound opt-in message to your Sender Identity. A Mobile Text Alerts deeplink works like this:

1. Generate your iMessage opt-in deeplink, which will look like this: https://mobile-text-alerts.com/deeplink/abcd1234

2. Through a method of your choice, direct your subscribers to this deeplink. For example, you could send an SMS campaign from Mobile Text Alerts that announces your customers can now receive iMessages from you by clicking the link (which is your deeplink from Step 1)

3. When a recipient clicks this link, Mobile Text Alerts with automatically detect whether they can send/receive iMessages.

4. If they can send/receive iMessages, Mobile Text Alerts will redirect them to a special iMessage specific link (eximessage://[email protected]&body=Signup) which launches iMessage and prefills their opt-in message. All they have to do is hit send.

5. If they cannot send/receive iMessages (for example, the link was opened on an Android phone or the web), the deeplink will gracefully redirect them to a context-sensible location (launch the SMS app instead, show a web opt-in form etc.)

If you choose to prompt your recipients for iMessage opt-ins via another method, you can still use the special imessage:// style URL to launch the iMessage app and prefill the message.

Sending Outbound Messages First

Mobile Text Alerts presently doesn't allow outbound messages to be sent to recipients before receiving an inbound opt-in message from them. As a result, messages can only be sent via iMessage to recipients that have explicitly completed the opt-in flow. This provides the best protection for your Sender Identities. Recipients are naturally wary of receiving unsolicited messages through iMessage since it is a peer to peer messaging system primarily. Apple may even prompt the user with a "Report Junk" warning for outbound messages received without an explicit inbound message from the recipient. These reports can result in your Sender Identity being blocked or disabled, which will directly impact your ability to deliver messages via iMessage. Our opt-in requirement provides the best possible protection for your Sender Identities.

Are there ways to send outbound messages first via iMessage?

In certain uncommon cases, the restriction on requiring an inbound opt-in can be relaxed for individual Sender Identities, after careful review by our team. As described above, this significantly increases the risk of impact on delivery rates for that Sender Identity and in making a request to lift this restriction, you are accepting that increased risk. Our team will only consider these requests for pre-existing Sender Identities that have already been in use. Our evaluation will look at the age of the Sender Identity (min 3 months old), number of active conversations and overall inbound message reply rates and it is not guaranteed that a Sender Identity will be approved for outbound-first messaging.

---

Message Sending

Once your subscribers begin opting-in to receiving iMessages, you're ready to begin sending to them. As mentioned above, Mobile Text Alerts will automatically capture and record the inbound opt-in messages and internally flag your subscribers as iMessage enabled and opted-in. Remember, opt-ins are tied to a specific Sender Identity, so you must receive inbound consent from a subscriber on each Sender Identity you plan to use to send messages to them. When sending messages via API, you'll specify a Sender Identity (more on that below) and Mobile Text Alerts will handle routing messages intelligently based on current subscriber status. For those subscibers included in a /send call, the system will examine whether they are enabled for iMessage and will route messages through your Sender Identity if so. The system also handles graceful fallback to SMS (also more on that further below).

Specifying a Sender Identity

When making /send API calls, you won't need to adjust much in order to send messages via iMessage. If you've completed all the necessary configuration and set up steps, you should have a Sender Identity that is attached to one of your existing outbound longcodes used for SMS/MMS. Your API calls will continue to supply a longcodeId and when that longcode has an associated iMessage Sender Identity, Mobile Text Alerts will use that identity for iMessage enabled recipients. This structure enables minimial change necessary to start using the iMessage route and provides flexibility to manage Sender Identities like you currently manage longcodes.

SMS Fallback

The iMessage route also supports graceful fallback for a number of failure scenarios. An outbound iMessage may fail for any of the following reasons:

• The subscriber is not capable of receiving iMessages

• The subscriber has not opted-in via inbound message to the selected Sender Identity

• The Sender Identity has been disabled, blocked, or banned

• Our iMessage route is temporarily unavailable

If any of these failures occur, Mobile Text Alerts will fall back gracefully to SMS in order to deliver your message. In this way, you can have the confidence that your subscriber will always receive your message, even if there's an issue preventing us from using iMessage to deliver that particular message.

Webhooks

When sending messages via the iMessage route, you can expect to receive webhooks from Mobile Text Alerts consistent with other messaging routes such as SMS. For messages routed via iMessage, you will receive delivery status callbacks as the message's status changes through the process of sending. When inbound messages are sent in to your Sender Identities, Mobile Text Alerts will deliver message reply webhooks consistent with inbound SMS messages. For more information on configuring webhooks for your account, please see the Webhooks section of our documentation.

Rate Limiting

This endpoint overrides the general rate limit with an account rate limit. Requests are limited by the authenticated account instead of the IP address. This endpoint is limited to 25 requests every 15 seconds

Authorizations

Body

groupsnumber[]Optional

subscriberIdsnumber[]Optional

allSubscribersbooleanOptional

excludedGroupIdsnumber[]Optional

threadIdnumberOptional

messagestringRequired

imagestringOptional

rehostbooleanOptional

externalIdstringOptional

scheduledDatestringOptional

headerstringOptional

footerstringOptional

isMMSbooleanOptional

repeatall ofOptional

and

linkClickDaysnumberOptional

templateIdnumberOptional

linkIdnumberOptional

longcodeIdnumberOptional

eventIdstringOptional

skipHeaderFooterbooleanOptional

addPlaceholderbooleanOptional

sourcestring · enumOptionalPossible values:

userSignaturestringOptional

poolIdstringOptional

userIdnumberOptional

senderNamestringOptional

exactSenderbooleanOptional

customRepeatFrequencyTypenumber | nullableOptional

customRepeatFrequencynumber | nullableOptional

customRepeatDaysall ofOptional

and

undefined · enumOptional

Used when a reference can be null

Possible values:

customEndMessageTypenumber | nullableOptional

customEndMessageDatestring | nullableOptional

customEndMessageOccurrencesnumber | nullableOptional

gatedbooleanOptional

brandImagestringOptional

Responses

200

Success

application/json

Responseall of

400

BadRequestError

application/json

401

UnauthorizedError

application/json

403

ForbiddenError

application/json

429

RateLimitError

application/json

500

InternalServerError

application/json

post

HTTPcURLJavaScriptPython

POST /v3/send HTTP/1.1
Host: api.mobile-text-alerts.com
Authorization: Bearer apiKey
Content-Type: application/json
Accept: */*
Content-Length: 1084

{
  "groups": [
    1
  ],
  "subscribers": [
    1
  ],
  "subscriberIds": [
    1
  ],
  "allSubscribers": true,
  "excludedGroupIds": [
    1
  ],
  "threadId": 1,
  "message": "text",
  "image": "text",
  "rehost": true,
  "externalId": "text",
  "scheduledDate": "text",
  "header": "text",
  "footer": "text",
  "properties": {
    "ANY_ADDITIONAL_PROPERTY": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    }
  },
  "isMMS": true,
  "repeat": {
    "monday": true,
    "tuesday": true,
    "wednesday": true,
    "thursday": true,
    "friday": true,
    "saturday": true,
    "sunday": true,
    "type": "week",
    "frequency": -1,
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "linkClickDays": 1,
  "templateId": 1,
  "linkId": 1,
  "longcodeId": 1,
  "eventId": "text",
  "skipHeaderFooter": true,
  "addPlaceholder": true,
  "source": "control-panel",
  "userSignature": "text",
  "tags": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "poolId": "text",
  "userId": 1,
  "senderName": "text",
  "exactSender": true,
  "customRepeatFrequencyType": 1,
  "customRepeatFrequency": 1,
  "customRepeatDays": {
    "monday": true,
    "tuesday": true,
    "wednesday": true,
    "thursday": true,
    "friday": true,
    "saturday": true,
    "sunday": true
  },
  "customEndMessageType": 1,
  "customEndMessageDate": "text",
  "customEndMessageOccurrences": 1,
  "gated": true,
  "brandImage": "text"
}

{
  "success": true,
  "error": "text",
  "message": "text",
  "data": {
    "messageId": "text",
    "totalSent": 1,
    "totalFailedInternationalRecipients": 1,
    "outboundIds": [
      1
    ]
  }
}

Learn More

Mobile Text Alerts - MMS Messaging

SMS and MMS: What They Are and When to Use Them