Blujay API

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

Send your first message in about five minutes.

API reference

Every endpoint, with a playground you can call from the browser.

Webhooks

Get replies, delivery updates and more pushed to your server.

Errors

Every error code, what it means and how to fix it.

Send a message in one request

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 walks you through the full setup in about five minutes. Words like phone number, chat, contact and recipient are defined in the Glossary.

Building with AI? Give your assistant every page in one file, connect it to the docs MCP server, or start from the prompts in Build with AI.

What you need

A Blujay workspace. Sign up free 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.
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	Start chats, send text, links, photos, videos, files and contact cards, and read the full history. The sending rules say what a message can contain before the contact replies.
Service choice	Check whether a number can get iMessage, RCS or SMS before you send, or let Blujay choose.
Group chats	Create iMessage groups, add and remove participants, rename the group.
iMessage features	Threaded replies, screen and bubble effects and text styles, edit and unsend, typing indicators and read receipts.
Contacts	Create, update, tag and assign contacts, and manage opt-outs.
Workflows	Enroll contacts in your Blujay workflows from your own systems.
Webhooks	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.
Stable errors. Every error has a stable code, a retryable flag and a page that explains the fix.
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 or on the message itself. See Track a message.

Base URL

https://api.blujay.io/v1

All requests use HTTPS and JSON. Authenticate with your workspace API key.

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. Include the trace_id from any response you’re asking about. See Support.

Get started

Messaging

Contacts

Webhooks

Build reliably

Resources

Quickstart

API reference

Webhooks

Errors

Send a message in one request

What you need

Common uses

What the API does

Built to be safe to retry

Base URL

Questions?

Quickstart

API reference

Webhooks

Errors

​Send a message in one request

​What you need

​Common uses

​What the API does

​Built to be safe to retry

​Base URL

​Questions?

Send a message in one request

What you need

Common uses

What the API does

Built to be safe to retry

Base URL

Questions?