List Conversations

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": "[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
  }
}