Replies & Conversations

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

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

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.

Python
cURL

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']}")

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"

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

{
  "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.

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.

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.

Python
cURL

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']}")

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!"}'

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)

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

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.

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.

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`

Getting Started

Authentication

Campaigns

Sender Accounts

Domains

Leads

Replies

Analytics

Reference

Compliance

Replies & Conversations

API Endpoints

List Conversations

Query Parameters

Response Format

Get Thread Details

Get Thread Messages

Send a Reply

Request Body

Mark Thread as Read

Star / Unstar a Thread

Required Scopes

​API Endpoints

​List Conversations

​Query Parameters

​Response Format

​Get Thread Details

​Get Thread Messages

​Send a Reply

​Request Body

​Mark Thread as Read

​Star / Unstar a Thread

​Required Scopes

API Endpoints

List Conversations

Query Parameters

Response Format

Get Thread Details

Get Thread Messages

Send a Reply

Request Body

Mark Thread as Read

Star / Unstar a Thread

Required Scopes