# Sendblue

Send and receive iMessage and SMS

## Manual Description

Sendblue connects your agents to iMessage and SMS through your own dedicated phone number. Use it to text one person or a group, attach images and other media, check whether a number can receive iMessage before you send, show a typing indicator, and look up the delivery status of any message.

Authentication uses a Sendblue **API Key ID** and **API Secret Key**, sent as the `sb-api-key-id` and `sb-api-secret-key` headers. You can find both in your [Sendblue dashboard](https://dashboard.sendblue.com). Every message is sent from one of your registered Sendblue lines, supplied as the **From Number** in E.164 format (for example `+15551234567`).

**Operations**

* **Send Message** — send an iMessage or SMS to a single recipient. Provide message text, a media URL, or both, and optionally apply an iMessage expressive style (celebration, fireworks, lasers, confetti, and more).
* **Send Group Message** — send to multiple recipients at once. Pass one recipient per line; reuse the returned `group_id` to keep replying in the same thread.
* **Evaluate Service** — check whether a number is reachable on iMessage or only SMS, so you can branch before sending.
* **Send Typing Indicator** — show a recipient that a reply is being composed (one-to-one chats only).
* **Get Message** — retrieve a single message and its current status by message handle.

**Triggers**

* **Message Received** — fires on every inbound message. Configure it as the **Receive** webhook in your Sendblue dashboard.
* **Message Status Updated** — fires when an outbound message changes state (`SENT`, `DELIVERED`, `ERROR`). Configure it as the **Outbound** webhook, or pass its URL per message as `status_callback`.

Each trigger generates its own webhook URL — paste the matching URL into the corresponding field in your Sendblue dashboard.

## Usage Instructions

Send iMessages and SMS to individuals or groups, check whether a number supports iMessage, show typing indicators, and look up message status with Sendblue. Trigger workflows on inbound messages and delivery status updates.

## Tools

### `sendblue_send_message`

Send an iMessage or SMS to a single recipient via Sendblue.

#### Input

| Parameter         | Type   | Required | Description                                                                                            |
| ----------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------ |
| `number`          | string | Yes      | Recipient phone number in E.164 format (e.g., +19998887777)                                            |
| `from_number`     | string | Yes      | One of your registered Sendblue phone numbers to send from, in E.164 format (e.g., +18887776666)       |
| `content`         | string | No       | Message text content. Either content or media\_url must be provided.                                   |
| `media_url`       | string | No       | URL of a media file to send. Either content or media\_url must be provided.                            |
| `send_style`      | string | No       | iMessage expressive style (e.g., celebration, fireworks, lasers, confetti, balloons, invisible, slam). |
| `status_callback` | string | No       | Webhook URL that Sendblue will POST message status updates to.                                         |

#### Output

| Parameter        | Type    | Description                                       |
| ---------------- | ------- | ------------------------------------------------- |
| `status`         | string  | Message status: QUEUED, SENT, DELIVERED, or ERROR |
| `message_handle` | string  | Unique identifier for tracking the message        |
| `account_email`  | string  | Email of the account that sent the message        |
| `content`        | string  | Message content                                   |
| `is_outbound`    | boolean | Whether this is an outbound message               |
| `from_number`    | string  | Sending phone number                              |
| `number`         | string  | Recipient phone number                            |
| `media_url`      | string  | URL of attached media                             |
| `send_style`     | string  | iMessage expressive style applied                 |
| `seat_id`        | string  | UUID of the seat that sent the message            |
| `sender_email`   | string  | Email of the seat (user) that sent the message    |
| `error_code`     | number  | Numeric error code if the message failed          |
| `error_message`  | string  | Error message if the message failed               |
| `date_created`   | string  | When the message was created                      |
| `date_updated`   | string  | When the message was last updated                 |

### `sendblue_send_group_message`

Send an iMessage or SMS to a group of recipients via Sendblue.

#### Input

| Parameter         | Type   | Required | Description                                                                                            |
| ----------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------ |
| `numbers`         | array  | Yes      | Recipient phone numbers in E.164 format (e.g., \["+19998887777", "+13334445555"])                      |
| `items`           | string | No       | No description                                                                                         |
| `from_number`     | string | Yes      | One of your registered Sendblue phone numbers to send from, in E.164 format (e.g., +18887776666)       |
| `content`         | string | No       | Message text content. Either content or media\_url must be provided.                                   |
| `media_url`       | string | No       | URL of a media file to send. Either content or media\_url must be provided.                            |
| `send_style`      | string | No       | iMessage expressive style (e.g., celebration, fireworks, lasers, confetti, balloons, invisible, slam). |
| `group_id`        | string | No       | Unique identifier of an existing group to send to. Omit to start a new group.                          |
| `status_callback` | string | No       | Webhook URL that Sendblue will POST message status updates to.                                         |

#### Output

| Parameter        | Type    | Description                                       |
| ---------------- | ------- | ------------------------------------------------- |
| `status`         | string  | Message status: QUEUED, SENT, DELIVERED, or ERROR |
| `message_handle` | string  | Unique identifier for tracking the message        |
| `group_id`       | string  | Identifier of the group the message was sent to   |
| `participants`   | array   | Phone numbers participating in the group          |
| `account_email`  | string  | Email of the account that sent the message        |
| `content`        | string  | Message content                                   |
| `is_outbound`    | boolean | Whether this is an outbound message               |
| `from_number`    | string  | Sending phone number                              |
| `number`         | string  | Recipient phone number                            |
| `media_url`      | string  | URL of attached media                             |
| `send_style`     | string  | iMessage expressive style applied                 |
| `seat_id`        | string  | UUID of the seat that sent the message            |
| `sender_email`   | string  | Email of the seat (user) that sent the message    |
| `error_code`     | number  | Numeric error code if the message failed          |
| `error_message`  | string  | Error message if the message failed               |
| `date_created`   | string  | When the message was created                      |
| `date_updated`   | string  | When the message was last updated                 |

### `sendblue_evaluate_service`

Check whether a phone number can receive iMessage or only SMS.

#### Input

| Parameter | Type   | Required | Description                                                    |
| --------- | ------ | -------- | -------------------------------------------------------------- |
| `number`  | string | Yes      | Phone number to evaluate, in E.164 format (e.g., +19998887777) |

#### Output

| Parameter | Type   | Description                                      |
| --------- | ------ | ------------------------------------------------ |
| `number`  | string | The evaluated phone number in E.164 format       |
| `service` | string | The service the number supports: iMessage or SMS |

### `sendblue_send_typing_indicator`

Display a typing indicator to a recipient (not supported in group chats).

#### Input

| Parameter     | Type   | Required | Description                                                   |
| ------------- | ------ | -------- | ------------------------------------------------------------- |
| `number`      | string | Yes      | Recipient's phone number in E.164 format (e.g., +19998887777) |
| `from_number` | string | No       | Your Sendblue line number to send from, in E.164 format.      |

#### Output

| Parameter       | Type   | Description                                            |
| --------------- | ------ | ------------------------------------------------------ |
| `status`        | string | Delivery status of the typing indicator (e.g., QUEUED) |
| `status_code`   | number | Numeric status code returned by Sendblue               |
| `number`        | string | The recipient phone number                             |
| `error_message` | string | Error details, null on success                         |

### `sendblue_get_message`

Retrieve a single message and its current status by message handle/ID.

#### Input

| Parameter    | Type   | Required | Description                                               |
| ------------ | ------ | -------- | --------------------------------------------------------- |
| `message_id` | string | Yes      | The message handle/ID returned when the message was sent. |

#### Output

| Parameter            | Type    | Description                                  |
| -------------------- | ------- | -------------------------------------------- |
| `status`             | string  | Current message status                       |
| `message_handle`     | string  | Unique message identifier                    |
| `account_email`      | string  | Email of the account                         |
| `content`            | string  | Message content                              |
| `is_outbound`        | boolean | Whether the message is outbound              |
| `from_number`        | string  | Sending phone number                         |
| `number`             | string  | Recipient phone number                       |
| `to_number`          | string  | Destination phone number                     |
| `media_url`          | string  | URL of attached media                        |
| `message_type`       | string  | Message category: message or group           |
| `service`            | string  | Messaging service: iMessage, SMS, or RCS     |
| `group_id`           | string  | Group identifier (empty for non-group)       |
| `group_display_name` | string  | Group chat name                              |
| `participants`       | array   | Participant phone numbers                    |
| `send_style`         | string  | Expressive style applied                     |
| `was_downgraded`     | boolean | True if the recipient lacks iMessage support |
| `opted_out`          | boolean | True if the recipient has opted out          |
| `plan`               | string  | Account plan type                            |
| `sendblue_number`    | string  | Sendblue phone number used                   |
| `seat_id`            | string  | Seat UUID                                    |
| `sender_email`       | string  | Email of the sending seat                    |
| `error_code`         | number  | Numeric error code if failed                 |
| `error_message`      | string  | Error message if failed                      |
| `error_reason`       | string  | Additional error context                     |
| `error_detail`       | string  | Detailed error information                   |
| `date_sent`          | string  | ISO 8601 creation timestamp                  |
| `date_updated`       | string  | ISO 8601 last-update timestamp               |

## Triggers

A workflow can start when one of these Sendblue events occurs.

### Sendblue Message Received

Trigger when an inbound iMessage or SMS is received in Sendblue

Sendblue sends the event to the webhook URL shown in the block.

#### Output

| Field                | Type    | Description                                                     |
| -------------------- | ------- | --------------------------------------------------------------- |
| `account_email`      | string  | Email of the Sendblue account                                   |
| `content`            | string  | Message text content                                            |
| `media_url`          | string  | CDN link to attached media, if any                              |
| `is_outbound`        | boolean | True for outbound messages, false for inbound                   |
| `status`             | string  | Message status (e.g., RECEIVED, QUEUED, SENT, DELIVERED, ERROR) |
| `error_code`         | number  | Error identifier, null if none                                  |
| `error_message`      | string  | Descriptive error text, null if none                            |
| `error_reason`       | string  | Additional error context, null if none                          |
| `error_detail`       | string  | Detailed error information, null if none                        |
| `message_handle`     | string  | Sendblue message identifier (use to deduplicate)                |
| `date_sent`          | string  | ISO 8601 creation timestamp                                     |
| `date_updated`       | string  | ISO 8601 last-update timestamp                                  |
| `from_number`        | string  | E.164 sender phone number                                       |
| `number`             | string  | E.164 recipient/counterparty phone number                       |
| `to_number`          | string  | E.164 destination phone number                                  |
| `was_downgraded`     | boolean | True if the recipient lacks iMessage support                    |
| `plan`               | string  | Account plan type                                               |
| `message_type`       | string  | Message category (e.g., message, group)                         |
| `group_id`           | string  | Group identifier, empty for non-group messages                  |
| `participants`       | array   | Participant phone numbers for group messages                    |
| `send_style`         | string  | Expressive style if applied                                     |
| `opted_out`          | boolean | True if the recipient has opted out                             |
| `sendblue_number`    | string  | Sendblue phone number used                                      |
| `service`            | string  | Messaging service (iMessage or SMS)                             |
| `group_display_name` | string  | Group chat name, null for non-group messages                    |
| `sender_email`       | string  | Email of the user who sent the message                          |
| `seat_id`            | string  | Seat UUID, null if absent                                       |
| `raw`                | string  | Complete raw webhook payload from Sendblue as a JSON string     |

### Sendblue Message Status Updated

Trigger when an outbound message status changes (SENT, DELIVERED, ERROR) in Sendblue

Sendblue sends the event to the webhook URL shown in the block.

#### Output

| Field                | Type    | Description                                                     |
| -------------------- | ------- | --------------------------------------------------------------- |
| `account_email`      | string  | Email of the Sendblue account                                   |
| `content`            | string  | Message text content                                            |
| `media_url`          | string  | CDN link to attached media, if any                              |
| `is_outbound`        | boolean | True for outbound messages, false for inbound                   |
| `status`             | string  | Message status (e.g., RECEIVED, QUEUED, SENT, DELIVERED, ERROR) |
| `error_code`         | number  | Error identifier, null if none                                  |
| `error_message`      | string  | Descriptive error text, null if none                            |
| `error_reason`       | string  | Additional error context, null if none                          |
| `error_detail`       | string  | Detailed error information, null if none                        |
| `message_handle`     | string  | Sendblue message identifier (use to deduplicate)                |
| `date_sent`          | string  | ISO 8601 creation timestamp                                     |
| `date_updated`       | string  | ISO 8601 last-update timestamp                                  |
| `from_number`        | string  | E.164 sender phone number                                       |
| `number`             | string  | E.164 recipient/counterparty phone number                       |
| `to_number`          | string  | E.164 destination phone number                                  |
| `was_downgraded`     | boolean | True if the recipient lacks iMessage support                    |
| `plan`               | string  | Account plan type                                               |
| `message_type`       | string  | Message category (e.g., message, group)                         |
| `group_id`           | string  | Group identifier, empty for non-group messages                  |
| `participants`       | array   | Participant phone numbers for group messages                    |
| `send_style`         | string  | Expressive style if applied                                     |
| `opted_out`          | boolean | True if the recipient has opted out                             |
| `sendblue_number`    | string  | Sendblue phone number used                                      |
| `service`            | string  | Messaging service (iMessage or SMS)                             |
| `group_display_name` | string  | Group chat name, null for non-group messages                    |
| `sender_email`       | string  | Email of the user who sent the message                          |
| `seat_id`            | string  | Seat UUID, null if absent                                       |
| `raw`                | string  | Complete raw webhook payload from Sendblue as a JSON string     |
