API Documentation
GET /api/v1/conversations
Returns a paginated list of conversations for your organization.
Query Parameters
Pagination
page(integer) - Page number, 1-based. Default: 1page_size(integer) - Items per page, 1-100. Default: 20
Filters (optional)
status(string) - “open”, “pending”, “on_hold”, “resolved”, “spam”, or “trash”priority(string) - “low”, “medium”, “high”, or “urgent”source(string) - “discord”, “email”, “portal”, or “webhook”inbox_email(string) - Filter by inbox email addresshas_first_response(boolean) - Whether a first response has been sentsearch(string) - Full-text search across subject, message content, and sender/recipient emailscontact_email(string) - Filter by the email of the customer who initiated the conversation
Sorting
sort(string) - “recency” (default), “oldest”, or “priority”
Response Object
data (array) - List of conversation objects
Each conversation contains:
id(string) - Unique conversation ID (UUID)display_id(integer) - Human-readable ticket numbersubject(string | null) - Conversation subject linestatus(string) -open,pending,on_hold,resolved,spam, ortrashpriority(string) -low,medium,high, orurgentsource(string) -discord,email,portal, orwebhookcontact(object | null) - Customer who initiated the conversationid(string) - Contact ID (UUID)email(string) - Contact email addressname(string | null) - Contact display name
inbox_email(string | null) - Email address of the inbox that received the conversationfirst_response_at(string | null) - ISO 8601 timestamp of the first agent responselast_message_at(string | null) - ISO 8601 timestamp of the most recent messagecreated_at(string) - ISO 8601 timestamp when the conversation was createdupdated_at(string) - ISO 8601 timestamp when the conversation was last updated
pagination (object)
page(integer) - Current page numberpage_size(integer) - Items per pagehas_next_page(boolean) - Whether more results existhas_previous_page(boolean) - Whether previous pages exist
Request Example
curl "https://api.letterbook.ai/api/v1/conversations?status=open&page_size=10" \
-H "Authorization: Bearer hld_your_api_key_here"Response Example
{
"data": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"display_id": 42,
"subject": "Issue with billing",
"status": "open",
"priority": "medium",
"source": "email",
"contact": {
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"email": "[email protected]",
"name": "Jane Smith"
},
"inbox_email": "[email protected]",
"first_response_at": "2026-04-09T14:30:00+00:00",
"last_message_at": "2026-04-09T15:45:00+00:00",
"created_at": "2026-04-09T14:00:00+00:00",
"updated_at": "2026-04-09T15:45:00+00:00"
}
],
"pagination": {
"page": 1,
"page_size": 10,
"has_next_page": true,
"has_previous_page": false
}
}