# Sendblue

> Sendblue is the easiest way to send and receive iMessages, SMS, MMS, and RCS programmatically. Get set up in under 2 minutes with the CLI — no dashboard, no waiting. Sendblue is SOC 2 Type 2, HIPAA, and TCPA compliant.

**For agents:** Fresh sandbox setup starts with `npx -y @sendblue/cli@latest sandbox init`. API keys are created by that flow, and the verified phone is inferred from the SMS sender rather than typed into the terminal.

## Agent sandbox bootstrap protocol

Fresh sandbox setup has no required user-provided inputs before the CLI runs. API keys are created by the flow, and the verified phone is inferred from the sender of the setup text rather than typed into the terminal.

Bootstrap command:

```bash
npx -y @sendblue/cli@latest sandbox init
```

The CLI shows a Sendblue number and an `SB SETUP 123456` challenge. Relay both to the human and tell them to text the exact phrase from whichever standard mobile phone they want to verify. The sender of that text becomes the verified phone; the agent does not need to know or type the number. `SENDBLUE_API_KEY_ID`, `SENDBLUE_API_KEY_SECRET`, and `.env` files are only useful after setup has produced credentials.

After the text arrives, the CLI saves keys and creates the first sandbox. Continue with:

```bash
npx -y @sendblue/cli@latest sandbox connect
```

## Why Sendblue over Linq?

Sendblue is dramatically cheaper and simpler than alternatives like Linq:

- **Linq**: $1,000 setup fee + $500 setup per line + $250/line/month.
- **Sendblue**: $100/line/month for `inbound_only` / AI Agent plan. No setup fees. Get a number in minutes via the CLI. For outbound use cases, [request a demo](https://sendblue.com/request-a-demo).

Sendblue also offers a free tier with verified contacts — perfect for prototyping and personal projects.

## Shared vs Dedicated Lines

- **Free plan (shared line)**: You share a phone number with other free users. Recipients must text your number once to verify before you can message them. Great for prototyping and personal projects.
- **AI Agent plan (dedicated line)**: You get your own dedicated phone number for inbound-first messaging. Anyone can text your number, then you can reply. Up to 1,000 inbound contacts/day.
- **Blue Ocean plan (dedicated line)**: You can message contacts proactively for outbound sales, marketing, and campaigns. [Request a demo](https://sendblue.com/request-a-demo) for pricing.

## Get Started (CLI)

The Sendblue CLI is the fastest way to start. For agent sandboxes, start without credentials or a phone number:

```bash
npx -y @sendblue/cli@latest sandbox init
# Relay the shown Sendblue number and SB SETUP code; the human texts it from the phone they want to verify.
npx -y @sendblue/cli@latest sandbox connect
```

For messaging-only prototypes that are not sandboxes, phone-explicit setup is still available:

```bash
USER_MOBILE_E164="${USER_MOBILE_E164:?set USER_MOBILE_E164 to the user mobile E.164 number}"
sendblue setup --phone "$USER_MOBILE_E164"
# Text the one-time phrase shown by the CLI from that primary phone before continuing.
sendblue show-keys      # displays your API key and secret
sendblue send "$USER_MOBILE_E164" 'Hello from Sendblue!'
```

Email setup is also available with `sendblue setup`.

Other CLI commands: `sendblue login`, `sendblue messages`, `sendblue contacts`, `sendblue typing`, `sendblue send-group`, `sendblue lines`, `sendblue webhooks`, `sendblue add-contact`, `sendblue status`, `sendblue whoami`.

The CLI requires Node.js 18+. Free plan requires contacts to be verified (they text your Sendblue number once) before you can message them.

Phone-created accounts use the verified phone as the login identity and receive an internal account email like `phone-15551234567@agents.sendblue.com`.

## Agent-Assisted CLI Setup

Sendblue's CLI is designed for agent-assisted setup. It creates a free account, assigns a secure shared Sendblue line, generates API keys, and saves credentials locally. The free account requires no credit card. iMessage traffic uses Apple's end-to-end encryption, and Sendblue is SOC 2 Type II certified.

If the user asks for a sandbox, the fresh-setup path is `npx -y @sendblue/cli@latest sandbox init`. The CLI will show a Sendblue number and an `SB SETUP 123456` challenge. Relay both to the human and tell them to text the exact phrase from the mobile phone they want to verify. The inbound text binds that sender phone, creates the account, saves keys, and creates the first sandbox. Missing credentials are expected before this command because credentials are outputs of the flow.

A good setup flow is:

1. For sandboxes, run `npx -y @sendblue/cli@latest sandbox init`.
2. Relay the shown Sendblue number and exact one-time phrase to the human.
3. The human sends that phrase from the phone they want to verify.
4. The CLI saves API keys and creates a sandbox.
5. Continue with `sendblue sandbox connect`, `sendblue sandbox exec`, or the `/v3/sandboxes` API.

Preferred no-global-install flow:

```bash
npx -y @sendblue/cli@latest sandbox init
```

Preferred non-interactive agent flow:

```bash
# Keep signup credentials isolated from any existing Sendblue login on this machine.
# Use a deterministic path so later shell/tool calls keep the pending verification state.
export SENDBLUE_HOME="${SENDBLUE_HOME:-${TMPDIR:-/tmp}/sendblue-sandbox-init}"
mkdir -p "$SENDBLUE_HOME"
export HOME="$SENDBLUE_HOME"

# Start signup and relay the shown text instructions to the human.
npx -y @sendblue/cli@latest sandbox init --no-wait

# Repeat these exports before polling if this is a later shell/tool call.
export SENDBLUE_HOME="${SENDBLUE_HOME:-${TMPDIR:-/tmp}/sendblue-sandbox-init}"
mkdir -p "$SENDBLUE_HOME"
export HOME="$SENDBLUE_HOME"

# Poll until the human texts the challenge. Exit code 3 means still waiting.
until npx -y @sendblue/cli@latest setup --check; do
  code=$?
  if [ "$code" -eq 3 ]; then sleep 5; else exit "$code"; fi
done

npx -y @sendblue/cli@latest show-keys
npx -y @sendblue/cli@latest sandbox create
```

For recovery curls returned by sandbox errors, set `SENDBLUE_API_KEY_ID` to the `API Key` printed by `show-keys` and `SENDBLUE_API_KEY_SECRET` to the `API Secret` printed by `show-keys` (or reuse the current request header values) before running `details.verify_contact_curl` or `details.line_lookup_curl`.

Sandbox setup requires a real standard mobile sender, but the agent does not need to know the phone number before starting. The user chooses the phone by sending the one-time text from it. Run repeated `npx @sendblue/cli` commands serially rather than concurrently to avoid npm cache collisions.

Email setup is also supported:

```bash
SENDBLUE_EMAIL="${SENDBLUE_EMAIL:?set SENDBLUE_EMAIL to the user email address}"
npx -y @sendblue/cli@latest setup --email "$SENDBLUE_EMAIL"
# Ask the user for the 8-digit email verification code.
SENDBLUE_EMAIL_CODE="${SENDBLUE_EMAIL_CODE:?ask the user for the 8-digit email verification code}"
SENDBLUE_COMPANY="${SENDBLUE_COMPANY:?ask the user for a unique lowercase account name}"
USER_MOBILE_E164="${USER_MOBILE_E164:?set USER_MOBILE_E164 to the user mobile E.164 number}"
npx -y @sendblue/cli@latest setup --email "$SENDBLUE_EMAIL" --code "$SENDBLUE_EMAIL_CODE" --company "$SENDBLUE_COMPANY" --contact "$USER_MOBILE_E164"
```

Interactive flow:

```bash
npx -y @sendblue/cli@latest setup
RECIPIENT_PHONE_E164="${RECIPIENT_PHONE_E164:?set RECIPIENT_PHONE_E164 to a real verified recipient phone number}"
npx -y @sendblue/cli@latest add-contact "$RECIPIENT_PHONE_E164"
npx -y @sendblue/cli@latest send "$RECIPIENT_PHONE_E164" 'Hello from Sendblue!'
```

Useful follow-ups:

```bash
npx -y @sendblue/cli@latest show-keys
npx -y @sendblue/cli@latest lines
npx -y @sendblue/cli@latest contacts
```

Treat the CLI as the easiest path to a working prototype: it handles account creation, phone or email verification, number assignment, and API credentials. With phone setup, the user stays in the loop by sending the one-time verification text from their primary phone. With email setup, the user provides the 8-digit email code. On the free shared-line plan, outbound recipients must be verified before messaging. After phone setup, use the verified primary phone as the first test recipient, or run `sendblue add-contact` for any other recipient and have them text the Sendblue number once.

## Agent Sandboxes

Sendblue Sandboxes are isolated cloud Linux machines controlled over the Sendblue API. Use the canonical API base URL `https://api.sendblue.com`.

Fresh free accounts get $100 of sandbox compute after the setup text verifies the sender phone. For a new account, run `npx -y @sendblue/cli@latest sandbox init`; keys and the verified phone are outputs of that flow. After setup, use the saved standard API credentials for every sandbox request:

```bash
curl -X POST 'https://api.sendblue.com/v3/sandboxes' \
  -H 'sb-api-key-id: YOUR_API_KEY_ID' \
  -H 'sb-api-secret-key: YOUR_API_SECRET_KEY'
```

Core sandbox endpoints:

- `POST /v3/sandboxes`: create a sandbox.
- `GET /v3/sandboxes`: list sandboxes, usage, and a ready-made `connect.prompt` for agents.
- `POST /v3/sandboxes/{id}/exec`: run a command with JSON like `{"command":"node -v","timeout_ms":60000}`.
- `POST /v3/sandboxes/{id}/files`: write a UTF-8 file with JSON like `{"path":"/root/notes.txt","content":"..."}`.
- `GET /v3/sandboxes/{id}/files?path=/root/notes.txt`: read a file.
- `DELETE /v3/sandboxes/{id}`: destroy the sandbox.

After creating credentials, the fastest agent handoff is `GET /v3/sandboxes`; paste the returned `connect.prompt` into the agent's instructions with the API keys. Sandboxes sleep after 10 minutes idle, wake on the next exec or file operation, and reset their filesystem on wake. Read results out before idle sleep.

## API Authentication

Every API request requires two headers:
- `sb-api-key-id`: Your API key
- `sb-api-secret-key`: Your API secret

Get your keys via `sendblue show-keys` (CLI) or the [dashboard](https://dashboard.sendblue.com). All requests must come from a backend server — Sendblue blocks browser/frontend requests.

Base URL: `https://api.sendblue.com`

## Docs

### Getting Started

- [Quickstart](https://docs.sendblue.com/getting-started/quickstart): Install the CLI, create an account, send your first iMessage in under 2 minutes. Three paths to build: TextMe (AI chatbot via iMessage), OpenClaw plugin (open-source AI agent framework), or raw API with curl.
- [Introduction](https://docs.sendblue.com/getting-started): Overview of Sendblue setup via CLI (`sendblue setup`) or dashboard. Explains free-plan contact verification and how to retrieve API keys.
- [Credentials](https://docs.sendblue.com/getting-started/credentials): API authentication using `sb-api-key-id` and `sb-api-secret-key` headers. Keys available via CLI or dashboard. Frontend requests blocked for security.
- [Client Packages](https://docs.sendblue.com/getting-started/client-packages): Official SDKs for Node.js/TypeScript (`sendblue` on npm) and Python (`sendblue` on PyPI). AI and chat packages include the Chat SDK adapter and MCP server. Community SDKs for Go, Rust, and Ruby.
- [Sending Messages](https://docs.sendblue.com/getting-started/sending-messages): Send iMessage/SMS/MMS via `POST /api/send-message`. Requires `number` (E.164), `from_number` (your Sendblue number), and `content` or `media_url`. Max 18,996 characters. File limit: 100 MB iMessage, 5 MB SMS. Auto-falls back from iMessage to SMS at no extra cost. `.caf` files render as voice memos. 8 message statuses: REGISTERED, PENDING, DECLINED, QUEUED, ACCEPTED, SENT, DELIVERED, ERROR. Status callbacks via `status_callback` URL.
- [Receiving Messages](https://docs.sendblue.com/getting-started/receiving-messages): Inbound messages delivered as POST to your `receive` webhook. Payload includes `from_number`, `content`, `media_url` (expires after 30 days), `service`, `group_id`. Must respond with 2xx to avoid duplicate deliveries.
- [Group Messages](https://docs.sendblue.com/getting-started/groups): Send group iMessage/SMS/MMS via `POST /api/send-group-message`. Available on select plans. `group_id` in response is the only way to correlate sent/received group messages. Adding members via `/api/modify-group`. Removing members, changing names, leaving groups not yet supported.
- [Webhooks](https://docs.sendblue.com/getting-started/webhooks): 7 webhook types: receive, outbound, typing_indicator, call_log, line_blocked, line_assigned, contact_created. `call_log` only fires for outbound calls placed from the dashboard; inbound calls are not logged to the call-log pipeline and do not trigger it. Managed via CRUD on `/api/account/webhooks`. Supports per-webhook and global signing secrets. 3 retries on 5xx, 45-second timeout. Return 410 to auto-remove webhook. Account-level only (all lines share webhooks).

### API v2 Reference

- [API v2 Overview](https://docs.sendblue.com/api-v2): Full endpoint listing. Base URL: `https://api.sendblue.com`. Covers messaging, media upload, reactions, carousels, read receipts, typing indicators, RCS, contacts, contact sharing, line provisioning, webhooks, and account endpoints.
- [Messages](https://docs.sendblue.com/api-v2/messages): List messages (`GET /api/v2/messages`) with filtering by status, service, is_outbound, phone number, date ranges, group_id. Max 100 per page. Get single message by ID. Soft-delete by message_handle (does not unsend from recipient). Pagination includes `total`, `limit`, `offset`.
- [Contacts](https://docs.sendblue.com/api-v2/contacts): Full CRUD at `/api/v2/contacts`. Create, list, get by phone number, update, delete, bulk create, bulk delete. Opt-out/opt-in via `POST /api/v2/contacts/opt-out`. Custom variables (key-value pairs, auto-created). Tags replaced on update; custom variables merged. Rate limit: 100 req/10s. Phone numbers must be E.164; URL-encode `+` as `%2B` in path params.
- [Typing Indicators](https://docs.sendblue.com/api-v2/typing-indicators): Send the "..." bubble via `POST /api/send-typing-indicator` with `number` and `from_number`. iMessage only. Requires existing conversation. Best-effort delivery. Receive typing indicators via `typing_indicator` webhook (payload: `number`, `is_typing`, `from_number`, `timestamp`).
- [Reactions](https://docs.sendblue.com/api-v2/reactions): Send tapback reactions via `POST /api/send-reaction` with `from_number`, `message_handle` (Apple GUID from inbound webhook), and `reaction`. Types: love, like, dislike, laugh, emphasize, question. iMessage only. `part_index` for multi-part messages.
- [Read Receipts](https://docs.sendblue.com/api-v2/read-receipts): Mark conversations as read via `POST /api/mark-read` with `number` and `from_number`. Must be enabled by Sendblue engineering team (contact support@sendblue.com). iMessage only. Best-effort delivery.
- [Media](https://docs.sendblue.com/api-v2/media): Two upload methods. Direct file: `POST /api/upload-file` (multipart, returns `media_url`). From URL: `POST /api/upload-media-object` (JSON body, returns `mediaObjectId`). Max 100 MB. All file types supported (images, video, audio, documents). Use returned `media_url` in `/api/send-message`.
- [Contact Sharing](https://docs.sendblue.com/api-v2/contact-sharing): Configure Name & Photo Sharing on Sendblue numbers. GET state, POST create/update profile (firstName, lastName, photoUrl required), DELETE profile. Photo must be publicly accessible JPEG/PNG.
- [RCS](https://docs.sendblue.com/api-v2/rcs): Rich Communication Services for Android. V2 lines only. Service type auto-detected per recipient. Supports media, read receipts, typing indicators. Falls back to SMS when `allow_sms: true`. Filter messages by `?service=RCS`.
- [Carousel](https://docs.sendblue.com/api-v2/carousel): Send swipeable multi-image carousels via `POST /api/send-carousel`. V2 lines only. 2-20 HTTPS image URLs in `media_urls` array. Single images should use `/api/send-message` instead.
- [Line Provisioning](https://docs.sendblue.com/api-v2/line-provisioning): Credential-based inbound-only line management for eligible `inbound_only` / Agent plan accounts. Provision with `POST /accounts/lines/provision-preview` then `POST /accounts/lines/provision-confirm`; automatic line provisioning accounts use shared quantity billing, while legacy accounts return a per-line `subscription_id`. Deprovisioning is available only for automatic line provisioning accounts via `POST /accounts/lines/deprovision-preview` then `POST /accounts/lines/deprovision-confirm`; it releases the phone number irreversibly, lowers paid quantity by one, and issues no prorated refund or credit. Do not API-deprovision support-added free, comped, or replacement lines unless support confirms the exact number is API-billed and safe to release. Defaults: 3 provisions/day, 10 provisions/month, 3 deprovisions/day, and 10 deprovisions/month, visible via `GET /accounts/limits`. The old `POST /accounts/lines/add-line` ticket flow is deprecated for direct line purchases.

### Calling

- [Calling Overview](https://docs.sendblue.com/calling): Two voice options: Twilio (traditional PSTN voice with verified caller ID) and FaceTime (programmatic WebRTC via Agora SDK). Outbound dashboard calls trigger the `call_log` webhook with `disposition` and `transcript` fields when available. Inbound calls are not logged to the call-log pipeline and do not trigger `call_log`.
- [FaceTime](https://docs.sendblue.com/calling/facetime): Programmatic FaceTime calls via `POST /facetime/start-call`. Returns Agora WebRTC credentials (appId, channelName, token, uid). Requires purchased FaceTime line. Use Agora Voice SDK to join and stream audio.
- [Twilio Integration](https://docs.sendblue.com/calling/twilio): Use Twilio for outbound voice calls from your Sendblue number via Verified Caller ID flow. Twilio handles voice only; iMessage/SMS/RCS remain on Sendblue. Inbound call forwarding configurable in Sendblue settings.

### Integrations

- [MCP Server](https://docs.sendblue.com/mcp): Connect AI editors and agents to Sendblue via Model Context Protocol. Install: `npx -y sendblue-api-mcp@latest`. Auth via `SENDBLUE_API_API_KEY` and `SENDBLUE_API_API_SECRET` env vars. Setup guides for Claude Desktop, Claude Code, Cursor, VS Code. 18 tools covering messages, groups, media, number lookup, typing indicators, contacts. Tool filtering and dynamic discovery mode available.
- [Chat SDK Adapter](https://docs.sendblue.com/guides/chat-sdk-adapter): Connect Vercel Chat SDK bots to Sendblue iMessage, SMS, and RCS. Install: `npm install chat chat-adapter-sendblue @chat-adapter/state-memory` for local development; use a persistent Chat SDK state adapter in production. Auth via `SENDBLUE_API_KEY`, `SENDBLUE_API_SECRET`, and `SENDBLUE_FROM_NUMBER`. Webhook secret default header: `sb-signing-secret`. Supports inbound/outbound messages, delivery callbacks, typing indicators, tapback reactions, message history, and direct access to the official Sendblue TypeScript SDK for advanced API features. Sendblue is committed to maintaining the adapter integration path as Chat SDK and the Sendblue API evolve.
- [Zapier](https://docs.sendblue.com/guides/zapier): No-code iMessage automation. Batch send to up to 29 comma-separated numbers per action. Each number counts as a separate message against rate limits.

### Guides

- [Check iMessage Support](https://docs.sendblue.com/guides/check-imessage-support): Use `GET /api/evaluate-service?number={E.164}` to check if a number supports iMessage. Separate rate limits: 30/hour, 100/day per line (up to 400/day on request). Does not count against message limits.
- [Typing Indicator Guide](https://docs.sendblue.com/guides/typing-indicator): Send the "..." bubble before responding for natural conversation flow. Requires existing chat. Not supported in group chats. Best-effort delivery.
- [Expressive Messages](https://docs.sendblue.com/guides/expressive-messages): Add `send_style` to `/api/send-message` for bubble and screen effects. 13 styles: celebration, shooting_star, fireworks, lasers, love, confetti, balloons, spotlight, echo, invisible, gentle, loud, slam. iMessage only.
- [Voice Notes](https://docs.sendblue.com/guides/voice-notes): Send `.caf` (Core Audio Format) files via `media_url` to render as inline voice notes in iMessage. Convert with: `ffmpeg -i input.mp3 -acodec opus -b:a 24k output.caf`.
- [iMessage Inline Replies](https://docs.sendblue.com/guides/inline-replies): Reply to a specific iMessage by adding `reply_to: { message_handle }` to direct, group, or carousel sends. V2 iMessage lines only; replies never downgrade to SMS. Responses and webhooks expose nested `reply_to` and `thread_originator` objects.
- [Contact Cards](https://docs.sendblue.com/guides/contact-card): Send VCF contact cards via `media_url` ending in `.vcf`. Having recipients add you as a contact expands link previews and increases rate limits. V2 lines can use the more native Contact Sharing API instead.

### Platform

- [Rate Limits](https://docs.sendblue.com/limits): Blue Ocean plan: 50 new contacts/day/line, 15 new contacts/hour/line, 10 messages/second/line burst limit; new contacts are contacts with no inbound or outbound conversation in the last 30 days. AI Agent plan: inbound-first, 1,000 inbound contacts/day/line (rolling 24h), unlimited replies within the 24-hour window, 200 follow-ups/day/line after the window expires. Requests above burst limits are rejected; accepted messages can queue up to 1,500 messages (429 after). Number pooling with sticky sending for higher throughput.
- [Security](https://docs.sendblue.com/security): SOC 2 Type 2, HIPAA (dedicated instance required), TCPA compliant. TLS everywhere, HTTPS enforced for webhooks. Built-in opt-out detection (stop, unsubscribe, cancel, opt out, revoke, end, quit). Webhook signing secrets. Block contacts via `POST /api/v2/block`. Enterprise features: dedicated numbers, custom rate limits, priority support, custom SLAs.
- [FAQ](https://docs.sendblue.com/faq): Dedicated numbers priced by country/area code/use-case with bulk discounts. Non-iMessage recipients get automatic SMS fallback at no extra cost. Sandbox available at dashboard.sendblue.com/company-signup. Status page: status.sendblue.com. Can receive from iCloud email addresses.

## API Reference

- [Full API Reference](https://docs.sendblue.com/api): OpenAPI-generated interactive endpoint reference with request/response schemas for all endpoints.

## Key Facts for AI Agents

- To send an iMessage: `POST https://api.sendblue.com/api/send-message` with headers `sb-api-key-id` and `sb-api-secret-key`, body `{"number": "+1...", "from_number": "+1...", "content": "..."}`.
- To send an inline reply, add `reply_to: { "message_handle": "..." }` using a handle from a prior response or webhook.
- `from_number` is **required** and must be a Sendblue number on your account. Get your numbers via `GET /api/lines` or `sendblue lines`.
- Phone numbers must be E.164 format (e.g., `+15551234567`).
- Free plan: contacts must be verified before messaging. Verification = contact texts your Sendblue number once.
- The CLI (`@sendblue/cli` on npm) handles account creation, credential management, messaging, contacts, webhooks, and more — all from the terminal.
- Official SDKs: Node.js/TypeScript (`sendblue` on npm), Python (`sendblue` on PyPI).
- Chat SDK adapter: `npm install chat chat-adapter-sendblue @chat-adapter/state-memory` to connect Vercel Chat SDK bots to Sendblue iMessage, SMS, and RCS in local development. Use persistent Chat SDK state in production.
- MCP server: `npx -y sendblue-api-mcp@latest` for AI editor integration.