# Messages

## List

**get** `/api/v2/messages`

Retrieve a list of messages for the authenticated account with comprehensive filtering capabilities.
Rate limited to 100 requests per 10 seconds per account.

## Common Use Cases

**Polling for inbound messages (no webhooks):**

```
GET /api/v2/messages?is_outbound=false&sendblue_number=+16292925296&order_by=createdAt&order_direction=desc&limit=50
```

Track processed message IDs to avoid duplicates.

**Get conversation with a specific contact:**

```
GET /api/v2/messages?number=+15551234567&order_by=createdAt&order_direction=desc
```

### Query Parameters

- `account_email: optional string`

  Filter by account email

- `created_at_gte: optional string`

  Filter messages created after this date (ISO 8601 format)

- `created_at_lte: optional string`

  Filter messages created before this date (ISO 8601 format)

- `from_number: optional string`

  Filter by sender phone number

- `group_id: optional string`

  Filter by group ID

- `is_outbound: optional "true" or "false"`

  Filter by message direction. Use `false` to get inbound messages (messages sent TO your Sendblue number).

  **To get inbound messages for polling:** Use `is_outbound=false` combined with `sendblue_number` or `to_number` set to your Sendblue phone number.

  Note: Do NOT use `message_type=inbound` - that parameter only accepts `message` or `group` values.

  - `"true"`

  - `"false"`

- `limit: optional number`

  Maximum number of messages to return

- `message_type: optional "message" or "group"`

  Filter by message type (1:1 vs group chat). Only accepts `message` or `group`.

  **Common mistake:** This is NOT for filtering inbound vs outbound messages. Use `is_outbound` parameter instead.

  - `"message"`

  - `"group"`

- `number: optional string`

  Filter by any phone number (from or to)

- `offset: optional number`

  Number of messages to skip

- `order_by: optional "createdAt" or "updatedAt" or "sentAt"`

  Field to order messages by

  - `"createdAt"`

  - `"updatedAt"`

  - `"sentAt"`

- `order_direction: optional "asc" or "desc"`

  Sort order

  - `"asc"`

  - `"desc"`

- `sendblue_number: optional string`

  Filter by Sendblue phone number

- `sent_at_gte: optional string`

  Filter messages sent after this date (ISO 8601 format)

- `sent_at_lte: optional string`

  Filter messages sent before this date (ISO 8601 format)

- `service: optional "iMessage" or "SMS" or "RCS"`

  Filter by service type

  - `"iMessage"`

  - `"SMS"`

  - `"RCS"`

- `status: optional "REGISTERED" or "PENDING" or "SENT" or 7 more`

  Filter by message status

  - `"REGISTERED"`

  - `"PENDING"`

  - `"SENT"`

  - `"DELIVERED"`

  - `"RECEIVED"`

  - `"QUEUED"`

  - `"ERROR"`

  - `"DECLINED"`

  - `"ACCEPTED"`

  - `"SUCCESS"`

- `to_number: optional string`

  Filter by recipient phone number

- `updated_at_gte: optional string`

  Filter messages updated after this date (ISO 8601 format)

- `updated_at_lte: optional string`

  Filter messages updated before this date (ISO 8601 format)

- `worker_id: optional string`

  Filter by worker ID (Admin only)

### Returns

