Skip to main content
GET
/
v1
/
identities
/
{handle}
/
conversations
/
{convId}
Get one conversation
curl --request GET \
  --url https://api.inboxbase.ai/v1/identities/{handle}/conversations/{convId} \
  --header 'Authorization: Bearer <token>'
{
  "identity": "<string>",
  "conversation": {
    "id": "<string>",
    "with": "<string>",
    "subject": "<string>",
    "messageCount": 123,
    "archived": true,
    "labels": [
      "<string>"
    ],
    "lastEventAt": 123,
    "lastEventAtIso": "2023-11-07T05:31:56Z",
    "noReplyAt": 123,
    "noReplyAtIso": "2023-11-07T05:31:56Z",
    "lastNoReplyAt": 123,
    "lastNoReplyAtIso": "2023-11-07T05:31:56Z",
    "events": [
      {
        "type": "message",
        "ts": 123,
        "message": {
          "id": "<string>",
          "from": "<string>",
          "to": "<string>",
          "cc": "<string>",
          "subject": "<string>",
          "text": "<string>",
          "html": "<string>",
          "snippet": "<string>",
          "ts": 123
        },
        "tsIso": "2023-11-07T05:31:56Z"
      }
    ]
  }
}
events[] is a discriminated-union timeline. The discriminator is always type. Today the union includes:
TypeWhat it is
messageA message sent or received. Body, direction, snippet, timestamps.
no_reply_expiredThe no-reply timer fired without a reply. Carries waitedMs.
label_addedA label was added (today, dashboard-only).
label_removedA label was removed.
archived / unarchivedThe conv was archived or unarchived.
To pull just the messages from the timeline: 
const messages = conv.events
  .filter((e) => e.type === "message")
  .map((e) => e.message);
Same idea for filtering to no-reply expirations, label changes, etc.

​
Snapshot, not subscription

This endpoint serves a fresh snapshot every call, off the materialized state inside the durable object that owns the conversation. There is no “give me the diff since last read” — and you don’t need one. The pattern we want you to use is:
  • Events stream tells you something changed on convId X.
  • GET /conversations/:convId gives you the current state.
You never reduce events into your own copy of the thread. We’re the reducer. See Live thread list.

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"

​
convId
string
required

Conversation id.

Pattern: ^conv_[0-9a-f]+$

Response

Conversation snapshot.

​
identity
string
​
conversation
object