> For the complete documentation index, see [llms.txt](https://developers.mobile-text-alerts.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.mobile-text-alerts.com/tutorials/message-sending/send-an-imessage/send-imessages.md).

# Send iMessages

Learn how to send iMessages via the API

Once your subscribers [opt in to receive iMessages](/tutorials/message-sending/send-an-imessage/subscriber-opt-in.md), you can send iMessages to them. Mobile Text Alerts will automatically capture and record inbound opt-in messages and flag your subscribers as iMessage-enabled and opted in. Remember, opt-ins are tied to a specific [Sender Identity](/tutorials/message-sending/send-an-imessage/sender-identity.md), so you must receive inbound consent from a subscriber on each Sender Identity you plan to use.

## Send iMessages via the API

When sending iMessages via the API, you need to specify a Sender Identity, and Mobile Text Alerts will handle routing messages intelligently based on current subscriber status. For the subscribers included in a <mark style="color:blue;">`/send`</mark> call, the system will verify whether they are iMessage-enabled and then route messages through your Sender Identity. A graceful [fallback to SMS](#sms-fallback) is also supported.

After completing the necessary configuration and setup steps, you should have a Sender Identity attached to one of your existing outbound longcodes used for SMS/MMS. This structure requires minimal changes to start using the iMessage route and provides flexibility to manage Sender Identities the same way you manage longcodes.

### Specify a Sender Identity with `senderName`

When calling the <mark style="color:blue;">`/send`</mark> endpoint, include `senderName` in the request to directly specify the sender name to use, without needing to include a `longcodeId`.

A Sender Identity must be indicated with either `senderName` or `longcodeId`.

### Specify a Sender Identity with `longcodeId`

When calling the <mark style="color:blue;">`/send`</mark> endpoint, you can also include `longcodeId` in the request. It will be used as a fallback to `senderName`. When a longcode has an associated iMessage Sender Identity, Mobile Text Alerts will use that identity for iMessage-enabled recipients.

### Create a request to the `/send` endpoint with the Sender Identity

See [Send a Message](/getting-started/send-a-message.md) to learn more about making a <mark style="color:blue;">`/send`</mark> call to the API.

## Webhooks

When sending messages via the iMessage route, you will receive webhooks from Mobile Text Alerts just as you would for other messaging routes (such as SMS). For messages routed via iMessage, you will receive [`delivery-status`](/getting-started/setting-up-webhooks.md#delivery-status-delivery-status) callbacks as the message status changes during the sending process.

For webhook calls for iMessage [`message-send`](/tutorials/webhooks.md#message-send) or [`message-reply`](/tutorials/webhooks.md#message-reply) events, the payloads will include the `senderName` field to identify the sender "in-scope" with sending that message when sent via iMessage. For message replies, this is the `senderName` that the inbound reply was sent to.

When inbound messages are sent to your Sender Identities, Mobile Text Alerts will deliver [`message-reply`](/getting-started/setting-up-webhooks.md#message-reply-message-reply) webhooks consistent with inbound SMS messages.

[Click here](/getting-started/setting-up-webhooks.md) for more information on configuring webhooks for your account.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developers.mobile-text-alerts.com/tutorials/message-sending/send-an-imessage/send-imessages.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.