> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.messageblue.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.messageblue.ai/_mcp/server.

# MessageBlue

MessageBlue puts a real iMessage number behind an API. Your server sends a request, a blue-bubble message arrives on someone's iPhone, and their reply comes back to you as a webhook. Optionally, an AI agent you configure answers on your behalf.

## Start here

#### [Core concepts](/concepts)

Apps, numbers, the Mac agent, conversations and webhooks — the ideas the rest of the docs assume.

#### [The dashboard](/overview)

A screen-by-screen guide to app.messageblue.ai, where you configure everything.

#### [API reference](/api-reference)

Every endpoint on the messaging gateway, generated from the live spec.

## What makes it different

#### Real iMessage

Blue bubbles, delivery and read receipts, reactions, attachments and group threads — not an SMS gateway pretending.

#### SMS fallback

When a recipient cannot receive iMessage, delivery falls back to SMS and the status event tells you it happened.

#### An agent, if you want one

Point it at your menu, price list or FAQ and it answers from them. Multi-step tasks and connected business apps are opt-in.

## The shape of an integration

#### Create an app and get credentials

Sign in at [app.messageblue.ai](https://app.messageblue.ai) and create your app. You receive an **Account ID**, an **App ID** and an **App Secret** — the secret is shown only once.

See [creating your app](/create-an-app).

#### Attach a number

Either pair an iMessage-capable Mac you already own, or request a number and the team provisions one. Nothing sends or receives until an app has a number.

#### Send a message

Sign your request with the App Secret and send it to the gateway at `api.messageblue.ai`. The [API reference](/api-reference) documents every endpoint, and the [API Console](https://api.messageblue.ai/docs) will sign and run a real request for you.

#### Receive replies

Set an inbound webhook URL in [Settings](/settings#webhooks). Incoming messages and delivery statuses are POSTed to your server, signed with `X-MB-Signature` so you can verify they came from MessageBlue.

> **Note**
>
> Everything above except sending is also doable without writing code — you can run an entire MessageBlue deployment from the [Messages inbox](/messages) and an [AI agent](/ai-agent-studio). To wire iMessage into tools you already use, the [Zapier integration](/zapier-messageblue-integration) connects MessageBlue to 7,000+ apps with no code at all.

## Where things live

| Host                  | What it is                                                                                                        |
| --------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `app.messageblue.ai`  | The web app — configuration, inbox, agent studio, analytics                                                       |
| `api.messageblue.ai`  | The messaging gateway — the API your server calls, and the [interactive console](https://api.messageblue.ai/docs) |
| `docs.messageblue.ai` | These docs                                                                                                        |