Get Threads - Puffle Docs

CLI:

puffle thread

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

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.

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

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Response

Successful response.

​Overview

​Query Parameters

​Example

​Correspondence Lookup

​AI agent notes