# Conversations & Inbox API

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

- **Note:** Generating an AI draft reply is callable today (beta), and so is following which threads changed since your last read without re-listing the inbox (`GET /v3/inbox/threads/changes`, read forward with a cursor). Only submitting *feedback* on a generated draft is still coming soon; targeted late November 2026. Verified 2026-11-05.
- **Category:** Conversations
- **Base URL:** `https://api.reply.io/v3`
- **Official reference:** https://docs.reply.io/api-reference/inbox/list-inbox-threads
- **OpenAPI:** https://agents.reply.io/apis/conversations-inbox.openapi.yaml
- **HTML version:** https://agents.reply.io/apis/conversations-inbox/

## 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. Generating an AI draft reply is live too, in beta. The one endpoint still coming soon is feedback on a generated draft (targeted late November 2026).

## 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. Generating an AI draft (callable today, in beta) slots into the same loop between reading and sending; the draft-feedback operation joins it once it ships.

## 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. Required scopes: `inbox:read`, `inbox:write`, `inbox:operate`. Get an API key in the Reply.io app under **Settings → API Key** (https://docs.reply.io/api-reference/authentication).

## Rate limits

100 requests/minute, 3,000 requests/hour, and 150,000 requests/week 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`

```bash
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`

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

### Error – `403`

```json
{
  "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

- [Sequence API](https://agents.reply.io/apis/sequences.md) – Create, populate, and control multichannel outreach sequences: email, LinkedIn, and calls in one campaign object.
- [Webhooks & Events API](https://agents.reply.io/apis/webhooks-events.md) – 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)](https://agents.reply.io/apis/ai-sdr.md) – Program Jason, Reply's autonomous AI SDR: knowledge bases, offers, playbooks, autopilot sequences, and the approval queue are all callable today.
- [Tasks API](https://docs.reply.io/api-reference/tasks/create-a-task) – Create, assign, and complete manual touch tasks (calls, LinkedIn actions, and custom to-dos) for the humans and agents on your team.

## FAQ

**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.
