Skip to main content

​
Getting started

No. Every call acts on your real workspace and messages are delivered. Test by sending to your own phone. See Test and live.
Workspace owners and admins find the key under API in the Blujay sidebar. A workspace has one key today. To rotate it, or if it leaks, email support@blujay.io. See Authentication.
Free Plan: a shared number that can message up to 10 verified contacts, people who texted it first and were verified in the app; no group chats. Dedicated: your own number with full functionality. AI Agent: your own number that only replies to people who text it first, with no group chats. See Plans.
Yes. Messages you send through the API appear in your team’s inbox in Blujay like any other text, and replies land in the same chat. They also appear in CRMs you’ve connected to Blujay.
Email support@blujay.io with the trace_id from the response. See Debugging and Support.

​
Sending

You don’t have to. Leave out preferred_service (Auto) and Blujay uses iMessage when the person can receive it, and RCS or SMS when they can’t. You can also check first or require a service. See iMessage, RCS or SMS.
Until a contact replies to your number, Blujay rejects a link, photo, file or contact card, and any text over 300 characters, with a 400. At most 6 texts go out in a row without a response. These errors are never retryable: wait for the reply. See Sending rules.
A text or a reaction (such as a tapback) from the contact, or a message from them in a group chat. Calls don’t count. Links, attachments and longer texts unlock once the contact replies to that specific number.
Send an Idempotency-Key header and reuse it on retries. See Idempotency.
Yes, from a Dedicated number. Send to two or more phone numbers to start a group chat. In iMessage groups you can add and remove participants and rename the group. See Group chats.
Yes, for text-only iMessages your workspace sent: edit within 15 minutes, unsend within 2 minutes. See Edit and unsend.
Typing is best effort and shows only in iMessage chats. SMS and RCS chats, and chats whose service isn’t confirmed yet, accept the request and show nothing. Check the chat’s supports_typing_indicators first. See Typing and read receipts.
Use a dedicated SMS provider for passcodes. Blujay is built for two-way conversations: texts to people who haven’t replied are limited, which doesn’t suit codes sent to someone who may never answer.
On a Dedicated number, Blujay opts the contact out automatically when they text exactly STOP and nothing else. For any other wording, or on other plans, opt them out with the API. Either way Blujay then refuses sends to them with RECIPIENT_SUPPRESSED. There is no webhook for opt-outs yet; read opted_out on the contact. See Opt-outs.

​
Replies and webhooks

Subscribe a webhook to message.received. See Webhooks and Receive messages.
For iMessage, yes: you get delivered, and read when the person has read receipts on. RCS reports them when the carrier does. SMS stops at sent, because carriers don’t report delivery reliably. See Track a message.
No. Delivery is at least once, so an event can arrive more than once, for example after a retry. Store each event_id you’ve handled and skip repeats. See Delivery and retries.
Blujay retries each event 10 times over about 25 minutes. After that, list the missed deliveries and replay them. See Delivery and retries.

​
Numbers and limits

A Dedicated number can message up to 50 new contacts a day once established (a new number starts lower and ramps up over about its first month), has room for 1,500 pending messages in its queue, and sends at most 30 messages a minute to the same person. At most 6 texts go to anyone in a row without a response. There’s no hourly limit on texts. The live values are on each number in GET /v1/phone-numbers. API requests are limited to 600 reads, 120 writes and 60 attachment requests a minute. See Phone numbers and limits and Rate limits.
You get a phone_number.status_updated webhook for the old number and one for the new number. Switch your sends to the new number’s phone_number_id.
Start fewer new conversations from it, focus on people who reply, and answer quickly. A critical number should stop starting new conversations; contact support@blujay.io. See Number health.

​
Tools and AI

Not yet. Every example uses plain HTTP. There’s a ready-made Postman collection, and the OpenAPI file works with code generators.
Yes. Give it every page in one file, connect it to the docs MCP server, or use the Copy page menu on any page. See Build with AI.

​
Next steps

Glossary

Every term the docs use.

Support

How to get help.