API Reference

Inbox

Access email and messaging threads across your company. Use flows for rich conversation metadata and threads when you need the raw messages.

GET /inbox/threads

List all threads for your company, newest first.

Requires inbox:read

Query parameters

Name	Type	Required	Description
`limit`	integer	optional	Max threads to return (default 50)

Response

{
  "threads": [
    {
      "threadId": "55274d36-7b41-486c-ab88-4b55f25f7fe1",
      "unreadCount": 1
    }
  ],
  "count": 6
}

GET /inbox/threads/{threadId}

Fetch all messages in a single thread, ordered by timestamp ascending.

Requires inbox:read

Response

{
  "threadId": "55274d36-7b41-486c-ab88-4b55f25f7fe1",
  "messages": [
    {
      "MessageId": "seed-03d8dfcb-...",
      "Channel": "email",
      "Direction": "incoming",
      "From": "marcus.j@apexretail.com",
      "To": ["brad@waverlystudio.com"],
      "Subject": "Wholesale Partnership — Apex Retail",
      "Body": "Hello, Apex Retail operates 12 locations...",
      "Timestamp": 1781479909627,
      "IsUnread": false
    }
  ],
  "count": 4
}

GET /inbox/flows

List conversation flows with full metadata. Optionally filter by contact to build a customer timeline.

Requires inbox:read

Query parameters

Name	Type	Required	Description
`contactId`	string	optional	Filter flows linked to a specific contact
`limit`	integer	optional	Max flows to return (default 50)

Response

{
  "flows": [
    {
      "flowId": "55274d36-7b41-486c-ab88-4b55f25f7fe1",
      "subject": "Wholesale Partnership — Apex Retail",
      "Channel": "email",
      "contactIdentifier": "marcus.j@apexretail.com",
      "contactName": "Marcus Johnson",
      "participants": ["marcus.j@apexretail.com", "brad@waverlystudio.com"],
      "lastMessageAt": 1781609509627,
      "messageCount": 4,
      "status": "resolved",
      "isUnread": false
    }
  ],
  "count": 6
}

💡

Customer timeline pattern

Pass a contactId to /inbox/flows to get every conversation thread involving that contact — useful for building a CRM activity feed.

curl "https://api.usebeya.com/v1/inbox/flows?contactId=dc9e8a9f-2222-4537-a4bf-abb047049359" \
  -H "x-api-key: bk_live_your_key_here"