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: 1
page_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 address
has_first_response (boolean) - Whether a first response has been sent
search (string) - Full-text search across subject, message content, and sender/recipient emails
contact_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 number
subject (string | null) - Conversation subject line
status (string) - open, pending, on_hold, resolved, spam, or trash
priority (string) - low, medium, high, or urgent
source (string) - discord, email, portal, or webhook
contact (object | null) - Customer who initiated the conversation
- id (string) - Contact ID (UUID)
- email (string) - Contact email address
- name (string | null) - Contact display name
inbox_email (string | null) - Email address of the inbox that received the conversation
first_response_at (string | null) - ISO 8601 timestamp of the first agent response
last_message_at (string | null) - ISO 8601 timestamp of the most recent message
created_at (string) - ISO 8601 timestamp when the conversation was created
updated_at (string) - ISO 8601 timestamp when the conversation was last updated

pagination (object)

page (integer) - Current page number
page_size (integer) - Items per page
has_next_page (boolean) - Whether more results exist
has_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": "customer@example.com",
        "name": "Jane Smith"
      },
      "inbox_email": "support@yourcompany.com",
      "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
  }
}