GET /api/v1/inbox/threads

Returns one row per conversation, newest activity first, the same rows the Emails page shows. Requires the read:emails scope (or * for full access).

Request

GET /api/v1/inbox/threads?folder=inbox&assignee=unassigned&state=open&limit=25 HTTP/1.1
Host: agentlyleads.com
Authorization: Bearer alk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Query parameters

Parameter	Default	Description
`folder`	`inbox`	`inbox`, `snoozed`, `archived`, `sent`, `drafts`, `all`, `bulk`, `spam` or `trash`. See places and states
`assignee`	`any`	`any`, `unassigned`, `me`, or a user ID in this workspace
`state`	`any`	`any`, `open` or `closed`
`waiting`		`true` keeps only open conversations whose last message is from the customer
`mailboxId`		Only conversations in this connected mailbox
`tagId`		Only conversations carrying this tag
`q`		Search text, the same syntax as the inbox search box (`from:`, `subject:` and so on)
`asUserId`		Who `assignee=me` means. Must be an active user in this workspace. An API key belongs to the workspace, not a person, so `me` needs this
`limit`	`50`	1 to 200
`cursor`		The `nextCursor` from the previous page, unchanged

Response: 200

{
  "threads": [
    {
      "threadKey": "18c2f0a9b1d4e5f6",
      "latestMessageId": "cmq5mail0alk34567890",
      "subject": "Pricing for 500 units",
      "snippet": "Hi, could you send pricing for 500 units delivered to Toronto?",
      "messageCount": 1,
      "unreadCount": 1,
      "lastAt": "2026-09-27T14:02:00.000Z",
      "latestDirection": "INBOUND",
      "state": "OPEN",
      "assignee": null,
      "tags": [],
      "aging": { "waitingOnUs": true, "waitingSince": "2026-09-27T14:02:00.000Z", "waitingMins": 42, "overdue": false }
    }
  ],
  "nextCursor": "eyJ0IjoxNzU4OTgxMzIwMDAwLCJrIjoiMThjMmYwYTliMWQ0ZTVmNiJ9"
}

Rows are trimmed here for space; each carries every field on the Thread object.

Paging

When nextCursor is not null, pass it back as cursor to get the next page. It is null on the last page.

The list covers the conversations behind the workspace's most recent 1,000 messages. To reach older mail, search for it with q.

Common filters

You want	Query
New mail nobody has picked up	`folder=inbox&assignee=unassigned&state=open`
One person's open queue	`folder=all&assignee=<userId>&state=open`
Everything waiting on a reply	`folder=all&waiting=true`
Closed this week, for review	`folder=all&state=closed`