Introduction
Send and receive iMessage from your own code — one HTTP API, one event stream.
Mapier gives your application a real iMessage presence. You send messages, react to them, manage group chats and receive everything people send back — over plain HTTP, from any language.
There is no SDK to install. Every example in these docs is a curl command or
a fetch call you can run right now.
curl $MAPIER_BASE_URL/v1/commands/message.send \
-H "Authorization: Bearer $MAPIER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"target": { "kind": "recipient", "recipientExternalId": "+14155550100" },
"payload": { "text": "Your table is ready." }
}'How it works
The API has two halves, and understanding the split makes everything else straightforward.
You send commands. Every action — sending a message, adding a reaction,
renaming a group — is a POST to one endpoint with a target (who) and a
payload (what). The response is 202 Accepted, meaning the command was
durably queued.
You read results from one stream. A single server-sent events connection tells you how each command settled and delivers every inbound message. This is the only way to learn whether something actually reached its recipient, which is why the quickstart has you open the stream before sending anything.
A 202 means queued, not delivered. That one sentence explains most of the surprises in this API
— keep the stream open and you will not be surprised by any of them.
What you can build
- Support and sales conversations that live where customers already are, with a human or an agent on your side of the thread.
- Transactional notifications — order updates, appointment reminders, delivery windows — as a real conversation rather than a no-reply channel.
- Group coordination: create a chat, add participants, rename it as the work changes.
- Interactive prompts using reactions, threaded replies and polls.
Start here
Send your first message
A working request and a settlement you can watch arrive, in about five minutes.
Core concepts
Targets, commands, settlements, capabilities — the vocabulary the rest of the docs assumes.
API reference
Every endpoint, every field, every error code.
The response stream
How to consume events, and what the stream does not guarantee.
What the API does today
Being straight about the edges saves you finding them the hard way.
| Area | Status |
|---|---|
| Sending text, rich text, links and polls | Available |
| Reactions, in direct messages and groups | Available |
| Creating groups, renaming, adding participants | Available |
| Receiving messages and downloading attachments | Available |
| Sending attachments and stickers | Not yet — no upload endpoint |
| Removing a participant, leaving a group | Not working on current macOS hosts |
| Webhooks | Not available — the event stream is the only push channel |
| Reading message history | Not available |
Conventions in these docs
Phone numbers are E.164 (+14155550100) and email addresses are lowercase.
Examples use the reserved +1415555xxxx range, so nothing here can dial a real
person. Where a detail is not yet settled, you will see a callout saying so
rather than a confident guess.