Message sending

The primary way to send in v4 is POST /messages. You pass a recipient and top-level content fields; Blooio picks the sender unless you add from.

How a send resolves a sender, delivers, and how you reply in the resulting chat. Click a step for details.

Send to a recipient

curl -X POST https://api.blooio.com/v4/messages \
 -H "Authorization: Bearer bl_live_..." \
 -H "Content-Type: application/json" \
 -d '{
 "to": "+15551234567",
 "text": "Hello from Blooio!"
 }'

Try it

to is a string — a phone number (E.164) or email — or an array of strings for multiple recipients (which fan out into separate sends). Object forms exist only for { "contact_id": "ct_..." } and { "group_id": "grp_..." }.

Configure which channels your API key can use on the Channels page in the dashboard. from accepts a phone number, alias, or channel ID — see Channels & senders.

Reply in an existing chat

When you already have a chat_id, post to that chat. The channel and peer are inferred — do not send from or to:

curl -X POST https://api.blooio.com/v4/chats/chat_.../messages \
 -H "Authorization: Bearer bl_live_..." \
 -H "Content-Type: application/json" \
 -d '{
 "text": "Following up"
 }'

Try it

What comes back

A successful send returns the message at the top level (not wrapped in data), including the resolved from, chat_id, channel_id, channel_type, status, and often a routing object explaining how the sender was chosen.

{
 "id": "msg_...",
 "chat_id": "chat_...",
 "from": "+15551230001",
 "channel_id": "ch_...",
 "channel_type": "blooio",
 "status": "queued",
 "routing": { "mode": "priority", "channel_type": "blooio", "priority": 1 }
}

Use an Idempotency-Key header for safe retries — see Idempotency.

Content

Content is defined by top-level fields whose names identify the shape: text, attachments, poll, and more. Start with text; see Message content for media, combined parts, and polls, and Attachments for media URLs.

Messaging safety

Blooio protects the deliverability of your numbers automatically. Sends to Blooio (iMessage) channels pass through two kinds of graduated safeguards:

Conversation limits — a small number of messages may be sent to a new recipient before they respond, and a consecutive-message cap applies to each thread thereafter, rising as the thread builds two-way history. These return 429 (or 403 for content restrictions) with a conversation_* error code, and lift as soon as the recipient responds — an emoji reaction counts. Links and media stay text-only until the recipient writes back.
Number-level actions — each number carries a warm-up tier (new → warming → established) and, when risky sending patterns are detected, a graduated action: queue and slow pace sends transparently, pause_new rejects brand-new conversations (403 safety_new_conversations_paused), reply_only restricts outbound to threads with prior inbound (403 safety_reply_only), and review blocks the number (403 safety_account_review). Actions clear automatically as the pattern ages out.

See Messaging safety limits and recovery for the exact allowances, trigger thresholds, and recovery process. See Errors for the full code list, and subscribe to the safety.state_changed webhook event to track tier and action changes per number.