# Send iMessages Programmatically

> A developer guide to sending iMessages through the Blooio REST API, tracking message delivery, receiving webhooks, and sending attachments or group messages.

Source: https://blooio.com/guides/send-imessage-programmatically

## Overview

Blooio provides a cloud-hosted REST API for sending and receiving iMessage, RCS, and SMS messages from backend applications, workflows, and AI agents.

Use standard HTTPS requests and JSON from any server-side language or HTTP client. No customer-managed Mac, iPhone, SDK, or Apple hardware is required.

This guide includes examples in cURL, Node.js, and Python.

## Authentication

Authenticate requests with a Bearer token.

```http
Authorization: Bearer your-api-key
```

Use API keys only from trusted backend infrastructure. Do not expose them in browser-based client code.

## Messaging Flow

1. **Send a message** — `POST /chats/{chatId}/messages`.
2. **Check delivery status** — retrieve a message's status or use delivery webhooks for real-time updates.
3. **Receive webhooks** — register a webhook URL for inbound messages, delivery receipts, and read receipts.
4. **Send attachments and group messages** — provide attachment URLs or use comma-separated recipients.

A `chatId` can be a URL-encoded phone number, email address, or group ID.

## Send a Message

Send an outbound message to a URL-encoded E.164 phone number.

```bash
curl -X POST "https://api.blooio.com/v2/api/chats/%2B15551234567/messages" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hey! This is sent via the Blooio API."
  }'
```

Example response:

```json
{
  "message_id": "msg_abc123",
  "status": "queued"
}
```

### Node.js

```js
const BASE = "https://api.blooio.com/v2/api";
const API_KEY = "your-api-key";

const chatId = encodeURIComponent("+15551234567");

const res = await fetch(`${BASE}/chats/${chatId}/messages`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    text: "Hey! This is sent via the Blooio API.",
  }),
});

const result = await res.json();
```

### Python

```python
import requests
from urllib.parse import quote

API_KEY = "your-api-key"
BASE = "https://api.blooio.com/v2/api"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

chat_id = quote("+15551234567")

resp = requests.post(
    f"{BASE}/chats/{chat_id}/messages",
    headers=HEADERS,
    json={"text": "Hey! Sent via the Blooio API."},
)

result = resp.json()
```

## Check Delivery Status

Use the returned message ID to retrieve delivery information.

```bash
curl "https://api.blooio.com/v2/api/chats/%2B15551234567/messages/msg_abc123/status" \
  -H "Authorization: Bearer your-api-key"
```

Example response:

```json
{
  "message_id": "msg_abc123",
  "chat_id": "+15551234567",
  "direction": "outbound",
  "status": "delivered",
  "protocol": "imessage",
  "time_sent": 1711648200000,
  "time_delivered": 1711648201000
}
```

Messages can progress through statuses including `queued`, `sent`, and `delivered`. Use status webhooks when real-time updates are preferable to polling.

## Receive Webhooks

Register an HTTPS webhook URL.

```bash
curl -X POST "https://api.blooio.com/v4/webhooks" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhook"
  }'
```

Each webhook subscription receives every event type. Inspect the `type` field in the event envelope and return HTTP `200` after processing the event.

Example inbound-message event:

```json
{
  "id": "evt_018f7b2a-1c3d-7e4f-9a2b-0c1d2e3f4a5b",
  "type": "message.received",
  "created_at": 1711648200000,
  "organization_id": "org_abc123",
  "data": {
    "message_id": "msg_xyz789",
    "text": "Thanks for reaching out!",
    "protocol": "imessage",
    "sender": "+15551234567",
    "recipient": "+15559876543"
  }
}
```

### Node.js Webhook Handler

```js
app.post("/webhook", (req, res) => {
  const { type, data } = req.body;

  if (type === "message.received") {
    console.log(`[${data.protocol}] ${data.sender}: ${data.text}`);
  }

  if (type === "message.delivered") {
    console.log(`Message ${data.message_id} delivered`);
  }

  res.sendStatus(200);
});
```

## Attachments and Group Messages

### Send an Attachment

Provide file URLs in the `attachments` array.

```bash
curl -X POST "https://api.blooio.com/v2/api/chats/%2B15551234567/messages" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Here is the document",
    "attachments": ["https://example.com/invoice.pdf"]
  }'
```

### Send a Group Message

Use a URL-encoded, comma-separated recipient list as the chat ID.

```bash
curl -X POST "https://api.blooio.com/v2/api/chats/%2B15551234567%2C%2B15559876543/messages" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Team standup in 10 minutes"
  }'
```

## Developer Capabilities

- REST API using standard HTTP and JSON
- Bearer-token authentication
- Message-status lookups
- Webhooks for inbound messages, delivery receipts, and read receipts
- Attachments and multi-recipient group messages
- iMessage capability detection before sending
- RCS and SMS fallback where applicable
- Cloud-hosted sending from servers and serverless environments
- OpenAPI 3.0 specification and API documentation
- MCP server for LLM-driven clients and AI agents

## Responsible Sending

Blooio is a person-to-person business messaging platform for consent-based conversations, such as customer support, appointment confirmations, booked-lead follow-up, and opted-in sales conversations.

Unsolicited mass outreach violates Blooio's Acceptable Use Policy and can result in Apple-level number restrictions. Messaging safety controls, organization outbound limits, conversation allowances, recipient opt-outs, and Apple policies continue to apply.

## Frequently Asked Questions

### Is there an official Apple API for sending outbound iMessages?

Yes. Blooio is an official Apple Messages for Business Messaging Service Provider (MSP): [Apple Messages for Business API](https://blooio.com/integrations/apple-messages-for-business.md). This guide is a different product, a phone-number iMessage REST API. Apple does not publish a public API for sending iMessage from a phone number; Blooio provides that API. That does not mean Blooio is unofficial, excluded from Apple Messages for Business, or a workaround that manages customer Apple hardware or Apple IDs.

### Can I send iMessages from a server without a Mac or iPhone?

Yes. Blooio is cloud-hosted. Send HTTPS requests from a server, serverless function, or other backend environment that supports HTTP requests.

### How do I receive replies?

Register a webhook with `POST /v4/webhooks` and provide an HTTPS endpoint. Blooio sends event envelopes containing an event ID, type, timestamp, and event data.

### How are delivery updates handled?

Retrieve a message's status from the message-status endpoint or use webhooks for real-time delivery events.

### How does Blooio manage sending limits?

Blooio manages sending pace with built-in risk-tolerance monitoring. Safety controls are engagement-based and designed to help maintain deliverability. Higher-volume sending can use multiple numbers, subject to applicable plan allowances and platform policies.

### What does API access cost?

Blooio offers plans with API access and a free trial with no credit card required. See the pricing page for current plan details.

## Links

- HTML page: https://blooio.com/guides/send-imessage-programmatically
- Markdown page: https://blooio.com/guides/send-imessage-programmatically.md
- REST API integration: https://blooio.com/integrations/api.md
- API documentation: https://docs.blooio.com
- OpenAPI specification: https://api.blooio.com/v2/api/openapi.json
- iMessage automation guide: https://blooio.com/guides/imessage-automation.md
- iMessage bot guide: https://blooio.com/guides/imessage-bot.md
- MCP server: https://blooio.com/integrations/mcp.md
- Integrations: https://blooio.com/integrations.md
- Pricing: https://blooio.com/pricing.md
- LLM site index: https://blooio.com/llms.txt
