> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reachedapp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List SMS Messages

> Returns a paginated list of SMS messages (sent and received) with optional filters.

# List SMS Messages

Returns a paginated list of SMS messages (sent and received) with optional filters. Default sort: `created_at` DESC.

## Request

`GET /v1/sms-messages`

### Query Parameters

| Parameter      | Type    | Required | Description                                                                                                                                                         |
| -------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `page`         | integer | No       | Page number (default: 1)                                                                                                                                            |
| `per_page`     | integer | No       | Results per page, max 100 (default: 25)                                                                                                                             |
| `lead_id`      | uuid    | No       | Filter by lead ID                                                                                                                                                   |
| `direction`    | string  | No       | Filter by direction: `inbound` or `outbound`                                                                                                                        |
| `status`       | string  | No       | Filter by delivery status: `queued`, `sent`, `delivered`, `failed`, `received`, `undelivered`                                                                       |
| `phone`        | string  | No       | Filter by phone number (matches `from_number` or `to_number`) in E.164 format                                                                                       |
| `date_from`    | string  | No       | Filter messages created after this ISO 8601 timestamp                                                                                                               |
| `date_to`      | string  | No       | Filter messages created before this ISO 8601 timestamp                                                                                                              |
| `include`      | string  | No       | Set to `"lead"` to embed lead details (`first_name`, `last_name`, `email`, `phone`, `company_name`, `title`) in each message object.                                |
| `workspace_id` | uuid    | No       | Filter by workspace ID. Use the [List Workspaces](/rest-api/workspaces/list-workspaces) endpoint to get available IDs. Omit to return messages from all workspaces. |

## Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET \
    "https://kdjmltmhxvvmiuehafgl.supabase.co/functions/v1/api-gateway/v1/sms-messages?lead_id=a1b2c3d4-...&direction=outbound&per_page=25" \
    -H "Authorization: Bearer rchd_live_xxxxxxxxxxxx"
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({
    lead_id: "a1b2c3d4-...",
    direction: "outbound",
    per_page: "25"
  });

  const response = await fetch(
    `https://kdjmltmhxvvmiuehafgl.supabase.co/functions/v1/api-gateway/v1/sms-messages?${params}`,
    { headers: { "Authorization": "Bearer rchd_live_xxxxxxxxxxxx" } }
  );
  const { data, meta } = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://kdjmltmhxvvmiuehafgl.supabase.co/functions/v1/api-gateway/v1/sms-messages",
      headers={"Authorization": "Bearer rchd_live_xxxxxxxxxxxx"},
      params={"lead_id": "a1b2c3d4-...", "direction": "outbound", "per_page": 25}
  )
  result = response.json()
  ```
</CodeGroup>

### Embed lead details

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET \
    "https://kdjmltmhxvvmiuehafgl.supabase.co/functions/v1/api-gateway/v1/sms-messages?include=lead&per_page=25" \
    -H "Authorization: Bearer rchd_live_xxxxxxxxxxxx"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://kdjmltmhxvvmiuehafgl.supabase.co/functions/v1/api-gateway/v1/sms-messages?include=lead&per_page=25",
    { headers: { "Authorization": "Bearer rchd_live_xxxxxxxxxxxx" } }
  );
  const { data } = await response.json();
  // Each message now includes a "lead" object with first_name, last_name, email, phone, company_name, title
  ```
</CodeGroup>

## Response

```json theme={null}
{
  "data": [
    {
      "id": "msg-uuid-1",
      "lead_id": "a1b2c3d4-...",
      "from_number": "+33140000000",
      "to_number": "+33612345678",
      "body": "Hi John, following up on our call last week. Are you available for a quick chat tomorrow?",
      "direction": "outbound",
      "status": "delivered",
      "segment_count": 2,
      "twilio_message_sid": "SMxxxxxxx",
      "read_at": null,
      "created_at": "2026-09-14T10:00:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 1
  }
}
```

### Response Fields

| Field                | Type     | Description                                                                         |
| -------------------- | -------- | ----------------------------------------------------------------------------------- |
| `id`                 | uuid     | Message unique identifier                                                           |
| `lead_id`            | uuid     | Associated lead ID (if linked)                                                      |
| `from_number`        | string   | Sender phone number                                                                 |
| `to_number`          | string   | Recipient phone number                                                              |
| `body`               | string   | Message content                                                                     |
| `direction`          | string   | `inbound` (received) or `outbound` (sent)                                           |
| `status`             | string   | Delivery status: `queued`, `sent`, `delivered`, `failed`, `received`, `undelivered` |
| `segment_count`      | integer  | Number of SMS segments used                                                         |
| `twilio_message_sid` | string   | Twilio message SID (if applicable)                                                  |
| `read_at`            | datetime | Timestamp when the message was marked as read (if applicable)                       |
| `created_at`         | datetime | Message creation timestamp                                                          |
| `workspace_id`       | uuid     | Workspace ID the message belongs to (null = default workspace)                      |