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

# Replies & Conversations

> Read reply threads, send replies, and manage conversation state via the ColdSend API.

The Replies API gives you full access to your unified inbox — threads from both campaign replies and direct inbound emails. Use it to build custom CRM workflows, automate reply routing, or surface conversation context in your own product.

## API Endpoints

| Method    | Endpoint                                | Description                                    |
| --------- | --------------------------------------- | ---------------------------------------------- |
| **GET**   | `/replies`                              | List all conversations (paginated, filterable) |
| **GET**   | `/replies/threads/{thread_id}`          | Get full thread details and messages           |
| **GET**   | `/replies/threads/{thread_id}/messages` | Get messages in a thread                       |
| **POST**  | `/replies/threads/{thread_id}/reply`    | Send a reply to a thread                       |
| **PATCH** | `/replies/threads/{thread_id}/read`     | Mark a thread as read/unread                   |
| **PATCH** | `/replies/threads/{thread_id}/star`     | Star or unstar a thread                        |

<Info>
  All reply endpoints require the `replies:read`, `replies:create`, or `replies:update` scope depending on the operation. Use `replies:all` to grant full access.
</Info>

## List Conversations

`GET /api/public/v1/replies`

Returns a paginated list of reply threads across your workspace. Supports filtering by campaign, read status, category, and starred state.

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    import requests

    response = requests.get(
        "https://api.coldsend.pro/api/public/v1/replies",
        headers={"X-API-Key": api_key},
        params={
            "page": 1,
            "limit": 20,
            "is_read": False,       # unread only
            "is_starred": False,
            "category": "interested"
        }
    )

    data = response.json()
    print(f"Total threads: {data['total_count']}")
    print(f"Unread: {data['unread_count']}")
    for thread in data["conversations"]:
        print(f"  [{thread['lead_email']}] {thread['subject']} — {thread['last_message_preview']}")
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl "https://api.coldsend.pro/api/public/v1/replies?page=1&limit=20&is_read=false" \
      -H "X-API-Key: cs_live_your_api_key_here"
    ```
  </Tab>
</Tabs>

### Query Parameters

| Parameter     | Type   | Description                                                     |
| ------------- | ------ | --------------------------------------------------------------- |
| `page`        | int    | Page number (default: 1)                                        |
| `limit`       | int    | Items per page (1-100, default: 20)                             |
| `campaign_id` | UUID   | Filter threads by campaign                                      |
| `is_read`     | bool   | Filter by read status                                           |
| `is_starred`  | bool   | Filter starred threads                                          |
| `category`    | string | Filter by intent category (e.g. `interested`, `not_interested`) |

### Response Format

```json theme={null}
{
  "success": true,
  "conversations": [
    {
      "thread_id": "550e8400-e29b-41d4-a716-446655440000",
      "lead_id": "660e8400-e29b-41d4-a716-446655440001",
      "inbox_id": "770e8400-e29b-41d4-a716-446655440002",
      "lead_email": "jane@acme.com",
      "lead_name": "Jane Doe",
      "campaign_name": "Q1 Product Launch",
      "subject": "Re: Quick question about Acme",
      "last_message_preview": "Thanks for reaching out, I'd like to learn more...",
      "last_message_at": "2024-01-15T14:30:00Z",
      "is_read": false,
      "is_starred": false,
      "reply_count": 2,
      "category": "interested"
    }
  ],
  "total_count": 48,
  "page": 1,
  "limit": 20,
  "unread_count": 12,
  "starred_count": 3
}
```

## Get Thread Details

`GET /api/public/v1/replies/threads/{thread_id}`

Returns full metadata for a thread including lead info, campaign context, and message history.

```python theme={null}
response = requests.get(
    f"https://api.coldsend.pro/api/public/v1/replies/threads/{thread_id}",
    headers={"X-API-Key": api_key}
)
```

## Get Thread Messages

`GET /api/public/v1/replies/threads/{thread_id}/messages`

Returns the individual messages in a thread in chronological order.

```python theme={null}
response = requests.get(
    f"https://api.coldsend.pro/api/public/v1/replies/threads/{thread_id}/messages",
    headers={"X-API-Key": api_key}
)
```

## Send a Reply

`POST /api/public/v1/replies/threads/{thread_id}/reply`

Sends a reply within an existing thread. The system automatically routes it through the correct inbox, cancels pending sequences for that lead, and threads the message.

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    response = requests.post(
        f"https://api.coldsend.pro/api/public/v1/replies/threads/{thread_id}/reply",
        headers={"X-API-Key": api_key},
        json={
            "body": "Hi Jane, thanks for your interest! Happy to set up a call.",
            "html_body": "<p>Hi Jane, thanks for your interest! Happy to set up a call.</p>"
        }
    )

    result = response.json()
    print(f"Message sent: {result['message_id']}")
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST "https://api.coldsend.pro/api/public/v1/replies/threads/{thread_id}/reply" \
      -H "X-API-Key: cs_live_your_api_key_here" \
      -H "Content-Type: application/json" \
      -d '{"body": "Hi Jane, happy to set up a call!"}'
    ```
  </Tab>
</Tabs>

### Request Body

| Field         | Type   | Required | Description                           |
| ------------- | ------ | -------- | ------------------------------------- |
| `body`        | string | Yes      | Plain text reply body                 |
| `html_body`   | string | No       | HTML version of the reply             |
| `attachments` | array  | No       | File attachments (max 5, 10 MB total) |

<Warning>
  Sending a reply automatically cancels any pending follow-up sequences for that lead within the campaign.
</Warning>

## Mark Thread as Read

`PATCH /api/public/v1/replies/threads/{thread_id}/read`

Marks a thread as read (or unread). Useful for syncing read state with your own CRM.

```python theme={null}
response = requests.patch(
    f"https://api.coldsend.pro/api/public/v1/replies/threads/{thread_id}/read",
    headers={"X-API-Key": api_key}
)
```

## Star / Unstar a Thread

`PATCH /api/public/v1/replies/threads/{thread_id}/star`

Toggles the starred state of a thread.

```python theme={null}
response = requests.patch(
    f"https://api.coldsend.pro/api/public/v1/replies/threads/{thread_id}/star",
    headers={"X-API-Key": api_key}
)
```

## Required Scopes

| Operation                                            | Required Scope   |
| ---------------------------------------------------- | ---------------- |
| List conversations, get thread details, get messages | `replies:read`   |
| Send a reply                                         | `replies:create` |
| Mark as read, star/unstar                            | `replies:update` |
| All reply operations                                 | `replies:all`    |