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

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

customRepeatFrequencyTypenumber | nullableOptional

customRepeatFrequencynumber | nullableOptional

customRepeatDaysall ofOptional

and

undefined · enumOptional

Used when a reference can be null

Possible values:

customEndMessageTypenumber | nullableOptional

customEndMessageDatestring | nullableOptional

customEndMessageOccurrencesnumber | nullableOptional

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

{
  "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",
  "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
}

{
  "statusCode": "MTANoLinkedAccountError",
  "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