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