- `data: optional array of object { accountEmail, content, date_sent, 22 more }`

  - `accountEmail: optional string`

    Email of the account

  - `content: optional string`

    Message content

  - `date_sent: optional string`

    When the message was sent

  - `date_updated: optional string`

    When the message was last updated

  - `error_code: optional number`

    Numeric error code if message failed

  - `error_detail: optional string`

    Detailed error information

  - `error_message: optional string`

    Error message if message failed

  - `error_reason: optional string`

    Error reason if message failed

  - `from_number: optional string`

    Sender phone number

  - `group_display_name: optional string`

    Display name for group messages

  - `group_id: optional string`

    Group ID for group messages

  - `is_outbound: optional boolean`

    Whether this is an outbound message

  - `media_url: optional string`

    URL of attached media

  - `message_handle: optional string`

    Unique message identifier

  - `message_type: optional "message" or "group"`

    - `"message"`

    - `"group"`

  - `number: optional string`

    Primary phone number (to_number for outbound, from_number for inbound)

  - `opted_out: optional boolean`

    Whether the recipient has opted out

  - `participants: optional array of string`

    List of participants for group messages

  - `plan: optional string`

    Account plan used for this message

  - `send_style: optional "celebration" or "shooting_star" or "fireworks" or 10 more`

    The iMessage expressive message style

    - `"celebration"`

    - `"shooting_star"`

    - `"fireworks"`

    - `"lasers"`

    - `"love"`

    - `"confetti"`

    - `"balloons"`

    - `"spotlight"`

    - `"echo"`

    - `"invisible"`

    - `"gentle"`

    - `"loud"`

    - `"slam"`

  - `sendblue_number: optional string`

    Sendblue phone number used

  - `service: optional "iMessage" or "SMS" or "RCS"`

    The messaging service used

    - `"iMessage"`

    - `"SMS"`

    - `"RCS"`

  - `status: optional "REGISTERED" or "PENDING" or "SENT" or 7 more`

    - `"REGISTERED"`

    - `"PENDING"`

    - `"SENT"`

    - `"DELIVERED"`

    - `"RECEIVED"`

    - `"QUEUED"`

    - `"ERROR"`

    - `"DECLINED"`

    - `"ACCEPTED"`

    - `"SUCCESS"`

  - `to_number: optional string`

    Recipient phone number

  - `was_downgraded: optional boolean`

    Whether the message was downgraded from iMessage to SMS

- `pagination: optional object { hasMore, limit, offset, total }`

  - `hasMore: optional boolean`

    Whether there are more messages available

  - `limit: optional number`

    Number of messages returned in this request

  - `offset: optional number`

    Number of messages skipped

  - `total: optional number`

    Total number of messages matching the filters

- `status: optional string`

### Example

```http
curl https://api.sendblue.co/api/v2/messages \
    -H "sb-api-key-id: $SENDBLUE_API_API_KEY" \
    -H "sb-api-secret-key: $SENDBLUE_API_API_SECRET"
```

## Retrieve

**get** `/api/v2/messages/{message_id}`

Retrieve details of a specific message by its ID

### Path Parameters

- `message_id: string`

### Returns

- `data: optional object { accountEmail, content, date_sent, 22 more }`

  - `accountEmail: optional string`

    Email of the account

  - `content: optional string`

    Message content

  - `date_sent: optional string`

    When the message was sent

  - `date_updated: optional string`

    When the message was last updated

  - `error_code: optional number`

    Numeric error code if message failed

  - `error_detail: optional string`

    Detailed error information

  - `error_message: optional string`

    Error message if message failed

  - `error_reason: optional string`

    Error reason if message failed

  - `from_number: optional string`

    Sender phone number

  - `group_display_name: optional string`

    Display name for group messages

  - `group_id: optional string`

    Group ID for group messages

  - `is_outbound: optional boolean`

    Whether this is an outbound message

  - `media_url: optional string`

    URL of attached media

  - `message_handle: optional string`

    Unique message identifier

  - `message_type: optional "message" or "group"`

    - `"message"`

    - `"group"`

  - `number: optional string`

    Primary phone number (to_number for outbound, from_number for inbound)

  - `opted_out: optional boolean`

    Whether the recipient has opted out

  - `participants: optional array of string`

    List of participants for group messages

  - `plan: optional string`

    Account plan used for this message

  - `send_style: optional "celebration" or "shooting_star" or "fireworks" or 10 more`

    The iMessage expressive message style

    - `"celebration"`

    - `"shooting_star"`

    - `"fireworks"`

    - `"lasers"`

    - `"love"`

    - `"confetti"`

    - `"balloons"`

    - `"spotlight"`

    - `"echo"`

    - `"invisible"`

    - `"gentle"`

    - `"loud"`

    - `"slam"`

  - `sendblue_number: optional string`

    Sendblue phone number used

  - `service: optional "iMessage" or "SMS" or "RCS"`

    The messaging service used

    - `"iMessage"`

    - `"SMS"`

    - `"RCS"`

  - `status: optional "REGISTERED" or "PENDING" or "SENT" or 7 more`

    - `"REGISTERED"`

    - `"PENDING"`

    - `"SENT"`

    - `"DELIVERED"`

    - `"RECEIVED"`

    - `"QUEUED"`

    - `"ERROR"`

    - `"DECLINED"`

    - `"ACCEPTED"`

    - `"SUCCESS"`

  - `to_number: optional string`

    Recipient phone number

  - `was_downgraded: optional boolean`

    Whether the message was downgraded from iMessage to SMS

