Project Blue API

Working with an AI assistant? Connect it here first — this is the fastest way to send a message, and there is no API key to paste.

The Project Blue MCP server gives Claude Desktop, Claude Code, Cursor, and any other MCP-compatible client the ability to send iMessage and SMS, place FaceTime Audio calls, manage contacts, run Workflows, and read message and call history — directly from the editor or chat surface. Authentication is OAuth 2.1 in the browser.

Writing code against the REST API instead? Start with the Quickstart.

Two ways to connect

Add the server directly. This is the standard path and works in any MCP client — paste the URL, or run the one-liner in the rail. Nothing else is installed.

Or install the plugin (Claude Code only). It registers the same server and adds a Project Blue skill carrying the workflow rules the tool descriptions cannot: the trial verification sequence, when a retry is being deduplicated rather than failing, the FaceTime call lifecycle, and which contact endpoint merges versus replaces.

Set up your client

Pick your client in the rail and run the snippet. Every one of them ends the same way: your client opens a browser to app.tryprojectblue.com, you approve the connection, and it is done. OAuth 2.1 with dynamic client registration — no key to paste, no tokens to rotate.

Any other client that speaks remote MCP over streamable HTTP works with the server URL alone. For one that only accepts stdio servers, use mcp-remote as an adapter — both are in the rail.

Available tools

Four steps from an API key to a delivered message. Every call here is copy-paste ready.

1. Get a key, then check it

Create a key in the Project Blue dashboard under Settings → API Keys. Keys start with proj_ followed by 64 hex characters, and you may hold five active keys at a time.

Start with /get-lines. It is the right first call because it reads rather than sends, and because its answer tells you which of the two setups you are in.

The two 401 bodies mean different things. Missing or invalid Authorization header means the header was absent or lacked the Bearer prefix — the request never carried a key. Invalid API key means the header was well-formed but the key is wrong, revoked, or from another account.

2. Get a number you can text

On a paid account, skip this — any valid number works.

On a trial, sends route through a shared Project Blue line and can only reach verified destinations. Verification is confirmed by an inbound text: the owner of that number must text the shared line from their own phone. Nothing in the API or the dashboard can confirm it on their behalf.

Sending to an unverified destination returns 403 with Trial accounts can only message numbers verified on the shared line. See Trial accounts for what else is restricted.

3. Send the message

Two fields is the whole request. If the recipient has iMessage it arrives as one; otherwise it falls back to SMS automatically.

A success returns status: "done" — but no message id, which is why there is a step 4.

4. Confirm it landed

The send response tells you the message was accepted, not that it was delivered. Read it back from list messages filtered to the number you texted, and check data[0].status. The same row carries the message_handle you need for get a message.

In production, register a webhook instead of polling.

1. Re-running the same send is collapsed, not repeated. Identical text to the same number within the hour returns 200 with deduped: true and sends nothing. Change the text or pass a distinct idempotencyKey. This is the most common reason a first integration looks like it worked but nothing arrived.
2. 60 requests per minute per key, then 429 with retryAfterSeconds.
3. Numbers are normalized to E.164. Most formats are accepted on the way in; everything comes back as +15551234567.
4. Trial sends are real messages on a line shared with other accounts. Do not load-test them — unverified probing burns iMessage reputation for everyone on that line.

All API requests require a bearer token in the Authorization header. You can generate API keys from within your Project Blue dashboard under Settings → API Keys.

Trial accounts (accounts still on a trial, before conversion to a paid line) get real API access — not a simulator. Sends are real messages. The difference is that a trial account sends through a shared Project Blue line, and it can only reach destinations that have been verified.

Verifying a destination

1. Register the destination in the Project Blue webapp under Settings. This creates a pending verification pinned to your shared line.
2. The owner of that destination texts the shared line from their own phone. That inbound text is what confirms the verification. There is no way to confirm it from the API or the dashboard.
3. The destination shows as verified in the webapp, and API sends to it start succeeding.

