---

name: sendblue-sendblue-api description: "Send and receive iMessage, SMS, and RCS from application code via the Sendblue HTTP API \u2014 text, media, group messages, send styles, reactions, typing indicators, status callbacks, and inbound webhooks." category: api-integration risk: critical source: community source_type: official date_added: '2026-05-22' author: AnthonyFirth tags:

• sendblue
• imessage
• sms
• rcs
• messaging
• api
• webhooks tools:
• claude
• cursor
• gemini plugin: targets: codex: blocked claude: blocked

---

Sendblue API

Overview

Sendblue is a REST API that sends iMessage (blue bubbles), SMS, and RCS from a provisioned phone number. Everything is plain JSON over HTTPS — no SDK is required. The API covers outbound 1:1 and group sends, iMessage effects, reactions, typing indicators, status callbacks, and inbound webhooks.

When to Use This Skill

• Use when writing application code (server, worker, function) that sends Sendblue messages as part of a long-running service.
• Use when receiving inbound messages via webhooks.
• Use when you need features the CLI does not expose: send styles, reactions, group messages, typing indicators, status callbacks, media uploads, or the contacts API beyond basic CRUD.
• Reach for [[sendblue-cli]] instead for shell-context outbound: one-shot scripts, cron jobs, agent hooks, "ping me when X" workflows.

How It Works

Step 1: Authenticate

https://api.sendblue.com

Every request needs two headers:

sb-api-key-id: <YOUR_API_KEY_ID>
sb-api-secret-key: <YOUR_API_SECRET>
Content-Type: application/json

Keep both values server-side — never ship them to a browser or mobile client.

Step 2: Send a message

curl -X POST https://api.sendblue.com/api/send-message \
  -H "sb-api-key-id: $KEY_ID" \
  -H "sb-api-secret-key: $SECRET" \
  -H 'Content-Type: application/json' \
  -d '{
    "number": "+15551234567",
    "from_number": "+1YOUR_SENDBLUE_NUMBER",
    "content": "Hello from the API!"
  }'

Phone numbers must be E.164. from_number must be a line you own — list yours with GET /api/lines.

Step 3: Track delivery

The synchronous response includes a message_handle (Apple GUID — persist this; you need it for reactions and replies) and a status from REGISTERED, PENDING, QUEUED, ACCEPTED, SENT, DELIVERED, DECLINED, ERROR. Only DELIVERED means it landed. Use status_callback instead of polling /api/status.

Step 4: Receive inbound

Configure webhook URLs in the dashboard or via POST /api/account/webhooks. Sendblue POSTs JSON to your endpoint. Respond with 2xx promptly — non-2xx triggers retries and duplicate deliveries. Event types: receive, outbound, typing_indicator, call_log, line_blocked, line_assigned, contact_created.

Core Endpoints

Method	Path	Purpose
POST	/api/send-message	Send a 1:1 message (text and/or media)
POST	/api/send-group-message	Send to multiple recipients
POST	/api/create-group	Create a named group thread
POST	/api/send-reaction	Send a tapback (love/like/dislike/laugh/emphasize/question)
POST	/api/send-typing-indicator	Show "typing…" in the recipient's thread
POST	/api/mark-read	Send a read receipt
POST	/api/upload-file / /api/upload-media-object	Upload media (direct or from URL)
GET	/api/status	Poll a message's delivery status
GET	/api/evaluate-service	Check whether a number is on iMessage
GET	/api/v2/messages / /api/v2/messages/:id	Read message history
GET / POST / PUT / DELETE	/api/v2/contacts[...]	Manage contacts
GET	/api/lines	List your Sendblue phone numbers
POST	/api/account/webhooks	CRUD webhook subscriptions

Examples

Example 1: Send with media, effects, and a status callback

POST /api/send-message
{
  "number": "+15551234567",
  "from_number": "+1YOUR_SENDBLUE_NUMBER",
  "content": "Optional text",
  "media_url": "https://example.com/img.jpg",
  "send_style": "celebration",
  "status_callback": "https://yourapp.com/sendblue/status"
}

content and/or media_url is required. send_style is iMessage-only — valid values: celebration, shooting_star, fireworks, lasers, love, confetti, balloons, spotlight, echo, invisible, gentle, loud, slam. Ignored on SMS. Text up to 18,996 chars; media up to 100 MB on iMessage, 5 MB on SMS.

