> ## 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) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.