Destination registration is webapp-only today — there is no API-key equivalent for registering a number or polling verification status yet.

Sending or probing an unverified destination returns 403 with Trial accounts can only message numbers verified on the shared line.

Endpoint availability

GET /get-lines on a trial account

Trial accounts do not own a device line. /get-lines returns a trial envelope instead of an array of lines.

Send a message to a phone number via iMessage or SMS. If the recipient has iMessage, the message is delivered as an iMessage (blue bubble). Otherwise, it falls back to SMS automatically.

The phone parameter is flexible — we accept formats like (555) 123-4567, 555.123.4567, +15551234567, and more. All numbers are normalized to E.164 format before sending.

When lineId is provided, we route through that line. If it is omitted, message sends continue to use default load balancing across your available lines.

A replay returns status: "done" when the original send finished, or status: "processing" with messageType and devicePhoneNumber still null while it is in flight. Both carry deduped: true; a first-time send never does.

List the iMessage send effects accepted by effect on /send-api-message. Each entry has a name, type (bubble or screen), and a short description.

Bubble effects: slam, loud, gentle, invisible-ink. Screen effects: confetti, balloons, hearts, lasers, fireworks, echo, spotlight, shooting-star, celebration. Not available on trial accounts.

Send an iMessage or SMS to a group of 2 to 32 recipients. There is no create step — pass numbers every time. The same participant set resolves to the same thread.

groupStatus is "creating" until the chat exists on the sending line, then "active". created is true only when this call created the group. groupId is opaque and stable — do not parse it.

On a replayed or deduplicated request, groupId and devicePhoneNumber can be null, because the group did not exist yet when the claim was taken.

Group send is unavailable on trial accounts — see Trial accounts.

200

Message queued successfully

400

Invalid request — missing message/attachment, both attachments, recipient count, email/chat handles, phone format, or lineId

401

Missing or invalid Authorization header / Invalid API key

403

Unavailable on trial (see Trial accounts) — e.g. Trial accounts cannot create group chats. Also: One or more recipients are blocked.

409

This group already exists on a different line.

429

Rate limit exceeded

500

Internal server error

Show the iMessage typing indicator (the three dots) to a recipient. Authenticate with a Bearer API key, same as every other endpoint.

The indicator auto-clears on the recipient's device after a short period or when a message arrives. The intended pattern is send-typing-indicator → wait about 2–4 seconds → send-api-message.

On success the endpoint returns HTTP 200 with { status: "SENT" | "ERROR", number, error_message } — error_message is null when status is SENT. Auth and request-validation failures still use standard 4xx bodies with an error field. Treat device-level failures (status: "ERROR") as fire-and-forget — do not retry.

React to a specific message with one of the six standard iMessage tapbacks. Pass the message_handle from /get-messages-api or /get-message-api as messageHandle.

Valid reaction values: love, like, dislike, laugh, emphasize, question. Set remove to true to retract a previous reaction of the same type. A typical pattern is acknowledging an inbound message with like or love instead of (or before) a text reply.

On success the endpoint returns HTTP 200 with { status: "SENT" | "ERROR", messageHandle, reaction, remove, error_message }. Auth and request-validation failures still use standard 4xx bodies with an error field.

The send endpoint works hand-in-hand with your CRM. If you have HighLevel or HubSpot connected, outbound messages sent through the API appear inside your CRM — just like messages sent from the Project Blue app.

Auto-create contacts

By default, shouldAutoCreateContact is true. This means if you send an outbound message and the recipient does not already exist as a contact in your CRM, we will automatically create the contact for you along with the message.

Set shouldAutoCreateContact to false if you only want messages logged for contacts that already exist in your CRM.

HighLevel

Outbound messages are synced directly into Conversations. If the contact doesn't exist and auto-create is enabled, we create the contact and the message appears in their conversation thread.

HubSpot

