> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blujay.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Blujay API

> Send and receive iMessage, RCS and SMS from your Blujay phone numbers.

The Blujay API lets your product message people from your Blujay phone numbers. Blujay picks the best service for each recipient (iMessage, RCS or SMS), tracks each message as far as that service reports (delivery and reads for iMessage and RCS; SMS stops at `sent`), and tells your server what happened through signed webhooks.

> **[Quickstart](/quickstart.md)**
>
> Send your first message in about five minutes.

> **[API reference](/api-reference/introduction.md)**
>
> Every endpoint, with a playground you can call from the browser.

> **[Webhooks](/webhooks/overview.md)**
>
> Get replies, delivery updates and more pushed to your server.

> **[Errors](/errors.md)**
>
> Every error code, what it means and how to fix it.

## Send a message in one request

```bash theme={null}
curl https://api.blujay.io/v1/chats \
  -H "Authorization: Bearer $BLUJAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-welcome" \
  -d '{
    "from": "+15555550100",
    "to": ["+15555550123"],
    "message": { "parts": [{ "type": "text", "text": "Hi! Thanks for reaching out." }] }
  }'
```

Blujay answers `202 Accepted` and sends it as iMessage, RCS or SMS. The [Quickstart](/quickstart.md) walks you through the full setup in about five minutes. Words like [phone number](/glossary.md), chat, contact and recipient are defined in the [Glossary](/glossary.md).

> [!TIP]
>
> **Building with AI?** Give your assistant [every page in one file](https://docs.blujay.io/llms-full.txt), connect it to the [docs MCP server](/build-with-ai.md#give-your-assistant-the-whole-docs), or start from the prompts in [Build with AI](/build-with-ai.md).

## What you need

* **A Blujay workspace.** [Sign up free](https://app.blujay.io/?auth=register) if you don't have one. Blujay has three plans: Free Plan, Dedicated and AI Agent. Each one changes who your numbers can message. See [Plans](/plans.md).
* **Workspace owner or admin access.** Only workspace owners and admins see the **API** tab, where your API key lives.
* **US recipients.** Blujay sends to US phone numbers only.
* **An HTTPS address on your server**, if you want replies and delivery updates sent to you as they happen.

## Common uses

* **Instant replies** to new inquiries, so no one waits for a callback.
* **Follow-ups and check-ins** with people you're already talking to.
* **Appointment confirmations and reminders**, with replies that come straight back to you.
* **Two-way customer support** over text.
* **AI assistants that text**, answering questions and handing off to a person.
* **Texts kept in sync with your CRM** or internal tools.

Blujay is built for conversations. For one-way bulk alerts or one-time passcodes, use a dedicated SMS provider.

## What the API does

| Area | What the API does |
| - | - |
| [Messaging](/messaging/send-messages.md) | Start chats, send text, links, photos, videos, files and contact cards, and read the full history. The [sending rules](/messaging/sending-rules.md) say what a message can contain before the contact replies. |
| [Service choice](/messaging/choosing-a-service.md) | Check whether a number can get iMessage, RCS or SMS before you send, or let Blujay choose. |
| [Group chats](/messaging/group-chats.md) | Create iMessage groups, add and remove participants, rename the group. |
| iMessage features | [Threaded replies](/messaging/replies.md), [screen and bubble effects and text styles](/messaging/effects.md), [edit and unsend](/messaging/edit-and-unsend.md), [typing indicators and read receipts](/messaging/typing-and-read-receipts.md). |
| [Contacts](/contacts.md) | Create, update, tag and assign contacts, and manage opt-outs. |
| [Workflows](/workflows.md) | Enroll contacts in your Blujay workflows from your own systems. |
| [Webhooks](/webhooks/overview.md) | Receive 18 event types, signed with the Standard Webhooks scheme and pinned to a payload version. |

## Built to be safe to retry

* **Idempotent sends.** Send an `Idempotency-Key` and a retried request never sends twice. See [Idempotency](/idempotency.md).
* **Stable errors.** Every error has a stable `code`, a `retryable` flag and a [page that explains the fix](/errors.md).
* **Traceable.** Every response carries a trace ID in the `X-Trace-ID` header (and as `trace_id` in JSON bodies). Include it when you contact support.
* **Honest status.** A `202 Accepted` means queued, not delivered. Delivery, read and failure arrive as [webhooks](/webhooks/events.md) or on the message itself. See [Track a message](/messaging/lifecycle.md).

## Base URL

```text theme={null}
https://api.blujay.io/v1
```

All requests use HTTPS and JSON. Authenticate with your workspace [API key](/authentication.md).

> [!NOTE]
>
> Every API call acts on your real workspace. There is no separate test mode, so messages you send through the API are delivered. Test with your own phone number first.

## Questions?

Email [support@blujay.io](mailto:support@blujay.io). Include the `trace_id` from any response you're asking about. See [Support](/support.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.