---
title: Messages | Sendblue Docs
description: Query, filter, and manage messages
---

The messages API provides endpoints to list, retrieve, and delete messages from your account.

## List Messages

```
GET /api/v2/messages
```

Retrieve messages with filtering and pagination.

### Query Parameters

| Parameter         | Type    | Default     | Description                 |
| ----------------- | ------- | ----------- | --------------------------- |
| `limit`           | integer | 100         | Results per page (1-100)    |
| `offset`          | integer | 0           | Pagination offset           |
| `order_by`        | string  | `createdAt` | Sort field                  |
| `order_direction` | string  | `desc`      | `asc` or `desc`             |
| `status`          | string  | —           | Filter by status            |
| `service`         | string  | —           | `iMessage`, `SMS`, or `RCS` |
| `is_outbound`     | boolean | —           | `true` or `false`           |
| `message_type`    | string  | —           | `message` or `group`        |
| `from_number`     | string  | —           | Sender phone                |
| `to_number`       | string  | —           | Recipient phone             |
| `number`          | string  | —           | Either party’s phone        |
| `group_id`        | string  | —           | Filter by group             |
| `sendblue_number` | string  | —           | Your Sendblue number        |
| `created_at_gte`  | string  | —           | Created after (ISO 8601)    |
| `created_at_lte`  | string  | —           | Created before (ISO 8601)   |
| `sent_at_gte`     | string  | —           | Sent after (ISO 8601)       |
| `sent_at_lte`     | string  | —           | Sent before (ISO 8601)      |

### Example

Terminal window

```
curl "https://api.sendblue.co/api/v2/messages?service=iMessage&is_outbound=true&limit=50" \
  -H "sb-api-key-id: YOUR_API_KEY" \
  -H "sb-api-secret-key: YOUR_API_SECRET"
```

### Response

```
{
  "status": "OK",
  "data": [
    {
      "message_handle": "5a17319e-cbcf-443e-897e-d8b0c04b1b09",
      "accountEmail": "user@example.com",
      "content": "Hello",
      "from_number": "+15551234567",
      "to_number": "+19998887777",
      "number": "+19998887777",
      "status": "DELIVERED",
      "service": "iMessage",
      "is_outbound": true,
      "date_sent": "2025-01-15T10:30:00.000Z",
      "date_updated": "2025-01-15T10:30:05.000Z",
      "media_url": "",
      "was_downgraded": false,
      "message_type": "message",
      "group_id": "",
      "group_display_name": "",
      "send_style": ""
    }
  ],
  "pagination": {
    "limit": 100,
    "offset": 0,
    "total": 1
  }
}
```

## Get Message

```
GET /api/v2/messages/:message_id
```

Retrieve a single message by ID.

Terminal window

```
curl "https://api.sendblue.co/api/v2/messages/5a17319e-cbcf-443e-897e-d8b0c04b1b09" \
  -H "sb-api-key-id: YOUR_API_KEY" \
  -H "sb-api-secret-key: YOUR_API_SECRET"
```

## Delete Message

```
DELETE /api/message/:message_handle
```

Remove a message from the Sendblue database.

**Note:** This is a soft delete. It removes the message from Sendblue’s database only. It does **not** unsend or recall the message from the recipient’s device.

Terminal window

```
curl -X DELETE "https://api.sendblue.co/api/message/5a17319e-cbcf-443e-897e-d8b0c04b1b09" \
  -H "sb-api-key-id: YOUR_API_KEY" \
  -H "sb-api-secret-key: YOUR_API_SECRET"
```

### Response

```
{
  "status": "OK",
  "message": "Message deleted"
}
```

## Message Statuses

| Status       | Description                     |
| ------------ | ------------------------------- |
| `QUEUED`     | Message queued for sending      |
| `PENDING`    | Message being processed         |
| `SENT`       | Message sent to carrier         |
| `DELIVERED`  | Message delivered to recipient  |
| `ERROR`      | Delivery failed                 |
| `DECLINED`   | Message rejected by system      |
| `RECEIVED`   | Inbound message received        |
| `ACCEPTED`   | Message accepted for processing |
| `SUCCESS`    | Message processed successfully  |
| `REGISTERED` | Message registered in system    |

## Message Object

| Field                | Type    | Description                     |
| -------------------- | ------- | ------------------------------- |
| `message_handle`     | string  | Unique message ID               |
| `content`            | string  | Message text                    |
| `from_number`        | string  | Sender phone (E.164)            |
| `to_number`          | string  | Recipient phone (E.164)         |
| `status`             | string  | Current status                  |
| `service`            | string  | `iMessage`, `SMS`, or `RCS`     |
| `is_outbound`        | boolean | True if sent, false if received |
| `date_sent`          | string  | Send timestamp (ISO 8601)       |
| `date_updated`       | string  | Last update (ISO 8601)          |
| `media_url`          | string  | CDN URL for attachments         |
| `was_downgraded`     | boolean | True if fell back to SMS        |
| `message_type`       | string  | `message` or `group`            |
| `group_id`           | string  | Group identifier                |
| `participants`       | array   | Phone numbers in conversation   |
| `send_style`         | string  | iMessage effect used            |
| `opted_out`          | boolean | Recipient opted out             |
| `sendblue_number`    | string  | Your Sendblue number            |
| `number`             | string  | Contact phone number            |
| `accountEmail`       | string  | Account email                   |
| `group_display_name` | string  | Display name for group chats    |
| `error_code`         | integer | Error code if failed            |
| `error_message`      | string  | Error description               |
| `error_reason`       | string  | Machine-readable error          |
| `error_detail`       | string  | Additional error context        |