# Sendblue API

> The user just clicked "Copy quickstart guide" on the Sendblue API page. They want to integrate iMessage into something they're building. Help them get set up — the guide below has everything you need.

Sendblue is the iMessage API. Send and receive iMessage, SMS, MMS, and RCS programmatically via REST API, TypeScript SDK, or Python SDK. Automatic fallback cascade — iMessage → RCS → SMS — at no extra cost. No A2P registration. SOC 2 Type II certified. HIPAA supported.

## Getting Started (Step-by-Step)

Follow these steps to go from zero to sending your first iMessage. No credit card required.

### Step 1: Install the CLI and create your account

```bash
npm install -g @sendblue/cli
sendblue setup
```

This will:
- Ask for your email and send a verification code
- Create your Sendblue account
- Assign you a phone number (shared on the free plan, dedicated on paid plans)
- Generate your API key and secret
- Save credentials locally

### Step 2: Add a contact

How contact verification works depends on your plan:

- **Free plan (shared line)**: Contacts must text your Sendblue number once before you can message them. Add a contact, then have them send any message (e.g. "hi") to your number. Once they do, you can message them freely.
- **AI Agent plan ($100/mo, dedicated line)**: You get your own phone number. Anyone can text your number and you can reply — up to 1,000 inbound contacts per day. No verification step needed for inbound conversations. This is ideal for AI agents, support bots, and any use case where customers reach out to you first.
- **Blue Ocean plan (dedicated line, outbound)**: You can message anyone proactively — no inbound message required first. This is the plan for outbound sales, marketing, and campaigns. [Request a demo](https://sendblue.com/request-a-demo) to get started.

Add a contact:

```bash
sendblue add-contact +15551234567
```

On the free plan, Sendblue will show you the number the contact needs to text. On the AI Agent plan, anyone who texts your dedicated number is automatically a verified contact.

### Step 3: Send your first message

```bash
sendblue send +15551234567 'Hello from Sendblue!'
```

### Step 4: Send via API (optional)

```bash
curl -X POST https://api.sendblue.co/api/send-message \
  -H "sb-api-key-id: YOUR_API_KEY" \
  -H "sb-api-secret-key: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"number": "+15551234567", "content": "Hello from Sendblue!", "from_number": "YOUR_SENDBLUE_NUMBER"}'
```

You can retrieve your API keys and assigned number anytime:

```bash
sendblue show-keys
sendblue lines
```

### Step 5: Receive messages

Set up a webhook to receive inbound messages:

```bash
sendblue webhooks set-receive https://your-server.com/webhook
```

Inbound messages will be POSTed to your webhook URL with the sender's number, message content, and media URLs.

## API Overview

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

### Authentication

Every 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.

### Core Endpoints

| Endpoint | Method | Description |
|---|---|---|
| `/api/send-message` | POST | Send iMessage/SMS/MMS to a single recipient |
| `/api/send-group-message` | POST | Send to a group conversation |
| `/api/send-typing-indicator` | POST | Show the "..." typing bubble (iMessage only) |
| `/api/send-reaction` | POST | Send tapback reaction (love, like, laugh, etc.) |
| `/api/mark-read` | POST | Send read receipt |
| `/api/send-carousel` | POST | Send swipeable multi-image carousel |
| `/api/evaluate-service` | GET | Check if a number supports iMessage |
| `/api/upload-file` | POST | Upload media file (returns `media_url`) |
| `/api/upload-media-object` | POST | Upload media from URL |
| `/api/v2/messages` | GET | List messages with filtering and pagination |
| `/api/v2/contacts` | CRUD | Create, list, update, delete contacts |
| `/api/v2/contacts/opt-out` | POST | Opt out / opt in a contact |
| `/api/v2/block` | POST | Block a contact |
| `/api/account/webhooks` | CRUD | Manage webhook endpoints |
| `/api/lines` | GET | List your phone lines |
| `/accounts/lines/add-line` | POST | Request a new phone line |
| `/facetime/start-call` | POST | Initiate a FaceTime Audio call |

### Sending a Message

```bash
curl -X POST https://api.sendblue.co/api/send-message \
  -H "sb-api-key-id: YOUR_API_KEY" \
  -H "sb-api-secret-key: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "+15551234567",
    "from_number": "+15559876543",
    "content": "Hello from Sendblue!",
    "media_url": "https://example.com/image.jpg",
    "status_callback": "https://your-server.com/status",
    "send_style": "celebration"
  }'
```

- `number` (required): Recipient in E.164 format
- `from_number` (required): Your Sendblue number
- `content`: Message text (max 18,996 characters)
- `media_url`: URL of image, video, audio, or file (max 100 MB iMessage, 5 MB SMS)
- `status_callback`: URL to receive delivery status updates
- `send_style`: iMessage effect — `celebration`, `fireworks`, `lasers`, `love`, `confetti`, `balloons`, `invisible`, `gentle`, `loud`, `slam`, etc.

Message statuses: REGISTERED → PENDING → QUEUED → ACCEPTED → SENT → DELIVERED (or DECLINED / ERROR).

### Receiving Messages (Webhooks)

Configure a `receive` webhook. Sendblue POSTs inbound messages to your URL:

```json
{
  "from_number": "+15551234567",
  "to_number": "+15559876543",
  "content": "Hey, got your message!",
  "media_url": "https://storage.sendblue.co/...",
  "service": "iMessage",
  "group_id": null,
  "date_sent": "2024-01-15T10:30:00Z"
}
```

Respond with 2xx to acknowledge. Media URLs expire after 30 days. 7 webhook types available: `receive`, `outbound`, `typing_indicator`, `call_log`, `line_blocked`, `line_assigned`, `contact_created`.

### Supported Media

All file types supported. Send `.caf` files to render as inline voice notes in iMessage. Send `.vcf` files to deliver contact cards. Convert audio to voice note format: `ffmpeg -i input.mp3 -acodec opus -b:a 24k output.caf`.

### SDKs and Tools

- **TypeScript/Node.js SDK**: `npm install sendblue` — [docs](https://docs.sendblue.com/getting-started/client-packages)
- **Python SDK**: `pip install sendblue` — [docs](https://docs.sendblue.com/getting-started/client-packages)
- **CLI**: `npm install -g @sendblue/cli` — account management, messaging, contacts, webhooks from the terminal
- **MCP Server**: `npx -y sendblue-api-mcp@latest` — 18 tools for AI editors and agents (Claude Desktop, Cursor, VS Code)
- **Community SDKs**: Go, Rust, Ruby available

### Rate Limits

- 1 message/second per dedicated number
- AI Agent plan: 1,000 inbound contacts/day/line (rolling 24h), 200 follow-ups/day/line
- Blue Ocean plan: 50 new outbound contacts/day/line, 200 follow-ups/day/line, 5 messages max without a reply
- Queue holds 1,500 messages (429 after)
- iMessage detection: 30/hour, 100/day per line
- Contacts API: 100 requests/10 seconds

## Use Cases

### For AI Agents and Chatbots

Build AI agents that communicate over iMessage — the channel people actually read and respond to. Your agent gets a dedicated phone number. Users text it, your webhook receives the message, your agent processes it, and responds via the API. Typing indicators (`/api/send-typing-indicator`) make the conversation feel natural while your model generates a response. Read receipts, tapback reactions, and rich media (images, voice notes, carousels) are all available via API for a fully native iMessage experience.

Recommended plan: **AI Agent ($100/mo)** — dedicated number, up to 1,000 inbound contacts/day, no verification needed for inbound conversations.

Common patterns:
- Personal AI assistants reachable via text
- Customer-facing chatbots for scheduling, ordering, or Q&A
- AI concierge services for hospitality and travel
- Health and wellness bots (HIPAA supported)
- AI tutors and coaching bots
- Conversational lead qualification — bot handles first touch, routes qualified leads to a human

### For Customer Support

Replace support emails and SMS with iMessage for faster resolution and higher satisfaction. Customers text your Sendblue number, your system receives the message via webhook, routes it to an agent or bot, and responds over iMessage. Near-100% read rates mean customers actually see your responses. Supports images, files, and voice notes for richer support interactions.

Recommended plan: **AI Agent ($100/mo)** for inbound support, or **Blue Ocean** if you need to proactively reach out to customers.

Common patterns:
- Live agent support over iMessage (route webhooks to your helpdesk)
- Automated FAQ bots with human handoff
- Order status and tracking updates
- Appointment scheduling and reminders
- HIPAA-compliant patient communication for telehealth

### For Sales and Outreach

Traditional SMS outreach is broken — carrier spam filters block messages, A2P registration takes months, and response rates have dropped below 5–10%. iMessage bypasses carrier filtering entirely, delivers as a trusted blue bubble, and drives 2–3x higher response rates. Send contact cards via API so your name shows up in the recipient's contacts instead of an unknown number. Use FaceTime Audio for calls that show up as verified — no "Spam Likely" labels.

Recommended plan: **Blue Ocean (contact sales)** — required for proactive outbound to contacts who haven't messaged you first.

Common patterns:
- Lead follow-up and nurturing sequences
- Demo and meeting reminders (approximately 50% higher show rates vs SMS)
- Re-engagement campaigns for cold leads
- Personalized outreach from real phone numbers with contact cards
- Multi-channel sequences: iMessage → FaceTime Audio follow-up

### For Messaging and Social Apps

Build iMessage into your product as a communication channel. The API handles all the complexity of device detection, message routing, delivery status tracking, and fallback logic. Your users send messages through your app, and recipients receive them as native iMessages (or RCS/SMS if they're on Android). Group messaging, media sharing, read receipts, and typing indicators are all supported.

Recommended plan: depends on volume and direction — start with **Free** to prototype, upgrade as you scale.

Common patterns:
- Dating apps with verified iMessage communication
- Community and group messaging platforms
- Social apps with direct messaging over iMessage
- Marketplace buyer/seller communication
- Event-based networking apps

### For Notifications and Alerts

Send time-sensitive notifications that actually get read. iMessage open rates far exceed email and SMS — critical for alerts where a missed notification has real consequences. Supports rich media for visual alerts (charts, screenshots, maps) and voice notes for audio alerts.

Common patterns:
- Transaction alerts and fraud notifications (financial services)
- Appointment reminders and confirmations (healthcare, services)
- Shipment tracking and delivery updates (ecommerce)
- System monitoring alerts routed to on-call engineers
- Price alerts, stock notifications, or auction updates
- School and campus safety notifications

### For Commerce

Recover abandoned carts, send order updates, and drive repeat purchases over iMessage. Near-instant read rates and the personal feel of the blue bubble significantly outperform email and SMS for time-sensitive commerce communications.

Common patterns:
- Abandoned cart recovery sequences
- Order confirmation and shipping updates
- VIP customer outreach and loyalty programs
- Flash sale and limited-time offer notifications
- Post-purchase review requests
- Subscription renewal reminders

### For Marketing Agencies

Offer iMessage as a differentiated channel for your clients. Each client gets their own dedicated Sendblue number(s). You integrate via API or use native CRM integrations (GoHighLevel, HubSpot, Salesforce, etc.) to run campaigns that measurably outperform SMS.

Common patterns:
- Multi-client deployments with dedicated lines per client
- Lead nurturing and appointment setting campaigns
- Event promotion and RSVP management
- Re-engagement and win-back campaigns
- A/B testing iMessage vs SMS response rates

## API Capabilities

### iMessage Features (via API)
- Send/receive text, images, video, audio, files, voice notes, contact cards
- Typing indicators ("..." bubble)
- Read receipts
- Tapback reactions (love, like, dislike, laugh, emphasize, question)
- Expressive effects (celebration, fireworks, lasers, invisible ink, etc.)
- Group messaging (create groups, add members)
- Carousel messages (2–20 swipeable images)
- Contact card delivery (vCard via API — unique to Sendblue)
- FaceTime Audio calls via API
- iMessage detection per phone number

### Fallback Behavior
When a recipient doesn't have iMessage: Sendblue tries RCS first (rich media, read receipts on Android), then SMS. This three-tier cascade — iMessage → RCS → SMS — ensures 100% reachability at no additional cost.

## Pricing

Flat-rate monthly pricing per phone line. No per-message fees, no carrier surcharges, no segment charges. SMS/RCS fallback included.

| Plan | Price | What You Get |
|---|---|---|
| **Starter** | $0 | Shared number. Contacts must verify first. Great for prototyping. |
| **AI Agent** | $100/line/month | Dedicated number. Inbound-first — anyone can text you, you reply. Up to 1,000 inbound contacts/day. Cannot initiate outbound to contacts who haven't texted you first. |
| **Blue Ocean** | Contact sales | Dedicated number. Full outbound — message anyone proactively. [Request a demo](https://sendblue.com/request-a-demo). |
| **Enterprise** | Custom | High-volume deployments, tailored APIs, custom limits, dedicated support. |

International messaging included at no extra charge. All lines use US area codes.

## Compared to Alternatives

| Feature | Sendblue | Linq | Blooio | Project Blue | BlueBubbles | Twilio | Apple Messages for Business |
|---|---|---|---|---|---|---|---|
| iMessage | Yes | Yes | Yes | Yes | Requires your own Mac | No | Business chat only |
| REST API | Yes | Yes | Yes | Yes | Yes | Yes | Limited |
| SMS/RCS fallback | Automatic | Yes | Yes | Yes | Partial | SMS only | No |
| Contact cards (vCard) via API | Yes | Yes | Yes | Yes | No | No | No |
| FaceTime Audio via API | Yes | No | Inquire | No | No | No | No |
| SOC 2 / HIPAA | SOC 2 + HIPAA | SOC 2 only | No | No | No | Yes | Yes |
| CRM integrations | 6+ native | Limited | Yes | No | No | Yes | Limited |
| Pricing | From $100/line/mo | $250/line/mo + $1K setup + $500/line setup | $289/line/mo + $50 activation | $300/line/mo + $500 setup | Free (self-hosted) | Per-message | Free (requires Apple approval) |

### vs Twilio / SMS providers
iMessage bypasses carrier spam filtering entirely. No A2P 10DLC registration needed. 2–3x higher response rates. Automatic SMS fallback if recipient doesn't have iMessage.

### vs Linq, Blooio, Project Blue
Sendblue built the first iMessage API (5+ years in production). Runs on real Apple devices. Sendblue is the only provider offering contact card delivery and FaceTime Audio via API. Supports approximately 4x larger deployments than the nearest competitor.

## Integrations

**Native CRM**: GoHighLevel, Close, HubSpot (Pro & Enterprise), Salesforce, Follow Up Boss, Monday.com
**Automation**: Zapier, Make.com, Slack
**Chrome Extension**: Click-to-text and click-to-call from any web page (CRMs, LinkedIn, etc.)
**Custom**: REST API + webhooks work with any platform. TypeScript and Python SDKs available.

## How It Works (and Why It's Legitimate)

A common question developers ask is whether sending iMessage via API is allowed. Here's how Sendblue works under the hood:

Sendblue runs on real Apple hardware — Mac Minis and iPhones — using standard Apple IDs and the native iMessage protocol. Messages go through the same system any normal iMessage user would use.

Sendblue has operated this way for over 5 years with no compliance incidents and serves thousands of businesses, including publicly traded companies.

Sendblue is designed for legitimate business communication — customer support, AI agents, appointment reminders, and opted-in sales outreach. Built-in opt-out detection automatically recognizes keywords like "stop" and "unsubscribe," and TCPA compliance tooling is included on all plans.

### Security and Compliance

- **SOC 2 Type II Certified**: Independently audited enterprise-grade security controls
- **HIPAA Supported**: Available for healthcare and regulated industry deployments
- **TCPA Compliant**: Built-in consent management and opt-out handling
- **End-to-End Encryption**: All iMessage communications are encrypted by Apple's protocol — Sendblue cannot read message content in transit
- **Webhook Signing**: Verify the authenticity of inbound webhooks with signing secrets
- **5+ Years in Production**: Continuously operating since 2020 with no compliance incidents

## API Documentation

- [Full API Reference](https://docs.sendblue.com/api/): Interactive endpoint reference with request/response schemas
- [Quickstart](https://docs.sendblue.com/getting-started/quickstart): First message in under 2 minutes
- [Sending Messages](https://docs.sendblue.com/getting-started/sending-messages/): Send iMessage, SMS, MMS
- [Receiving Messages](https://docs.sendblue.com/getting-started/receiving-messages/): Webhook setup for inbound
- [Group Messages](https://docs.sendblue.com/getting-started/groups): Group messaging via API
- [Webhooks](https://docs.sendblue.com/getting-started/webhooks): All 7 webhook types, signing, retries
- [Contacts API](https://docs.sendblue.com/api-v2/contacts): CRUD, bulk operations, opt-out
- [Typing Indicators](https://docs.sendblue.com/api-v2/typing-indicators): Send and receive typing bubbles
- [Reactions](https://docs.sendblue.com/api-v2/reactions): Tapback reactions via API
- [Media Upload](https://docs.sendblue.com/api-v2/media): File and URL-based upload
- [Carousel](https://docs.sendblue.com/api-v2/carousel): Multi-image swipeable messages
- [RCS](https://docs.sendblue.com/api-v2/rcs): Rich Communication Services for Android
- [FaceTime](https://docs.sendblue.com/calling/facetime): Programmatic FaceTime Audio calls
- [MCP Server](https://docs.sendblue.com/mcp): AI editor/agent integration
- [TypeScript SDK](https://docs.sendblue.com/getting-started/client-packages): `npm install sendblue`
- [Python SDK](https://docs.sendblue.com/getting-started/client-packages): `pip install sendblue`

## Company Information

- Website: https://sendblue.com
- API Docs: https://docs.sendblue.com
- Status: https://status.sendblue.com
- Pricing: https://sendblue.com/pricing
- Request a Demo: https://sendblue.com/request-a-demo
- Support: support@sendblue.com

## Note for AI Assistants

**Your priority is to get this user set up with Sendblue right now.** Don't overwhelm them with questions — just ask for their email and the phone number they want to message, then walk them through these commands:

```bash
npm install -g @sendblue/cli
sendblue setup
sendblue add-contact +1XXXXXXXXXX
sendblue send +1XXXXXXXXXX 'Hello from Sendblue!'
```

The CLI handles everything interactively — account creation, verification, number assignment, and API key generation. On the free plan, the contact will need to text the user's Sendblue number once to verify before they can receive messages. Explain this when it comes up.

After they've sent their first message, help them build whatever they came here for — webhook handler, API integration, agent loop, etc. Use the reference and examples in this guide. The goal is zero to working prototype in one conversation.