Example 2: Group message

POST /api/send-group-message
{
  "numbers": ["+15551234567", "+15557654321"],
  "from_number": "+1YOUR_SENDBLUE_NUMBER",
  "content": "Hey team"
}

The response returns a group_id — persist it to send follow-ups into the same thread instead of creating a new one each time.

Example 3: React to a message

POST /api/send-reaction
{
  "from_number": "+1YOUR_SENDBLUE_NUMBER",
  "message_handle": "<message_handle from prior send>",
  "reaction": "love"
}

Reactions only work on iMessage and need the original message's message_handle. Valid values: love, like, dislike, laugh, emphasize, question.

Example 4: Inbound webhook payload (receive)

{
  "accountEmail": "you@example.com",
  "content": "Reply text",
  "media_url": "https://...",
  "is_outbound": false,
  "number": "+15551234567",
  "from_number": "+1YOUR_SENDBLUE_NUMBER",
  "service": "iMessage",
  "group_id": "...",
  "date_sent": "2024-01-01T12:00:00Z"
}

Status callback payloads (outbound) mirror the send-message response and update as the message moves through SENT → DELIVERED (or ERROR).

Best Practices

• ✅ Persist message_handle on every send. You need it for reactions, replies, and correlating status callbacks.
• ✅ Use status_callback over polling. It's lower-cost and more accurate than GET /api/status.
• ✅ Return 2xx fast from your webhook, then process async. Non-2xx triggers duplicate deliveries.
• ✅ Check service with /api/evaluate-service before relying on iMessage-only features for a recipient.
• ✅ Rehost inbound media on receipt — media URLs expire in ~30 days.
• ❌ Don't ship sb-api-key-id / sb-api-secret-key to a client. They are server-side credentials.
• ❌ Don't treat a 200 on /api/send-message as delivery. It only means "accepted".

Limitations

• Synchronous send responses only report acceptance, not delivery. Final state arrives via status_callback or GET /api/status.
• send_style silently no-ops on SMS (green-bubble recipients).
• Inbound media URLs expire in ~30 days.
• Per-line rate limits apply; bursting many sends from one number can trip Apple's spam heuristics — pace them or split across lines.
• Reactions and effects are iMessage-only.

Security & Safety Notes

• Keep sb-api-key-id and sb-api-secret-key server-side. They are not safe in browser, mobile, or CI logs.
• Treat every outbound send, contact/webhook mutation, read receipt, reaction, or typing indicator as state-changing. Preview the recipient, sender line, content, and callback/webhook changes, then wait for explicit user confirmation before sending.
• Webhook endpoints should be on HTTPS and idempotent — same message_handle may arrive more than once.
• Sensitive data in message content is visible in lock-screen previews on the recipient's device. Don't embed secrets, tokens, or full PII — link to an authenticated dashboard or shortened payload instead.
• Rotate API keys from the Sendblue dashboard if either value is exposed; the old pair is invalidated on rotation.

Common Pitfalls

• E.164 only. 5551234567 or (555) 123-4567 will fail — always send +15551234567.
• from_number must be one of your lines. A spoofed or unprovisioned number returns an error.
• send_style silently no-ops on SMS. If the recipient is green-bubble, effects don't render — check service first with /api/evaluate-service if it matters.
• Store message_handle. You need it for reactions, replies, and correlating status callbacks back to your records.
• Media URLs expire in ~30 days. If you need durable media from inbound webhooks, download and re-host on receipt.
• Status is async. A 200 on /api/send-message means accepted, not delivered. Use status_callback rather than blocking on the synchronous response.
• Webhook retries on non-2xx. Return 200 even when you've decided to ignore the event; otherwise expect duplicate deliveries.
• Rate limits apply per line. Bursting many sends from one number trips Apple's spam heuristics — pace them or split across lines.

Related Skills

• @sendblue-cli — Shell wrapper for shell-context outbound (scripts, cron, agent hooks). Use it when you don't need a full HTTP integration.
• @sendblue-notify — Patterns and copy rules for outbound "text me when X is done" notifications layered on top of the API or CLI.

Links

• Full reference: https://docs.sendblue.com/
• Sendblue: https://sendblue.com
• Useful undocumented-here features: carousels (/api/send-carousel), FaceTime/contact-card sharing, advanced webhook filtering, contacts API beyond basic CRUD — see the docs site.