# Send * Send Message from API [#post-send](#post-send "mention") ### Sending Utilities * Validate Recipients [#post-send-validate-recipients](#post-send-validate-recipients "mention") * Shorten Message [#post-send-shorten-message](#post-send-shorten-message "mention") * Get Message Cost [#post-send-cost](#post-send-cost "mention") * Get Message Delivery Time [#post-send-messaging-speeds](#post-send-messaging-speeds "mention") ## Send Message from API > \# 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]\(#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]\(#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]\(#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]\(#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.\ > \ > \- \`\`\`typescript\ > interface IRepeat {\ > monday: boolean;\ > tuesday: boolean;\ > wednesday: boolean;\ > thursday: boolean;\ > friday: boolean;\ > saturday: boolean;\ > sunday: boolean;\ > type: "week" | "month";\ > frequency: RepeatFrequency;\ > }\ > \`\`\`\ > \ > \- \`\`\`typescript\ > 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:\ > \ > \`\`\`json\ > {\ > "subscribers": \["3175551111", "3175552222"],\ > "message": "Hello {{firstName}}! Visit {{link}}",\ > "properties": {\ > "3175551111": {\ > "firstName": "Bob",\ > "link": " > },\ > "3175552222": {\ > "firstName": "Tony",\ > "link": " > }\ > }\ > }\ > \`\`\`\ > \ > \## 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: \` > \ > 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 (ex\`imessage://yoursenderidentity\@your-imsg-domain.com\&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 ````json {"openapi":"3.0.0","info":{"title":"Mobile Text Alerts API","version":"8.0.0"},"servers":[{"url":"https://api.mobile-text-alerts.com/v3"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"apiKey"}},"schemas":{"SendMessage.Response":{"allOf":[{"$ref":"#/components/schemas/IApiResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"messageId":{"type":"string"},"totalSent":{"type":"number"},"totalFailedInternationalRecipients":{"type":"number"},"outboundIds":{"type":"array","items":{"type":"number"}}},"required":["totalSent","totalFailedInternationalRecipients"]}},"required":["data"]}]},"IApiResponse":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"},"message":{"type":"string"},"data":{}},"required":[]},"SendMessage.Request":{"type":"object","properties":{"groups":{"type":"array","items":{"type":"number"}},"subscribers":{"type":"array","items":{"oneOf":[{"type":"number"},{"type":"string"}]}},"subscriberIds":{"type":"array","items":{"type":"number"}},"allSubscribers":{"type":"boolean"},"excludedGroupIds":{"type":"array","items":{"type":"number"}},"threadId":{"type":"number"},"message":{"type":"string"},"image":{"type":"string"},"rehost":{"type":"boolean"},"externalId":{"type":"string"},"scheduledDate":{"type":"string"},"header":{"type":"string"},"footer":{"type":"string"},"properties":{"type":"object","additionalProperties":{"type":"object","additionalProperties":{"type":"string"}}},"isMMS":{"type":"boolean"},"repeat":{"$ref":"#/components/schemas/IMessageRepeat"},"linkClickDays":{"type":"number"},"templateId":{"type":"number"},"linkId":{"type":"number"},"longcodeId":{"type":"number"},"eventId":{"type":"string"},"skipHeaderFooter":{"type":"boolean"},"addPlaceholder":{"type":"boolean"},"source":{"$ref":"#/components/schemas/SendRequestSource"},"userSignature":{"type":"string"},"tags":{"type":"object","additionalProperties":{"type":"string"}},"poolId":{"type":"string"},"userId":{"type":"number"},"senderName":{"type":"string"},"exactSender":{"type":"boolean"},"customRepeatFrequencyType":{"type":"number","nullable":true},"customRepeatFrequency":{"type":"number","nullable":true},"customRepeatDays":{"allOf":[{"$ref":"#/components/schemas/IRepeatDays"},{"$ref":"#/components/schemas/NullReference"}]},"customEndMessageType":{"type":"number","nullable":true},"customEndMessageDate":{"type":"string","nullable":true},"customEndMessageOccurrences":{"type":"number","nullable":true},"gated":{"type":"boolean"},"brandImage":{"type":"string"}},"required":["message"]},"IMessageRepeat":{"allOf":[{"type":"object","properties":{"monday":{"type":"boolean"},"tuesday":{"type":"boolean"},"wednesday":{"type":"boolean"},"thursday":{"type":"boolean"},"friday":{"type":"boolean"},"saturday":{"type":"boolean"},"sunday":{"type":"boolean"},"type":{"$ref":"#/components/schemas/RepeatMonthType"},"frequency":{"$ref":"#/components/schemas/RepeatFrequency"}},"required":["monday","tuesday","wednesday","thursday","friday","saturday","sunday","type","frequency"]},{"type":"object","additionalProperties":{}}]},"RepeatMonthType":{"type":"string","enum":["week","month"]},"RepeatFrequency":{"format":"int32","type":"number","enum":[-1,1,2,3,4,5]},"SendRequestSource":{"type":"string","enum":["control-panel","php-api","platform","node-api","ios-app","android-app","shopify-app","node-inbox","php-inbox","zipwhip-sync","scheduled","hooks","workflow","webinars","chatbot","hubspot-sync"]},"IRepeatDays":{"type":"object","properties":{"monday":{"type":"boolean"},"tuesday":{"type":"boolean"},"wednesday":{"type":"boolean"},"thursday":{"type":"boolean"},"friday":{"type":"boolean"},"saturday":{"type":"boolean"},"sunday":{"type":"boolean"}},"required":["monday","tuesday","wednesday","thursday","friday","saturday","sunday"]},"NullReference":{"title":"Null Reference","description":"Used when a reference can be null","enum":[null]}},"responses":{"BadRequestError":{"description":"BadRequestError","content":{"application/json":{"schema":{"type":"object","properties":{"httpCode":{"type":"number","enum":[400]},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"type":{"type":"string","enum":["bad_request_error"]},"name":{"type":"string","enum":["MTABadRequestError"]},"requestId":{"type":"string","format":"uuid"}}}}}},"UnauthorizedError":{"description":"UnauthorizedError","content":{"application/json":{"schema":{"type":"object","properties":{"httpCode":{"type":"number","enum":[401]},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"type":{"type":"string","enum":["unauthorized_error"]},"name":{"type":"string","enum":["MTAUnauthorizedError"]},"requestId":{"type":"string","format":"uuid"}}}}}},"ForbiddenError":{"description":"ForbiddenError","content":{"application/json":{"schema":{"type":"object","properties":{"httpCode":{"type":"number","enum":[403]},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"type":{"type":"string","enum":["forbidden_error"]},"name":{"type":"string","enum":["MTAForbiddenError"]},"requestId":{"type":"string","format":"uuid"},"reason":{}}}}}},"RateLimitError":{"description":"RateLimitError","content":{"application/json":{"schema":{"type":"object","properties":{"httpCode":{"type":"number","enum":[429]},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"type":{"type":"string","enum":["rate_limit_error"]},"name":{"type":"string","enum":["MTARateLimitError"]},"requestId":{"type":"string","format":"uuid"}}}}}},"InternalServerError":{"description":"InternalServerError","content":{"application/json":{"schema":{"type":"object","properties":{"httpCode":{"type":"number","enum":[500]},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"type":{"type":"string","enum":["internal_server_error"]},"name":{"type":"string","enum":["MTAInternalServerError"]},"requestId":{"type":"string","format":"uuid"}}}}}}}},"paths":{"/send":{"post":{"tags":["Send"],"summary":"Send Message from API","description":"# Overview\n\n## Request Fields\n\n- `message: string`\n\n - The body of the message.\n\n- `image: string`\n\n - An attachment for the message in the form of a URL.\n\n - See [Send as MMS](#send-as-mms) for more details.\n\n- `rehost: boolean`\n\n - An indicator to specify if the attached image should be rehosted by MTA before being sent.\n\n - See [Send as MMS](#send-as-mms) for more details.\n\n- `templateId: number`\n\n - A template id corresponding to the controlled template that should be used as the body of the message.\n\n- `linkId: number`\n\n - If the message content is specified using a `templateId` and the template includes a link, this field is used to find the correspinding link.\n\n- `subscriberIds: number[]`\n\n - A list of subscriber ids to send the message to.\n\n- `subscribers: (number | string)[]`\n\n - A list of phone numbers and/or emails to send the message to. Phone numbers can be provided in the number or string type.\n\n- `allSubscribers: boolean`\n\n - An indicator to send the message to all subscribers if true.\n\n - Default: `false`.\n\n- `groups: number[]`\n\n - A list of group ids to send the message to.\n\n- `threadId: number`\n\n - A thread id to send the message to.\n\n- `isMMS: boolean`\n\n - An indicator to send the message as MMS instead of SMS.\n\n - Default behavior: False for messages without an attachment. True for messages with an attachment.\n\n - See [Send as MMS](#send-as-mms) for more details.\n\n- `header: string`\n\n - A message to include before the message body. A newline will be added between the header and message body.\n\n- `footer: string`\n\n - A message to include at the end of the message body. A space will be added between the message body and footer.\n\n- `longcodeId: number`\n\n - The longcode id corresponding to the dedicated number to send the message from.\n\n- `senderName: string`\n\n - If your account is enabled for iMessage sending, specify your desired sender name using this field.\n\n- `externalId: string`\n\n - An external id to include with the metadata of your message. The `externalId` will be included in webhook notifications.\n\n- `properties: { [key: string]: string }`\n\n - Properties are used to populate the liquid template variables in your message.\n\n - See [Using Properties](#using-properties) for details.\n\n- `scheduledDate: string`\n\n - The date and time a message should be scheduled to send.\n\n - Must be in ISO8601 format (eg. \"20230302T173000-0500\").\n\n- `repeat: IRepeat`\n\n - If a scheduled message should go out repeatedly, `repeat` indicates how.\n\n - Default behavior: If `repeat` is not provided, the scheduled message will not repeat.\n\n - ```typescript\n interface IRepeat {\n monday: boolean;\n tuesday: boolean;\n wednesday: boolean;\n thursday: boolean;\n friday: boolean;\n saturday: boolean;\n sunday: boolean;\n type: \"week\" | \"month\";\n frequency: RepeatFrequency;\n }\n ```\n\n - ```typescript\n enum RepeatFrequency {\n NEVER = 0,\n DAILY = 1,\n WEEKLY = 2,\n BIWEEKLY = 3,\n MONTHLY = 4,\n ANNUALLY = 5\n }\n ```\n\n- `tags`\n\n - Tags is a map of custom data to be included with your webhook notifications.\n\n\n## Required Fields\n\n- Content to Send: One of the following\n\n - `message`\n\n - `image`\n\n - `templateId`\n\n- Recipients: One of the following\n\n - `subscriberIds`\n\n - `subscribers`\n\n - `allSubscribers`\n\n - `groups`\n\n - `threadId`\n\n- If `templateId` is used and corresponds to a template that requires a link, `linkId` is required.\n\n\n## Notes\n\n- 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.\n\n- 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.\n\n\n# Features\n\n## Send to All Subscribers\n\nThe `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.\n\n## Send as MMS\n\nA 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`.\n\nIf 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.\n\n### Credit Costs\n\n- SMS messages cost 1 credit per 160 characters\n\n- MMS messages cost 3 credits\n\n\n## Template-Only Sending\n\n- Accounts configured for template-only sending should provide a `templateId` rather than a message.\n\n- If the template corresponding to `templateId` requires a link, a `linkId` should also be provided.\n\n- All available controlled templates can be queried via the [Controlled Template](https://docs.mobile-text-alerts.com/#8a6c8f75-ee31-4af1-8788-2b60353c3fdd) endpoints.\n\n- Links can be created using the [Create Short Link](https://docs.mobile-text-alerts.com/#07b764b8-59f7-4bdf-a18e-acf4af15a429) endpoint.\n\n\n## Using Properties\n\nBy 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.\n\nThe `properties` field is a map between the individual subscribers you're sending your message to, and the values of the variables in your message.\n\nExample:\n\n```json\n{\n \"subscribers\": [\"3175551111\", \"3175552222\"],\n \"message\": \"Hello {{firstName}}! Visit {{link}}\",\n \"properties\": {\n \"3175551111\": {\n \"firstName\": \"Bob\",\n \"link\": \"https://example.com/abc\"\n },\n \"3175552222\": {\n \"firstName\": \"Tony\",\n \"link\": \"https://example.com/def\"\n }\n }\n}\n```\n\n## Duplicate Requests (Idempotency)\n\nThe 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.\n\nWhen 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.\n\nIf the request is a duplicate, you'll receive a `409 Conflict` error response.\n\n# iMessage Sending\n\n## Introduction\n\n_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._\n\n### What is iMessage?\n\niMessage 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.\n\n### Why send via iMessage?\n\nDue 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.\n\n---\n\n## Sender Identities\n\nWhen communicating with subscribers via iMessage, you'll use a unique, dedicated \"Sender Identity\" that helps identify your brand.\n\n### What is a Sender Identity?\n\nA 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.\n\n### Provisioning and Using Sender Identities\n\nUpon 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.\n\n### Custom Domains\n\nMobile 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.\n\n---\n\n## Subscriber Opt In\n\nAs 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.\n\n### iMessage Opt In\n\nIn 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.\n\n### Deeplinks\n\nA 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:\n\n1. Generate your iMessage opt-in deeplink, which will look like this: `https://mobile-text-alerts.com/deeplink/abcd1234`\n\n2. 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)\n\n3. When a recipient clicks this link, Mobile Text Alerts with automatically detect whether they can send/receive iMessages.\n\n4. If they can send/receive iMessages, Mobile Text Alerts will redirect them to a special iMessage specific link (ex`imessage://yoursenderidentity@your-imsg-domain.com&body=Signup`) which launches iMessage and prefills their opt-in message. All they have to do is hit send.\n\n5. 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.)\n\n\nIf 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.\n\n### Sending Outbound Messages First\n\nMobile 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.\n\n#### Are there ways to send outbound messages first via iMessage?\n\nIn 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.\n\n---\n\n## Message Sending\n\nOnce 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).\n\n### Specifying a Sender Identity\n\nWhen 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.\n\n### SMS Fallback\n\nThe iMessage route also supports graceful fallback for a number of failure scenarios. An outbound iMessage may fail for any of the following reasons:\n\n- The subscriber is not capable of receiving iMessages\n\n- The subscriber has not opted-in via inbound message to the selected Sender Identity\n\n- The Sender Identity has been disabled, blocked, or banned\n\n- Our iMessage route is temporarily unavailable\n\n\nIf 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.\n\n### Webhooks\n\nWhen 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](https://docs.mobile-text-alerts.com/#a87529ee-01b1-4ef8-a48e-d6234ad0517f) section of our documentation.\n\n\n\n# Rate Limiting\n\nThis 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","operationId":"send_send_message_from_api","responses":{"200":{"description":"Success","headers":{"RateLimit-Limit":{"description":"The maximum number of requests that the consumer is permitted to make per window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"The number of requests remaining in the current rate limit window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"The remaining window before the rate limit resets in milliseconds","schema":{"type":"integer"}},"Retry-After":{"description":"The number of seconds to wait before retrying the request","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"The maximum number of requests that the consumer is permitted to make per window","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"The number of requests remaining in the current rate limit window","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"The remaining window before the rate limit resets in milliseconds","schema":{"type":"integer"}},"X-Request-ID":{"description":"A unique identifier for the request","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessage.Response"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"429":{"$ref":"#/components/responses/RateLimitError"},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessage.Request"}}},"required":true}}}}} ```` ## POST /send/validate-recipients > Validate Recipients ```json {"openapi":"3.0.0","info":{"title":"Mobile Text Alerts API","version":"8.0.0"},"servers":[{"url":"https://api.mobile-text-alerts.com/v3"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"apiKey"}},"schemas":{"ValidateRecipients.Response":{"allOf":[{"$ref":"#/components/schemas/IApiResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"validRecipients":{"type":"array","items":{"type":"object","properties":{"externalId":{"oneOf":[{"type":"number"},{"type":"string"}]},"number":{"oneOf":[{"type":"number"},{"type":"string"}]},"email":{"type":"string"}},"required":[],"description":"ValidateRecipients.IRecipient"}},"invalidRecipients":{"type":"array","items":{"allOf":[{"type":"object","properties":{"externalId":{"oneOf":[{"type":"number"},{"type":"string"}]},"number":{"oneOf":[{"type":"number"},{"type":"string"}]},"email":{"type":"string"}},"required":[],"description":"ValidateRecipients.IRecipient"},{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}]}}},"required":["validRecipients","invalidRecipients"]}},"required":["data"]}]},"IApiResponse":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"},"message":{"type":"string"},"data":{}},"required":[]},"ValidateRecipients.Request":{"type":"object","properties":{"recipients":{"type":"array","items":{"type":"object","properties":{"externalId":{"oneOf":[{"type":"number"},{"type":"string"}]},"number":{"oneOf":[{"type":"number"},{"type":"string"}]},"email":{"type":"string"}},"required":[],"description":"ValidateRecipients.IRecipient"}},"validateUnsubscribes":{"type":"boolean"}},"required":["recipients"]}},"responses":{"BadRequestError":{"description":"BadRequestError","content":{"application/json":{"schema":{"type":"object","properties":{"httpCode":{"type":"number","enum":[400]},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"type":{"type":"string","enum":["bad_request_error"]},"name":{"type":"string","enum":["MTABadRequestError"]},"requestId":{"type":"string","format":"uuid"}}}}}},"UnauthorizedError":{"description":"UnauthorizedError","content":{"application/json":{"schema":{"type":"object","properties":{"httpCode":{"type":"number","enum":[401]},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"type":{"type":"string","enum":["unauthorized_error"]},"name":{"type":"string","enum":["MTAUnauthorizedError"]},"requestId":{"type":"string","format":"uuid"}}}}}},"ForbiddenError":{"description":"ForbiddenError","content":{"application/json":{"schema":{"type":"object","properties":{"httpCode":{"type":"number","enum":[403]},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"type":{"type":"string","enum":["forbidden_error"]},"name":{"type":"string","enum":["MTAForbiddenError"]},"requestId":{"type":"string","format":"uuid"},"reason":{}}}}}},"InternalServerError":{"description":"InternalServerError","content":{"application/json":{"schema":{"type":"object","properties":{"httpCode":{"type":"number","enum":[500]},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"type":{"type":"string","enum":["internal_server_error"]},"name":{"type":"string","enum":["MTAInternalServerError"]},"requestId":{"type":"string","format":"uuid"}}}}}}}},"paths":{"/send/validate-recipients":{"post":{"tags":["Send"],"summary":"Validate Recipients","operationId":"send_validate_recipients","responses":{"200":{"description":"Success","headers":{"RateLimit-Limit":{"description":"The maximum number of requests that the consumer is permitted to make per window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"The number of requests remaining in the current rate limit window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"The remaining window before the rate limit resets in milliseconds","schema":{"type":"integer"}},"Retry-After":{"description":"The number of seconds to wait before retrying the request","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"The maximum number of requests that the consumer is permitted to make per window","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"The number of requests remaining in the current rate limit window","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"The remaining window before the rate limit resets in milliseconds","schema":{"type":"integer"}},"X-Request-ID":{"description":"A unique identifier for the request","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidateRecipients.Response"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidateRecipients.Request"}}},"required":true}}}}} ``` ## Shorten Message > \# 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 \`20\` requests every \`NaN\` seconds ```json {"openapi":"3.0.0","info":{"title":"Mobile Text Alerts API","version":"8.0.0"},"servers":[{"url":"https://api.mobile-text-alerts.com/v3"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"apiKey"}},"schemas":{"ShortenMessage.Response":{"allOf":[{"$ref":"#/components/schemas/IApiResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"shortenedMessage":{"type":"string"}},"required":["shortenedMessage"]}},"required":["data"]}]},"IApiResponse":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"},"message":{"type":"string"},"data":{}},"required":[]},"ShortenMessage.Request":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}},"responses":{"BadRequestError":{"description":"BadRequestError","content":{"application/json":{"schema":{"type":"object","properties":{"httpCode":{"type":"number","enum":[400]},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"type":{"type":"string","enum":["bad_request_error"]},"name":{"type":"string","enum":["MTABadRequestError"]},"requestId":{"type":"string","format":"uuid"}}}}}},"UnauthorizedError":{"description":"UnauthorizedError","content":{"application/json":{"schema":{"type":"object","properties":{"httpCode":{"type":"number","enum":[401]},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"type":{"type":"string","enum":["unauthorized_error"]},"name":{"type":"string","enum":["MTAUnauthorizedError"]},"requestId":{"type":"string","format":"uuid"}}}}}},"ForbiddenError":{"description":"ForbiddenError","content":{"application/json":{"schema":{"type":"object","properties":{"httpCode":{"type":"number","enum":[403]},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"type":{"type":"string","enum":["forbidden_error"]},"name":{"type":"string","enum":["MTAForbiddenError"]},"requestId":{"type":"string","format":"uuid"},"reason":{}}}}}},"RateLimitError":{"description":"RateLimitError","content":{"application/json":{"schema":{"type":"object","properties":{"httpCode":{"type":"number","enum":[429]},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"type":{"type":"string","enum":["rate_limit_error"]},"name":{"type":"string","enum":["MTARateLimitError"]},"requestId":{"type":"string","format":"uuid"}}}}}},"InternalServerError":{"description":"InternalServerError","content":{"application/json":{"schema":{"type":"object","properties":{"httpCode":{"type":"number","enum":[500]},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"type":{"type":"string","enum":["internal_server_error"]},"name":{"type":"string","enum":["MTAInternalServerError"]},"requestId":{"type":"string","format":"uuid"}}}}}}}},"paths":{"/send/shorten-message":{"post":{"tags":["Send"],"summary":"Shorten Message","description":"# Rate Limiting\n\nThis 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 `20` requests every `NaN` seconds","operationId":"send_shorten_message","responses":{"200":{"description":"Success","headers":{"RateLimit-Limit":{"description":"The maximum number of requests that the consumer is permitted to make per window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"The number of requests remaining in the current rate limit window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"The remaining window before the rate limit resets in milliseconds","schema":{"type":"integer"}},"Retry-After":{"description":"The number of seconds to wait before retrying the request","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"The maximum number of requests that the consumer is permitted to make per window","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"The number of requests remaining in the current rate limit window","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"The remaining window before the rate limit resets in milliseconds","schema":{"type":"integer"}},"X-Request-ID":{"description":"A unique identifier for the request","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShortenMessage.Response"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"429":{"$ref":"#/components/responses/RateLimitError"},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShortenMessage.Request"}}},"required":true}}}}} ``` ## Get Message Cost > \# 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 ```json {"openapi":"3.0.0","info":{"title":"Mobile Text Alerts API","version":"8.0.0"},"servers":[{"url":"https://api.mobile-text-alerts.com/v3"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"apiKey"}},"schemas":{"GetCost.Response":{"allOf":[{"$ref":"#/components/schemas/IApiResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/IMessageCost"}},"required":["data"]}]},"IApiResponse":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"},"message":{"type":"string"},"data":{}},"required":[]},"IMessageCost":{"type":"object","properties":{"fee":{"type":"number"},"carrierFee":{"type":"number"},"totalCost":{"type":"number"},"messageCredits":{"type":"number"},"premiumCredits":{"type":"number"},"messageCount":{"type":"number"}},"required":["fee","carrierFee","totalCost","messageCredits","premiumCredits","messageCount"]},"GetCost.Request":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"},"message":{"type":"string"},"isMMS":{"type":"boolean"}},"required":["to"]}},"responses":{"BadRequestError":{"description":"BadRequestError","content":{"application/json":{"schema":{"type":"object","properties":{"httpCode":{"type":"number","enum":[400]},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"type":{"type":"string","enum":["bad_request_error"]},"name":{"type":"string","enum":["MTABadRequestError"]},"requestId":{"type":"string","format":"uuid"}}}}}},"UnauthorizedError":{"description":"UnauthorizedError","content":{"application/json":{"schema":{"type":"object","properties":{"httpCode":{"type":"number","enum":[401]},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"type":{"type":"string","enum":["unauthorized_error"]},"name":{"type":"string","enum":["MTAUnauthorizedError"]},"requestId":{"type":"string","format":"uuid"}}}}}},"ForbiddenError":{"description":"ForbiddenError","content":{"application/json":{"schema":{"type":"object","properties":{"httpCode":{"type":"number","enum":[403]},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"type":{"type":"string","enum":["forbidden_error"]},"name":{"type":"string","enum":["MTAForbiddenError"]},"requestId":{"type":"string","format":"uuid"},"reason":{}}}}}},"InternalServerError":{"description":"InternalServerError","content":{"application/json":{"schema":{"type":"object","properties":{"httpCode":{"type":"number","enum":[500]},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"type":{"type":"string","enum":["internal_server_error"]},"name":{"type":"string","enum":["MTAInternalServerError"]},"requestId":{"type":"string","format":"uuid"}}}}}}}},"paths":{"/send/cost":{"post":{"tags":["Send"],"summary":"Get Message Cost","operationId":"send_get_cost","responses":{"200":{"description":"Success","headers":{"RateLimit-Limit":{"description":"The maximum number of requests that the consumer is permitted to make per window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"The number of requests remaining in the current rate limit window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"The remaining window before the rate limit resets in milliseconds","schema":{"type":"integer"}},"Retry-After":{"description":"The number of seconds to wait before retrying the request","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"The maximum number of requests that the consumer is permitted to make per window","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"The number of requests remaining in the current rate limit window","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"The remaining window before the rate limit resets in milliseconds","schema":{"type":"integer"}},"X-Request-ID":{"description":"A unique identifier for the request","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetCost.Response"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetCost.Request"}}},"required":true},"description":"# Overview\n\n### Request Fields\n\n- `from: string`\n - The phone number used to send the message\n\n- `to: string`\n - The phone number the message is being sent to\n\n- `message: string`\n - The contents of the message being sent\n\n- `isMMS: boolean`\n - An indicator to that the message is an MMS instead of SMS.\n\n - Default behavior: False\n\n\n### Response Fields\n\n- `fee: number`\n\n - The fee for sending the message\n\n- `carrierFee: number`\n\n - The carrier fee for sending the message, when applicable\n\n- `totalCost: number`\n\n - The total cost for sending the message\n\n- `messageCredits: number`\n\n - The number of message credits used for sending the message\n\n- `premiumCredits: number`\n\n - The number of premium credits used for sending the message\n\n- `messageCount: number`\n\n - The number of messages that would be sent\n\n\n### Notes\n\n- The `message` field can be excluded or left blank to indicate that, when `isMMS` is true, that the message would be an attachment only.\n\n- The `isMMS` field can be excluded and will default to `false`.\n\n\nundefined"}}}} ``` ## POST /send/messaging-speeds > Get Message Delivery Time ```json {"openapi":"3.0.0","info":{"title":"Mobile Text Alerts API","version":"8.0.0"},"servers":[{"url":"https://api.mobile-text-alerts.com/v3"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"apiKey"}},"schemas":{"GetMessagingSpeeds.Response":{"allOf":[{"$ref":"#/components/schemas/IApiResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/IMessagingSpeeds"}},"required":["data"]}]},"IApiResponse":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"},"message":{"type":"string"},"data":{}},"required":[]},"IMessagingSpeeds":{"type":"object","properties":{"totalRecipients":{"type":"number"},"fromNumber":{"type":"number"},"longcodeStatus":{"$ref":"#/components/schemas/DedicatedNumberStatus"},"isLongcodeRegistered":{"type":"boolean"},"time":{"$ref":"#/components/schemas/IMessagingSpeedsTimeFormat"},"timeByCarrier":{"type":"array","items":{"type":"object","properties":{"carrier":{"type":"string"},"time":{"$ref":"#/components/schemas/IMessagingSpeedsTimeFormat"}},"required":["carrier","time"]}},"brandRegistration":{"$ref":"#/components/schemas/IMessagingSpeedsBrandRegistration"}},"required":["totalRecipients","fromNumber","longcodeStatus","isLongcodeRegistered","time","brandRegistration"]},"DedicatedNumberStatus":{"type":"string","enum":["Basic","Pending Carrier Approval","Carrier Approved","Undefined"]},"IMessagingSpeedsTimeFormat":{"type":"object","properties":{"hours":{"type":"number"},"minutes":{"type":"number"}},"required":["hours","minutes"]},"IMessagingSpeedsBrandRegistration":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/MessagingSpeedsBrandRegistrationStatus"},"estimatedApprovalDate":{"type":"string"}},"required":["status"]},"MessagingSpeedsBrandRegistrationStatus":{"type":"string","enum":["Pending","Approved","Not Submitted","Delayed"]},"GetMessagingSpeeds.Request":{"type":"object","properties":{"longcodeId":{"type":"number"},"groups":{"type":"array","items":{"type":"number"}},"subscriberIds":{"type":"array","items":{"type":"number"}},"allSubscribers":{"type":"boolean"},"excludedGroupIds":{"type":"array","items":{"type":"number"}},"isMMS":{"type":"boolean"},"linkClickDays":{"type":"number"}},"required":["longcodeId"]}},"responses":{"BadRequestError":{"description":"BadRequestError","content":{"application/json":{"schema":{"type":"object","properties":{"httpCode":{"type":"number","enum":[400]},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"type":{"type":"string","enum":["bad_request_error"]},"name":{"type":"string","enum":["MTABadRequestError"]},"requestId":{"type":"string","format":"uuid"}}}}}},"UnauthorizedError":{"description":"UnauthorizedError","content":{"application/json":{"schema":{"type":"object","properties":{"httpCode":{"type":"number","enum":[401]},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"type":{"type":"string","enum":["unauthorized_error"]},"name":{"type":"string","enum":["MTAUnauthorizedError"]},"requestId":{"type":"string","format":"uuid"}}}}}},"ForbiddenError":{"description":"ForbiddenError","content":{"application/json":{"schema":{"type":"object","properties":{"httpCode":{"type":"number","enum":[403]},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"type":{"type":"string","enum":["forbidden_error"]},"name":{"type":"string","enum":["MTAForbiddenError"]},"requestId":{"type":"string","format":"uuid"},"reason":{}}}}}},"InternalServerError":{"description":"InternalServerError","content":{"application/json":{"schema":{"type":"object","properties":{"httpCode":{"type":"number","enum":[500]},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"type":{"type":"string","enum":["internal_server_error"]},"name":{"type":"string","enum":["MTAInternalServerError"]},"requestId":{"type":"string","format":"uuid"}}}}}}}},"paths":{"/send/messaging-speeds":{"post":{"tags":["Send"],"summary":"Get Message Delivery Time","operationId":"send_get_messaging_speeds","responses":{"200":{"description":"Success","headers":{"RateLimit-Limit":{"description":"The maximum number of requests that the consumer is permitted to make per window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"The number of requests remaining in the current rate limit window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"The remaining window before the rate limit resets in milliseconds","schema":{"type":"integer"}},"Retry-After":{"description":"The number of seconds to wait before retrying the request","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"The maximum number of requests that the consumer is permitted to make per window","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"The number of requests remaining in the current rate limit window","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"The remaining window before the rate limit resets in milliseconds","schema":{"type":"integer"}},"X-Request-ID":{"description":"A unique identifier for the request","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetMessagingSpeeds.Response"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetMessagingSpeeds.Request"}}},"required":true}}}}} ```