Outbound messages are logged as an activity on the contact record. If you have a HubSpot Inbox enabled, the message is also delivered there for your team to see and reply from.

If the contact doesn't exist and auto-create is enabled, we create the contact in HubSpot first, then log the activity.

Returns a paginated list of the authenticated user's messages — outbound and inbound merged into a single feed. Each message includes a durable message_handle that can be passed to /get-message-api/:message_handle for the full record.

Fetch a single message by its opaque message_handle (as returned from /get-messages-api). Handles are scoped to the authenticated user — a handle from another user's account returns 404.

Check whether a phone number is reachable via iMessage before sending. Useful for routing logic or pre-qualifying contacts.

200

Phone checked successfully

400

Invalid phone number format

401

Missing or invalid API key

403

Trial account probing a destination that is not verified on the shared line

409

Trial account has no shared line provisioned

429

Rate limit exceeded

500

Internal server error

Fetch all sending lines available to your account. Pass the returned lineId value to /send-api-message when you want to force a specific line.

External contacts are Project Blue's native contact store for accounts without a connected CRM. They render in the Project Blue app's contact list and details panel.

You can create them explicitly with the endpoints below, or implicitly by passing firstName, lastName, email, and customFields on /send-api-message — those fields persist on the auto-created contact for the recipient.

Required: phone only (plus Authorization: Bearer <api key>). Optional: firstName, lastName, email, customFields.

customFields is a JSON object of key/value pairs, max 10,000 characters when stringified. Omit it entirely if you have none. Same phone for the same API key is an upsert (fills blank names, overwrites email, shallow-merges customFields).

All three endpoints return the same object. Create and update return it as { contact }; list returns { contacts, pagination }. There is no status envelope.

Returns the authenticated user's external contacts, newest first, with pagination. Pass phone to look up a single contact by number.

Updates an existing contact's name, email, note, or custom metadata. The contact's phone number cannot be changed. Returns 404 if the contact does not belong to your account.

At least one of firstName, lastName, email, customFields, or note must be present. A request carrying only contactId returns 400. The phone number cannot be changed.

Workflows are automation flows built in the Project Blue app — send a message, wait, branch on a reply, and so on. These endpoints list your published flows, enroll a contact (which starts the run immediately), and cancel active runs for a contact.

Returns the authenticated user's published Workflows. Use each flow's id as flowId when enrolling a contact. Ids are opaque UUID strings, not sequential numbers — pass them back verbatim.

Starts a Workflow run for the given contact. The first step executes immediately. The response includes runId and the pb_line_id pinned to the run.

Because the first step runs before the response is written, the returned status is the state after that step. A run that begins with a wait comes back SLEEPING, and one that begins by asking a question comes back WAITING_REPLY — ACTIVE is the exception, not the rule. Statuses are uppercase: ACTIVE, SLEEPING, WAITING_REPLY, COMPLETED, CANCELLED, FAILED.

400

Invalid phone number, invalid pb_line_id, or no available lines

403

Contact has opted out

404

Flow not found or not published, or line not found

409

An active run already exists for this contact in this flow

Cancels all active Workflow runs for the given contact. Safe to call when the contact has no active runs. POST is accepted as an alias for clients that cannot send DELETE with a body.

Returns the authenticated user's outbound call logs from the Project Blue dialer, including a recording_url when a recording is available. This is the call-log analog of /get-messages-api.

Dispositions

After a recording is transcribed, the transcript is run through an AI classifier that assigns one of the following dispositions. Use this for routing, follow-up automation, or analytics. The disposition can be null on calls that haven't been classified yet.

200

Call logs returned

400

Invalid query parameter (limit/offset/call_log_timestamp/dates/pb_line_id)

401

Missing or invalid API key

429

Rate limit exceeded

500

Internal server error

Initiate real FaceTime Audio calls programmatically and connect to the live call audio via WebRTC using Agora's SDK. The pb_line_id must be a FaceTime-enabled line on your account.