- `status: optional string`

### Example

```http
curl https://api.sendblue.co/api/v2/messages/$MESSAGE_ID \
    -H "sb-api-key-id: $SENDBLUE_API_API_KEY" \
    -H "sb-api-secret-key: $SENDBLUE_API_API_SECRET"
```

## Send

**post** `/api/send-message`

Send an iMessage, SMS, or MMS to a single recipient

### Body Parameters

- `content: string`

  Message text content

- `from_number: string`

  **REQUIRED** - The phone number to send from. Must be one of your registered Sendblue phone numbers in E.164 format.
  Without this parameter, the message will fail to send.

- `number: string`

  Recipient phone number in E.164 format

- `media_url: optional string`

  URL of media file to send (images, videos, etc.)

- `send_style: optional "celebration" or "shooting_star" or "fireworks" or 10 more`

  The iMessage expressive message style

  - `"celebration"`

  - `"shooting_star"`

  - `"fireworks"`

  - `"lasers"`

  - `"love"`

  - `"confetti"`

  - `"balloons"`

  - `"spotlight"`

  - `"echo"`

  - `"invisible"`

  - `"gentle"`

  - `"loud"`

  - `"slam"`

- `status_callback: optional string`

  Webhook URL for message status updates

### Returns

- `MessageResponse = object { account_email, content, date_created, 10 more }`

  - `account_email: optional string`

    Email of the account that sent the message

  - `content: optional string`

    Message content

  - `date_created: optional string`

    When the message was created

  - `date_updated: optional string`

    When the message was last updated

  - `error_code: optional number`

    Numeric error code if message failed

  - `error_message: optional string`

    Error message if message failed

  - `from_number: optional string`

    Sending phone number

  - `is_outbound: optional boolean`

    Whether this is an outbound message

  - `media_url: optional string`

    URL of attached media

  - `message_handle: optional string`

    Unique identifier for tracking the message

  - `number: optional string`

    Recipient phone number

  - `send_style: optional "celebration" or "shooting_star" or "fireworks" or 10 more`

    The iMessage expressive message style

    - `"celebration"`

    - `"shooting_star"`

    - `"fireworks"`

    - `"lasers"`

    - `"love"`

    - `"confetti"`

    - `"balloons"`

    - `"spotlight"`

    - `"echo"`

    - `"invisible"`

    - `"gentle"`

    - `"loud"`

    - `"slam"`

  - `status: optional "QUEUED" or "SENT" or "DELIVERED" or "ERROR"`

    - `"QUEUED"`

    - `"SENT"`

    - `"DELIVERED"`

    - `"ERROR"`

### Example

```http
curl https://api.sendblue.co/api/send-message \
    -H 'Content-Type: application/json' \
    -H "sb-api-key-id: $SENDBLUE_API_API_KEY" \
    -H "sb-api-secret-key: $SENDBLUE_API_API_SECRET" \
    -d '{
          "content": "Hello, World!",
          "from_number": "+19998887777",
          "number": "+19998887777",
          "media_url": "https://example.com/image.jpg",
          "send_style": "celebration",
          "status_callback": "https://example.com/webhook"
        }'
```

## Get Status

**get** `/api/status`

Retrieve the current status of a message using its message handle. Useful for resolving pending message statuses and avoiding duplicate messages.

### Query Parameters

- `handle: string`

  The message handle of the message you want to check status for

### Returns

