Get Threads

curl --request GET \
  --url https://app.puffle.ai/api/threads \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://app.puffle.ai/api/threads', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.puffle.ai/api/threads",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://app.puffle.ai/api/threads"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://app.puffle.ai/api/threads")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

GET

api

threads

Get Threads

curl --request GET \
  --url https://app.puffle.ai/api/threads \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://app.puffle.ai/api/threads', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.puffle.ai/api/threads",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://app.puffle.ai/api/threads"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://app.puffle.ai/api/threads")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

CLI:

puffle thread
puffle thread --view <view> --channel <channel> --include <include> --search <search> --sender-id <sender-id> --account-id <account-id> --campaign-id <campaign-id> --exclude-thread-id <exclude-thread-id> --exclude-id <exclude-id> --participant-email <participant-email> --correspondence <correspondence> --status <status> --inbox-state <inbox-state> --ai-label <ai-label> --unread <unread> --bounced <bounced> --replied <replied> --page <page> --limit <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

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.

Query Parameters

view

string

Comma-separated Unibox label view. Supported values: inbox, unread, needs_reply, active_thread, sent, drafts, archived, bounced, replied, interested, not_interested, out_of_office.

channel

enum<string>

Channel filter. Use email for email threads and linkedin for LinkedIn threads.

Available options:

email,

linkedin

include

string

Optional comma-separated includes. Use include=filter_options to also return sender and outbound filter option lists.

string

Search participant and message text.

sender_id

string

Sender/account filter alias used by the Unibox UI.

account_id

string

Sender/account filter.

campaign_id

string

Outbound/campaign filter.

exclude_thread_id

string

Thread id to exclude from correspondence lookups.

exclude_id

string

Conversation id to exclude.

participant_email

string

Participant email for correspondence lookups.

correspondence

enum<string>

Set true to find existing correspondence with participant_email.

Available options:

true,

false

status

string

Lower-level lifecycle filter: active, archived, draft, warmup.

inbox_state

string

Lower-level inbox state filter: draft, needs_reply, active_thread, sent_one_off, sent_campaign, archived, warmup, empty.

ai_label

string

AI label filter: interested, not_interested, out_of_office.

unread

enum<string>

Available options:

true,

false

bounced

enum<string>

Available options:

true,

false

replied

enum<string>

Available options:

true,

false

page

integer

Required range: 0 < x <= 9007199254740991

limit

integer

Required range: 0 < x <= 100

Response

Successful response.

​Overview

​Query Parameters

​Example

​Correspondence Lookup

​AI agent notes

Authorizations

Query Parameters

Response

Overview

Query Parameters

Example

Correspondence Lookup

AI agent notes