Joining the call

The returned agora credentials are used with the Agora Voice SDK to stream audio to and from the FaceTime call. Tokens are time-limited, so join the channel promptly after starting the call.

Status is driven by call lifecycle events. Poll this endpoint to track ringing → answered → ended.

200

Call started / status returned

400

Invalid pb_line_id or phone_number

401

Missing or invalid API key

403

FACETIME_NOT_ENABLED — FaceTime Audio not enabled on this account

404

Call not found (status/end endpoints)

429

Rate limit exceeded or daily FaceTime dial limit reached

502

Device error placing the call

500

Internal server error

Place and receive calls on your Project Blue lines from your own web app with @tryprojectblue/dialer. Your API key stays on your server; the browser holds only a short-lived token scoped to one line.

FaceTime Audio is a separate, native API — see FaceTime Audio. This section covers regular phone calls through the Project Blue dialer. Phone numbers and caller ID are managed by Project Blue; you never touch a carrier account.

How it works

1. Your server calls the token mint with your API key and a lineId, and forwards the response to the browser.
2. The SDK takes a tokenProvider that calls your server. It handles refresh, the call lifecycle, inbound registration, and your plan's daily minute allowance.
3. Your UI calls dialer.call(number) and listens to events on the returned call.

Before you start

The Settings → API Keys page in the dashboard shows these same steps with your account's status filled in, so it is the fastest way to see which prerequisite is missing.

Exchange your API key for a 15-minute voice token pinned to one line. Call this from your server whenever the SDK's tokenProvider asks, and return the body to the browser as-is.

Authorization: Bearer YOUR_API_KEY and Content-Type: application/json. The same key you use against api.tryprojectblue.com.

Forward it unchanged

Return the upstream status, body, and Retry-After header to the browser exactly as received. The SDK reads expiresAt, maxCallsPerToken, inboundEnabled, and allowance to schedule its own refreshes and to raise typed errors. If you reshape the body, refresh timing and error handling degrade to defaults.

Guard the .json() call. A proxy in front of the app can return a non-JSON 502 or 503, and an unhandled throw in your route becomes a generic 500 in the browser instead of a retryable token_unavailable.

Refusals

Every non-2xx body is { error, code }, plus extra fields on the cap and rate-limit cases. Unlike the messaging API, code is always present here, and the SDK maps it to a DialerError code for you.

200

Token minted

400

invalid_line_id

401

invalid_api_key

402

dialer_cap_reached or account_paywalled

403

dialer_subscription_required, line_inbound_only, line_not_eligible, api_key_unsupported

404

line_not_found or dialer_not_provisioned

429

rate_limited — read retryAfterSeconds

500

dialer_misconfigured or internal_error

503

dialer_unavailable — retry with backoff

ProjectBlueDialer is one calling session for one line. Create it with a tokenProvider, call start(), and keep it alive for as long as the user can place or receive calls.

Writing the tokenProvider

It runs whenever the SDK needs a token: at start(), about a minute before the current token expires, and before a token has been used for its tenth call. It must call your server, never the mint directly.

Return the mint body unchanged. To report a refusal, throw mintErrorFromResponse(res.status, body) — it returns null on a 2xx and the matching typed error otherwise, so the three-line pattern in the rail is the whole thing. If you would rather return the error body, add status to it first; without it the SDK reports 402 for a cap refusal and 400 for everything else.

Methods

Events

Subscribe with dialer.on(event, handler); off and once work the same way.

Token refresh, in detail

You never manage tokens directly, but knowing the schedule explains what your server will see. The session refreshes 60 seconds before expiry by default, immediately before the call that would exceed maxCallsPerToken, and whenever the voice service reports the token invalid. A failed refresh emits tokenRefreshFailed and retries after 5, 15, then 45 seconds; the current token keeps working until it expires.

