Skip to main content
GET
/
v1
/
identities
/
{handle}
/
conversations
List conversations
curl --request GET \
  --url https://api.inboxbase.ai/v1/identities/{handle}/conversations \
  --header 'Authorization: Bearer <token>'
{
  "identity": "<string>",
  "conversations": [
    {
      "id": "<string>",
      "with": "jsmith@example.com",
      "subject": "<string>",
      "snippet": "<string>",
      "messageCount": 123,
      "archived": true,
      "lastEventAt": 123,
      "lastEventAtIso": "2023-11-07T05:31:56Z",
      "createdAt": 123,
      "createdAtIso": "2023-11-07T05:31:56Z"
    }
  ],
  "nextCursor": 123
}
Returns a page of summary rows — id, correspondent, subject, snippet, message count, timestamps. Not the full timeline; for that, fetch one conversation at a time.

​
Filtering

Filters are AND-combined. Common patterns:
  • The conversation with one correspondent. ?with=morgan@example.com.
  • Everything from a domain. ?withDomain=example.com matches both morgan@example.com and bob@us.example.com.
  • Incremental polls. ?since=<lastEventAt of your previous poll> returns only threads that moved since then. Pair with the events stream for live updates.
  • Hide archived. ?archived=false.

​
Pagination

nextCursor (or null) is on every response. Pass it back as ?cursor= on the next call. The cursor is the lastEventAt of the last row in the previous page, so behavior is “give me older than this.”

​
What’s NOT in this response

  • The full timeline. Each row carries messageCount and the most recent subject / snippet. To see all messages on a conversation, fetch GET /conversations/:convId.
  • Per-conversation read state. We don’t track read state — every integrator wants different semantics. Run your own cursor on top of lastEventAt.

Authorizations

​
Authorization
string
header
required

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

Path Parameters

​
handle
string
required

Identity handle, URL-encoded.

Example:

"alice.acme@inboxbase.ai"

Query Parameters

​
archived
boolean

Filter to archived (true) or active (false) only. Omit for both.

​
with
string<email>

Exact correspondent email match.

​
withDomain
string

Suffix match on the correspondent's domain (e.g. acme.com).

​
since
integer<int64>

lastEventAt >= since (Unix milliseconds).

​
until
integer<int64>

lastEventAt <= until (Unix milliseconds).

​
cursor
integer<int64>

Pagination — lastEventAt of the last row from the previous page.

​
limit
integer
default:50

Page size, 1..200.

Required range: 1 <= x <= 200

Response

Page of conversations.

​
identity
string
​
conversations
object[]
​
nextCursor
integer<int64> | null