- `MessageResponse = object { account_email, content, date_created, 10 more }`

  - `account_email: optional string`

    Email of the account that sent the message

  - `content: optional string`

    Message content

  - `date_created: optional string`

    When the message was created

  - `date_updated: optional string`

    When the message was last updated

  - `error_code: optional number`

    Numeric error code if message failed

  - `error_message: optional string`

    Error message if message failed

  - `from_number: optional string`

    Sending phone number

  - `is_outbound: optional boolean`

    Whether this is an outbound message

  - `media_url: optional string`

    URL of attached media

  - `message_handle: optional string`

    Unique identifier for tracking the message

  - `number: optional string`

    Recipient phone number

  - `send_style: optional "celebration" or "shooting_star" or "fireworks" or 10 more`

    The iMessage expressive message style

    - `"celebration"`

    - `"shooting_star"`

    - `"fireworks"`

    - `"lasers"`

    - `"love"`

    - `"confetti"`

    - `"balloons"`

    - `"spotlight"`

    - `"echo"`

    - `"invisible"`

    - `"gentle"`

    - `"loud"`

    - `"slam"`

  - `status: optional "QUEUED" or "SENT" or "DELIVERED" or "ERROR"`

    - `"QUEUED"`

    - `"SENT"`

    - `"DELIVERED"`

    - `"ERROR"`

### Example

```http
curl https://api.sendblue.co/api/status \
    -H "sb-api-key-id: $SENDBLUE_API_API_KEY" \
    -H "sb-api-secret-key: $SENDBLUE_API_API_SECRET"
```

## Domain Types

### Message Content

- `MessageContent = object { account_email, content, date_created, 9 more }`

  - `account_email: optional string`

    Email of the account

  - `content: optional string`

    Message content

  - `date_created: optional string`

    When the message was created

  - `date_sent: optional string`

    When the message was sent

  - `date_updated: optional string`

    When the message was last updated

  - `from_number: optional string`

    Sender phone number

  - `is_outbound: optional boolean`

    Whether this is an outbound message

  - `media_url: optional string`

    URL of attached media

  - `message_handle: optional string`

    Unique message identifier

  - `send_style: optional "celebration" or "shooting_star" or "fireworks" or 10 more`

    - `"celebration"`

    - `"shooting_star"`

    - `"fireworks"`

    - `"lasers"`

    - `"love"`

    - `"confetti"`

    - `"balloons"`

    - `"spotlight"`

    - `"echo"`

    - `"invisible"`

    - `"gentle"`

    - `"loud"`

    - `"slam"`

  - `status: optional "QUEUED" or "SENT" or "DELIVERED" or 2 more`

    - `"QUEUED"`

    - `"SENT"`

    - `"DELIVERED"`

    - `"ERROR"`

    - `"RECEIVED"`

  - `to_number: optional string`

    Recipient phone number

### Message Response

- `MessageResponse = object { account_email, content, date_created, 10 more }`

  - `account_email: optional string`

    Email of the account that sent the message

  - `content: optional string`

    Message content

  - `date_created: optional string`

    When the message was created

  - `date_updated: optional string`

    When the message was last updated

  - `error_code: optional number`

    Numeric error code if message failed

  - `error_message: optional string`

    Error message if message failed

  - `from_number: optional string`

    Sending phone number

  - `is_outbound: optional boolean`

    Whether this is an outbound message

  - `media_url: optional string`

    URL of attached media

  - `message_handle: optional string`

    Unique identifier for tracking the message

  - `number: optional string`

    Recipient phone number

  - `send_style: optional "celebration" or "shooting_star" or "fireworks" or 10 more`

    The iMessage expressive message style

    - `"celebration"`

    - `"shooting_star"`

    - `"fireworks"`

    - `"lasers"`

    - `"love"`

    - `"confetti"`

    - `"balloons"`

    - `"spotlight"`

    - `"echo"`

    - `"invisible"`

    - `"gentle"`

    - `"loud"`

    - `"slam"`

  - `status: optional "QUEUED" or "SENT" or "DELIVERED" or "ERROR"`

    - `"QUEUED"`

    - `"SENT"`

    - `"DELIVERED"`

    - `"ERROR"`