# BlueReplies

> BlueReplies is a programmatic iMessage and FaceTime API. Send blue-bubble iMessages, receive replies, react with tapbacks, run group chats, place FaceTime calls, and automate workflows over a REST API with an official Node.js SDK, signed webhooks, and a free sandbox you activate from your own phone.

Base URL for all API requests: `https://blueapi-api-production.up.railway.app/v1` (HTTPS only). Authenticate with the `x-api-key` header. Sandbox keys are prefixed `sk_sandbox_` and production keys `sk_live_`; both use the same base URL and the prefix selects the mode.

## Getting started

- [Introduction](https://bluereplies.com/docs): Overview of the BlueReplies iMessage API and what you can build.
- [Quickstart](https://bluereplies.com/docs/quickstart): Send your first iMessage in about five minutes using the free sandbox.
- [Authentication](https://bluereplies.com/docs/authentication): API keys, the x-api-key header, and sandbox vs production key prefixes.
- [Sandbox](https://bluereplies.com/docs/sandbox): Free test environment activated by texting one code from your phone.
- [SDKs & libraries](https://bluereplies.com/docs/sdks): Official Node.js SDK (npm: blueapi) and using the REST API from any language.

## Core concepts

- [Phone numbers](https://bluereplies.com/docs/phone-numbers): E.164 formatting, lines, and how sender numbers are selected.
- [Idempotency](https://bluereplies.com/docs/idempotency): Use idempotency keys to safely retry requests without duplicating messages.
- [Errors](https://bluereplies.com/docs/errors): Error codes, HTTP status meanings, and when to retry.
- [Rate limits & warmup](https://bluereplies.com/docs/rate-limits): Apple's hidden iMessage caps and the line warmup curve.

## API reference

- [Messages](https://bluereplies.com/docs/messages): Send, edit, unsend, schedule, react, bulk send; effects, replies, attachments.
- [Conversations](https://bluereplies.com/docs/conversations): List conversations and fetch message history by participant.
- [Calls (FaceTime)](https://bluereplies.com/docs/calls): Place and end FaceTime audio/video calls and receive call events.
- [Contacts](https://bluereplies.com/docs/contacts): CRUD for saved contacts, tags, bulk upsert, and export.
- [Group chats](https://bluereplies.com/docs/groups): Create and manage group chats, members, names, icons, and messages.
- [Number lookup](https://bluereplies.com/docs/lookup): Check whether phone numbers are registered with iMessage.
- [Media uploads](https://bluereplies.com/docs/media): Upload images, videos, and voice notes for use as attachments.
- [Opt-outs](https://bluereplies.com/docs/opt-outs): Manage opt-out lists and STOP/START handling.
- [Lines](https://bluereplies.com/docs/lines): Inspect line health, ban status, and per-line usage.
- [Webhooks](https://bluereplies.com/docs/webhooks): 29 event types, HMAC-SHA256 signing, retries with backoff, and replay.

## Recipes

- [Examples gallery](https://bluereplies.com/docs/examples): Copy-paste recipes for common messaging automations.
- [One-time passcodes](https://bluereplies.com/docs/examples/otp): Deliver OTP / 2FA codes over iMessage.
- [Appointment reminders](https://bluereplies.com/docs/examples/appointment-reminders): Scheduled reminder sends with confirmation replies.
- [Drip campaigns](https://bluereplies.com/docs/examples/drip): Multi-step drip sequences with webhooks.

## API reference (machine-readable)

- [OpenAPI 3 specification](https://blueapi-api-production.up.railway.app/openapi.json): Complete machine-readable spec for every endpoint, parameter, and schema.
- [llms-full.txt](https://bluereplies.com/llms-full.txt): This index plus every API operation rendered inline as markdown, in a single file.

## Key endpoints

- `POST /v1/messages`: Send an iMessage (supports effects, replies, attachments, scheduling).
- `GET /v1/messages`: List or full-text search messages.
- `PUT /v1/messages/:id`: Edit a sent message within Apple's 15-minute window.
- `POST /v1/messages/:id/unsend`: Unsend a message within Apple's 2-minute window.
- `POST /v1/messages/react`: Send a tapback reaction to a message.
- `POST /v1/messages/bulk`: Send up to 100 messages in one request.
- `GET /v1/conversations`: List conversations grouped by participant.
- `POST /v1/lookup`: Check iMessage registration for phone numbers.
- `POST /v1/calls`: Initiate a FaceTime call.
- `POST /v1/groups`: Create a group chat.
- `GET /v1/contacts`: List contacts, optionally filtered by tag.
- `POST /v1/webhooks`: Register a webhook endpoint for event delivery.