Send

Send Message from API POST /send

Sending Utilities

Validate Recipients POST /send/validate-recipients
Shorten Message POST /send/shorten-message
Get Message Cost POST /send/cost
Get Message Delivery Time POST /send/messaging-speeds

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:

Generate your iMessage opt-in deeplink, which will look like this: https://mobile-text-alerts.com/deeplink/abcd1234
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)
When a recipient clicks this link, Mobile Text Alerts with automatically detect whether they can send/receive iMessages.
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.
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

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

groupsnumber[]Optional

subscriberIdsnumber[]Optional

allSubscribersbooleanOptional

excludedGroupIdsnumber[]Optional

threadIdnumberOptional

messagestringRequired

imagestringOptional

rehostbooleanOptional

externalIdstringOptional

scheduledDatestringOptional

headerstringOptional

footerstringOptional

isMMSbooleanOptional

linkClickDaysnumberOptional

templateIdnumberOptional

linkIdnumberOptional

longcodeIdnumberOptional

eventIdstringOptional

skipHeaderFooterbooleanOptional

addPlaceholderbooleanOptional

sourcestring · enumOptionalPossible values:

userSignaturestringOptional

poolIdstringOptional

userIdnumberOptional

senderNamestringOptional

exactSenderbooleanOptional

customRepeatFrequencyTypenumber · nullableOptional

customRepeatFrequencynumber · nullableOptional

customEndMessageTypenumber · nullableOptional

customEndMessageDatestring · nullableOptional

customEndMessageOccurrencesnumber · nullableOptional

gatedbooleanOptional

brandImagestringOptional

Responses

200

Success

application/json

400

BadRequestError

application/json

401

UnauthorizedError

application/json

403

ForbiddenError

application/json

429

RateLimitError

application/json

500

InternalServerError

application/json

post

/send

POST /v3/send HTTP/1.1
Host: api.mobile-text-alerts.com
Authorization: Bearer YOUR_SECRET_TOKEN
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
    ]
  }
}

Validate Recipients

post

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

validateUnsubscribesbooleanOptional

Responses

200

Success

application/json

400

BadRequestError

application/json

401

UnauthorizedError

application/json

403

ForbiddenError

application/json

500

InternalServerError

application/json

post

/send/validate-recipients

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

{
  "recipients": [
    {
      "externalId": 1,
      "number": 1,
      "email": "text"
    }
  ],
  "validateUnsubscribes": true
}

{
  "success": true,
  "error": "text",
  "message": "text",
  "data": {
    "validRecipients": [
      {
        "externalId": 1,
        "number": 1,
        "email": "text"
      }
    ],
    "invalidRecipients": [
      {
        "externalId": 1,
        "number": 1,
        "email": "text",
        "error": "text"
      }
    ]
  }
}

Shorten Message

post

Rate Limiting

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

messagestringRequired

Responses

200

Success

application/json

400

BadRequestError

application/json

401

UnauthorizedError

application/json

403

ForbiddenError

application/json

429

RateLimitError

application/json

500

InternalServerError

application/json

post

/send/shorten-message

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

{
  "message": "text"
}

{
  "success": true,
  "error": "text",
  "message": "text",
  "data": {
    "shortenedMessage": "text"
  }
}

Get Message Cost

post

Overview

Request Fields

from: string
- The phone number used to send the message
to: string
- The phone number the message is being sent to
message: string
- The contents of the message being sent
isMMS: boolean
- An indicator to that the message is an MMS instead of SMS.
- Default behavior: False

Response Fields

fee: number
- The fee for sending the message
carrierFee: number
- The carrier fee for sending the message, when applicable
totalCost: number
- The total cost for sending the message
messageCredits: number
- The number of message credits used for sending the message
premiumCredits: number
- The number of premium credits used for sending the message
messageCount: number
- The number of messages that would be sent

Notes

The message field can be excluded or left blank to indicate that, when isMMS is true, that the message would be an attachment only.
The isMMS field can be excluded and will default to false.

undefined

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

