> ## Documentation Index > Fetch the complete documentation index at: https://docs.puffle.ai/llms.txt > Use this file to discover all available pages before exploring further. # Get Threads > List Unibox threads with filters for inbox state, sender, campaign, channel, and correspondence lookup. **CLI:** ```bash theme={null} puffle thread puffle thread --view --channel --include --search --sender-id --account-id --campaign-id --exclude-thread-id --exclude-id --participant-email --correspondence --status --inbox-state --ai-label --unread --bounced --replied --page --limit ``` ## Overview Lists Unibox threads for the authenticated workspace. Threads include email and LinkedIn conversations from campaign replies, one-off outbound email, drafts, archived conversations, and warmup rows. By default, this endpoint returns active threads with inbound activity. Use `view`, `inbox_state`, `status`, `sender_id`, `campaign_id`, or `participant_email` to override that default. ## Query Parameters | Parameter | Type | Description | | ------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `view` | string | Friendly view filter. Supported values: `inbox`, `needs_reply`, `active_thread`, `sent`, `drafts`, `archived`, `unread`, `bounced`. Comma-separated values are allowed. | | `inbox_state` | string | Lower-level state filter. Supported values: `draft`, `needs_reply`, `active_thread`, `sent_one_off`, `sent_campaign`, `archived`, `warmup`, `empty`. Comma-separated values are allowed. | | `status` | string | Lifecycle status filter: `active`, `archived`, `draft`, or `warmup`. Comma-separated values are allowed. | | `unread` | boolean | Use `true` to return only threads with `unread_count > 0`. | | `bounced` | boolean | Use `true` to return bounce-like threads, or `false` to exclude bounce-like threads. | | `channel` | string | Filter to `email` or `linkedin`. | | `sender_id` | string | Sender account ID. Public alias for the underlying `account_id` filter. | | `campaign_id` | string | Campaign ID. Returns threads linked to that campaign. | | `participant_email` | string | Recipient email. Also used by correspondence lookup. | | `correspondence` | boolean | Use `true` with `participant_email` to check for existing email correspondence instead of returning the normal thread list. | | `exclude_thread_id` | string | Thread ID to omit from correspondence lookup results. | | `search` | string | Searches participant name, email, LinkedIn URL, and last-message snippet. | | `include` | string | Use `filter_options` to include available sender and campaign filter options. | | `page` | integer | Page number. Defaults to `1`. | | `limit` | integer | Page size. Defaults to `50`, max `100`. | ## Example ```bash theme={null} curl -H "Authorization: Bearer $PUFFLE_API_KEY" \ "https://app.puffle.ai/api/threads?view=sent&channel=email&limit=25&include=filter_options" ``` The response returns `threads`, `total`, `page`, and `limit`. When `include=filter_options` is present, the response also includes `filter_options.campaigns` and `filter_options.senders`. ```json theme={null} { "threads": [ { "id": "3d986dd1-9d70-45b7-8e36-5d5b8b1c9337", "channel": "email", "status": "active", "inbox_state": "sent_one_off", "participant_email": "founder@example.com", "last_message_direction": "outbound", "has_one_off_message": true } ], "total": 1, "page": 1, "limit": 25, "filter_options": { "campaigns": [], "senders": [] } } ``` ## Correspondence Lookup Use `correspondence=true&participant_email=...` before creating a one-off email draft if you need to avoid duplicate conversations. The response includes `existing_threads` and `threads` for the recipient. ## AI agent notes Use `view=needs_reply` for work that needs human or agent follow-up. Use `view=sent` to find outbound-only one-off and campaign conversations. Use `correspondence=true` before creating a one-off thread for a recipient that may already have history. ## OpenAPI ````yaml get /api/threads openapi: 3.0.3 info: title: Puffle API version: 1.0.0 description: >- HTTP API for the Puffle GTM platform - Feed and Lead Finder search preparation, campaign-backed Outbound execution, Puffle Agent runs, sender management, and Unibox reply workflows. Designed for operation by both humans and autonomous AI agents. Agents should start at the [Agent Playbook](/guides/agent-playbook) which prescribes a workspace-context check (`GET /api/context`) and core user journeys with exact call ordering. contact: name: Puffle Support url: https://puffle.ai servers: - url: https://app.puffle.ai description: Production security: - bearerAuth: [] tags: - name: Campaigns description: >- Campaign-backed Outbound execution. These endpoints manage draft, launching, active, paused, and completed Outbound runs with sequence nodes, contacts, and sender accounts. - name: Accounts description: Signed-in user account, settings, and workspace context endpoints. - name: Billing description: Billing customer portal and account billing endpoints. - name: Senders description: >- Connected sender accounts, email inboxes, sending domains, DNS verification, warmup, and sender capacity. - name: Socials description: >- Read connected LinkedIn and X accounts, review current and archived posts, and reconcile publication status. Creating, editing, scheduling, publishing, OAuth connection, analytics, and mentions remain dashboard-managed workflows and are not part of the public Bearer-token API. paths: /api/threads: get: tags: - Unibox summary: Get Threads description: Get Threads operationId: listThreads parameters: - name: view in: query required: false schema: description: >- Comma-separated Unibox label view. Supported values: inbox, unread, needs_reply, active_thread, sent, drafts, archived, bounced, replied, interested, not_interested, out_of_office. type: string - name: channel in: query required: false schema: description: >- Channel filter. Use email for email threads and linkedin for LinkedIn threads. type: string enum: - email - linkedin - name: include in: query required: false schema: description: >- Optional comma-separated includes. Use include=filter_options to also return sender and outbound filter option lists. type: string - name: search in: query required: false schema: description: Search participant and message text. type: string - name: sender_id in: query required: false schema: description: Sender/account filter alias used by the Unibox UI. type: string - name: account_id in: query required: false schema: description: Sender/account filter. type: string - name: campaign_id in: query required: false schema: description: Outbound/campaign filter. type: string - name: exclude_thread_id in: query required: false schema: description: Thread id to exclude from correspondence lookups. type: string - name: exclude_id in: query required: false schema: description: Conversation id to exclude. type: string - name: participant_email in: query required: false schema: description: Participant email for correspondence lookups. type: string - name: correspondence in: query required: false schema: description: Set true to find existing correspondence with participant_email. type: string enum: - 'true' - 'false' - name: status in: query required: false schema: description: 'Lower-level lifecycle filter: active, archived, draft, warmup.' type: string - name: inbox_state in: query required: false schema: description: >- Lower-level inbox state filter: draft, needs_reply, active_thread, sent_one_off, sent_campaign, archived, warmup, empty. type: string - name: ai_label in: query required: false schema: description: 'AI label filter: interested, not_interested, out_of_office.' type: string - name: unread in: query required: false schema: type: string enum: - 'true' - 'false' - name: bounced in: query required: false schema: type: string enum: - 'true' - 'false' - name: replied in: query required: false schema: type: string enum: - 'true' - 'false' - name: page in: query required: false schema: type: integer exclusiveMinimum: true maximum: 9007199254740991 minimum: 0 - name: limit in: query required: false schema: type: integer exclusiveMinimum: true maximum: 100 minimum: 0 responses: '200': description: Successful response. '400': description: Bad request. '401': description: Unauthorized. '403': description: Forbidden. '500': description: Internal server error. components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: pk_live_... ````