A cap_reached refusal is different: the session emits capReached, stops retrying, and wakes itself one second after periodEnd. A call that is already up is never cut off — caps apply at mint time only.

A DialerCall is one call. Outbound calls come back from dialer.call(); inbound calls arrive on the session's incoming event and must be accepted or rejected.

Events

Exactly one of disconnected, cancelled, or rejected fires when a call ends, and never more than once. Clear your UI on all three.

Inbound calls

A session receives calls only while its token was minted with inboundEnabled: true. That requires the line to have an inbound number and at least one person in your workspace in its ring set; the SDK then rings alongside them, never instead of them. A line with nobody in its ring set still answers "no one is available", SDK or not.

Because inboundEnabled is evaluated at every mint, it can change mid-session. Read the value from each ready event rather than caching it at start, and show an inbound UI only when it is true.

Every rejection from the SDK is a DialerError with a stable code, the HTTP status of the mint response when there was one, and the original cause. Two subclasses carry extra fields.

The mapping from the mint's server codes to these is in Mint a token. Branch on code or use instanceof for the two subclasses; do not match on message, which is written for end users and may change.

Plans, caps and minutes

Every call is metered against your Dialer plan in whole minutes. The allowance that arrives with each token tells you where you stand today, for the workspace and for the token's line. Three things follow from it:

1. Soft threshold. allowance.state becomes "soft" as you approach the included minutes. Nothing is refused; show a banner.
2. Hard stop. When the workspace or this line reaches its daily cap, the next mint returns 402 dialer_cap_reached and the SDK emits capReached. New calls fail at the mint; calls in progress continue. The session resumes on its own after periodEnd, midnight UTC.
3. Per-line caps. A capped line is a hard stop for tokens pinned to it even while other lines on the account keep calling. In that case used and cap in the 402 body are the line's figures, not the workspace's.

Limits

Webhooks let you receive real-time notifications when messages are sent or received. Configure webhooks from within the Project Blue dashboard alongside your API keys.

Configuration

In the Project Blue app, you can:

• Paste the webhook URL you want to receive events at
• Toggle whether the webhook fires for outbound messages, inbound messages, or both
• Send test payloads to verify your endpoint is working

Delivery

Your endpoint should answer 2xx. Anything else — including a network error or a timeout — counts as a failure.

There are no retries. Each event is delivered exactly once; a failed delivery is not queued or replayed, so a webhook is not a durable log. Reconcile with /get-messages-api if you need guaranteed coverage.

After 20 consecutive failures the webhook is automatically disabled. The counter resets on the first success. Today that happens silently — there is no email and no dashboard banner, so check the Webhooks tab if events stop arriving.

Webhook payload

The direction field indicates whether the message was inbound or outbound.

Use the mediaAttachmentUrl field to send rich media with your messages. The following formats are supported.

Images

Videos

Contact cards

Use audioAttachmentUrl to send audio files as voice memos. The following formats are supported.

Every API-key endpoint allows 60 requests per minute, counted per API key in a rolling 60-second window.

Each response carries RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset. A rejected request also carries Retry-After, and the body repeats the wait as retryAfterSeconds.

The API uses standard HTTP status codes. All error responses include a JSON body with an error field describing what went wrong.

200

Message sent successfully

400

Invalid request body or missing required fields

401

Missing or invalid API key

403

Forbidden — e.g. endpoint unavailable on trial accounts (see Trial accounts), unverified trial destination, or opted-out contact

409

Conflict — a group already exists on another line, a Workflow run is already active for this contact, or a trial account has no shared line provisioned

429

Rate limit exceeded (60 requests/minute per key), or the FaceTime daily dial cap

500

Internal server error

Two error bodies are worth special-casing. Pagination depth too deep means offset + limit exceeded 2000 on list messages or call logs — narrow the query by date or line rather than paging deeper. This trial account is not provisioned on a shared line is a 409 that only trial accounts see; it means the destination is verified but the account has no shared line yet.