fromstringOptional

tostringRequired

messagestringOptional

isMMSbooleanOptional

Responses

200

Success

application/json

400

BadRequestError

application/json

401

UnauthorizedError

application/json

403

ForbiddenError

application/json

500

InternalServerError

application/json

post

/send/cost

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

{
  "from": "text",
  "to": "text",
  "message": "text",
  "isMMS": true
}

{
  "success": true,
  "error": "text",
  "message": "text",
  "data": {
    "fee": 1,
    "carrierFee": 1,
    "totalCost": 1,
    "messageCredits": 1,
    "premiumCredits": 1,
    "messageCount": 1
  }
}

Get Message Delivery Time

post

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

longcodeIdnumberRequired

groupsnumber[]Optional

subscriberIdsnumber[]Optional

allSubscribersbooleanOptional

excludedGroupIdsnumber[]Optional

isMMSbooleanOptional

linkClickDaysnumberOptional

Responses

200

Success

application/json

400

BadRequestError

application/json

401

UnauthorizedError

application/json

403

ForbiddenError

application/json

500

InternalServerError

application/json

post

/send/messaging-speeds

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

{
  "longcodeId": 1,
  "groups": [
    1
  ],
  "subscriberIds": [
    1
  ],
  "allSubscribers": true,
  "excludedGroupIds": [
    1
  ],
  "isMMS": true,
  "linkClickDays": 1
}

{
  "success": true,
  "error": "text",
  "message": "text",
  "data": {
    "totalRecipients": 1,
    "fromNumber": 1,
    "longcodeStatus": "Basic",
    "isLongcodeRegistered": true,
    "time": {
      "hours": 1,
      "minutes": 1
    },
    "timeByCarrier": [
      {
        "carrier": "text",
        "time": {
          "hours": 1,
          "minutes": 1
        }
      }
    ],
    "brandRegistration": {
      "status": "Pending",
      "estimatedApprovalDate": "text"
    }
  }
}

PreviousScheduled Messages NextShortcodes

Last updated 2 months ago

Was this helpful?

hashtagSending Utilities

hashtagSend Message from API

hashtagOverview

hashtagRequest Fields

hashtagRequired Fields

hashtagNotes

hashtagFeatures

hashtagSend to All Subscribers

hashtagSend as MMS

hashtagCredit Costs

hashtagTemplate-Only Sending

hashtagUsing Properties

hashtagDuplicate Requests (Idempotency)

hashtagiMessage Sending

hashtagIntroduction

hashtagWhat is iMessage?

hashtagWhy send via iMessage?

hashtagSender Identities

hashtagWhat is a Sender Identity?

hashtagProvisioning and Using Sender Identities

hashtagCustom Domains

hashtagSubscriber Opt In

hashtagiMessage Opt In

hashtagDeeplinks

hashtagSending Outbound Messages First

hashtagMessage Sending

hashtagSpecifying a Sender Identity

hashtagSMS Fallback

hashtagWebhooks

hashtagRate Limiting

hashtagValidate Recipients

hashtagShorten Message

hashtagRate Limiting

hashtagGet Message Cost

hashtagOverview

hashtagRequest Fields

hashtagResponse Fields

hashtagNotes

hashtagGet Message Delivery Time

Sending Utilities

Send Message from API

Overview

Request Fields

Required Fields

Notes

Features

Send to All Subscribers

Send as MMS

Credit Costs

Template-Only Sending

Using Properties

Duplicate Requests (Idempotency)

iMessage Sending

Introduction

What is iMessage?

Why send via iMessage?

Sender Identities

What is a Sender Identity?

Provisioning and Using Sender Identities

Custom Domains

Subscriber Opt In

iMessage Opt In

Deeplinks

Sending Outbound Messages First

Message Sending

Specifying a Sender Identity

SMS Fallback

Webhooks

Rate Limiting

Validate Recipients

Shorten Message

Rate Limiting

Get Message Cost

Overview

Request Fields

Response Fields

Notes

Get Message Delivery Time