Sendblue API

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

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