Conversations & Inbox API

The unified inbox as an API — read threads across email and LinkedIn, classify replies with categories, detect meeting intent, and respond.

AI draft-reply endpoints are marked coming soon in Reply's reference; everything else is callable today.

Base URL: https://api.reply.io/v3
Official reference: docs.reply.io/api-reference/inbox/list-inbox-threads
OpenAPI: conversations-inbox.openapi.yaml
Markdown twin: conversations-inbox.md
Scopes: inbox:readinbox:writeinbox:operate

What it does

The Conversations & Inbox API is Reply.io’s unified inbox as a programmable surface. Every reply a sequence earns — email or LinkedIn — lands in one queue, and this API reads and acts on it: list and filter threads, get a single thread, pull its full message history, send a reply within the thread, mark threads read or unread, and delete or bulk-delete them. Classification is first-class: reply categories (interested, not interested, plus your own) have full CRUD, with operations to assign threads to a category in bulk, assign or clear a single thread’s category, and unassign threads. A meeting-intent toggle marks threads where the prospect is ready to book. Two AI endpoints — generate an AI draft reply and submit feedback on a generated draft — are marked coming soon in Reply’s reference (targeted early and late July 2026; still not live as of 2026-07-05).

The problem it solves

Reply handling is where outreach becomes revenue, and it is the step most automation stacks leave manual. Without a unified surface, an agent has to watch a mailbox over IMAP, monitor LinkedIn separately, match each incoming message back to the right contact and campaign, classify it, and keep that classification somewhere durable. This API collapses all of it: threads from both channels arrive in one queue already tied to platform contacts, categories are the built-in reply-classification store — the “Reply Classification API” capability lives here — and meeting intent is a flag on the thread, not a heuristic your agent re-derives on every pass. Responding is one in-thread call instead of an SMTP integration, so the loop from reply detected to reply answered runs in a handful of requests.

How an agent starts using it

Get an API key with the inbox:read, inbox:write, and inbox:operate scopes. Find work with POST /v3/inbox/threads/filter (unread threads, or threads in a given category), read history with GET /v3/inbox/threads/{threadId}/messages, then act: assign a category to record the classification, toggle meeting intent if the prospect asked for time, send a reply within the thread, and mark it read. For push instead of polling, pair this module with the Webhooks & Events API and fetch threads only when notified. Once the coming-soon AI draft endpoints ship, the generate-draft and draft-feedback operations slot into the same loop between reading and sending.

Typical agent tasks

Filter threads for unread replies across email and LinkedIn
Read a thread's full message history before deciding how to respond
Classify a reply by assigning a category (interested, not interested, or a custom label)
Toggle meeting intent on a thread where the prospect asks for time
Send a reply within a thread and mark it read

Inputs

Name	Type	Required	Description
`threadId`	string	yes	Thread identifier used by every thread-scoped operation (get, messages, reply, category, meeting-intent).
`filter`	ThreadFilter	no	Criteria for the Filter inbox threads operation — channel, read state, category.
`body`	string	no	Message content for the Send a reply within a thread operation.
`categoryId`	string	no	Reply category to assign, unassign, or clear on threads. Categories themselves are managed through the category CRUD endpoints.

Outputs

Name	Type	Description
`thread`	Thread	Channel, contact, subject, read state, assigned category, and meeting-intent flag.
`messages`	Message[]	Full inbound and outbound message history of a thread, across email and LinkedIn.
`category`	Category	Workspace-level reply classification label (interested, not interested, and custom values).

Authentication

API key as Bearer token. Send Authorization: Bearer <API_KEY> on every request. Get an API key in the Reply.io app under Settings → API Key — authentication reference.

Rate limits

100 requests/minute and 3,000 requests/hour per user (shared across all of the user's API clients). On 429, honor the Retry-After header.

Example

Request — POST /v3/inbox/threads/filter

curl -X POST https://api.reply.io/v3/inbox/threads/filter \
  -H "Authorization: Bearer $REPLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "unread": true, "channel": "email", "categoryId": 3 }'

Response — 200

{
  "items": [
    {
      "id": 88123,
      "channel": "email",
      "subject": "Re: Quick question about your outbound",
      "contactEmail": "[email protected]",
      "unread": true,
      "categoryId": 3,
      "meetingIntent": true,
      "lastMessageAt": "2026-07-04T08:42:00Z"
    }
  ]
}

Error — 403

{
  "type": "https://docs.reply.io/api-reference/authentication",
  "title": "Forbidden",
  "status": 403,
  "detail": "This API key does not have the required scope: inbox:read."
}

Related APIs

Modules are designed to chain — combining them is the point.

Sequence API

Create, populate, and control multichannel outreach sequences — email, LinkedIn, and calls in one campaign object.

Webhooks & Events API

Outbound event subscriptions — Reply pushes every reply, open, click, bounce, and LinkedIn event to your endpoint instead of making you poll.

AI SDR API (Jason)

Program Jason, Reply's autonomous AI SDR — feed it knowledge bases, offers, and playbooks today; run full autopilot sequences with approval gates soon.

Tasks API

Create, assign, and complete manual touch tasks — calls, LinkedIn actions, and custom to-dos — for the humans and agents on your team.

docs.reply.io ↗

Frequently asked questions

How do reply classification categories work?

Categories are workspace-level labels with full CRUD — create, get, list, update, delete. Assignment is separate — assign threads to a category in bulk, assign or clear a single thread's category, or unassign threads. Category CRUD requires the `inbox:write` scope; assignment requires `inbox:operate`. An agent classifies a reply by writing the category onto the thread, so the decision becomes durable, filterable state instead of something re-inferred on every read.

Should an agent poll the inbox or subscribe to webhooks?

Both work. For push, subscribe to reply events with the Webhooks & Events API and fetch the affected thread when notified. For pull, run Filter inbox threads with an unread filter and mark threads read as you process them — the read flag makes polling idempotent, and the same filter doubles as reconciliation if a webhook delivery is ever missed.

Are email and LinkedIn replies really in one inbox?

Yes. Threads carry a channel field, and the same list, filter, read, classify, and reply operations apply to both. Your agent handles a LinkedIn reply through the same code path as an email reply.

Start here: get an API key and make your first call, or explore workflows that combine this module with others.