> ## Documentation Index
> Fetch the complete documentation index at: https://docs.outbound.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Work the inbox

> Read the conversations on your mailboxes and LinkedIn seats, keep them in order, and answer them.

The inbox holds the conversations of your sending accounts: the email threads of your mailboxes and the LinkedIn chats of your seats. A mailbox's existing mail comes in from the moment it connects, not only the replies to your campaigns. You can read conversations, mark, star, archive and label them, reply, start new ones, and invite people to connect on LinkedIn. Every inbox call is free.

## List conversations

Every list is of one channel, so `channel` is required: `email` or `linkedin`. A call without it answers `422`.

```bash theme={null}
curl "https://api.outbound.dev/v1/conversations?channel=email&folder=inbox&pageSize=25" \
  -H "Authorization: Bearer $OUTBOUND_API_KEY"
```

```json theme={null}
{
  "data": [
    {
      "id": "c210cDptYXlhQGZlcm53YXkuY286MTg5YzQ",
      "channel": "email",
      "mailbox": "maya@fernway.co",
      "subject": "Your Lisbon fleet",
      "participants": ["maya@fernway.co", "ana.costa@example.com"],
      "messageCount": 2,
      "unreadCount": 1,
      "labels": [],
      "lastMessage": {
        "messageId": "18f3c2a9b7d41e02",
        "direction": "received",
        "from": { "name": "Ana Costa", "address": "ana.costa@example.com" },
        "text": "Happy to talk on Thursday.",
        "sentAt": "2026-11-17T15:20:00.000Z"
      }
    }
  ],
  "pagination": { "pageSize": 25, "nextCursor": "MjoyNQ", "total": 221 }
}
```

Conversations come newest first. Narrow them with:

| Parameter | What it keeps |
| - | - |
| `folder` | Email: `inbox` (the default), `sent`, `unread`, `favorite`, `archived`, `spam` or `trash`. LinkedIn: `inbox` (the default, every chat) or `unread`. |
| `campaignId` | One campaign's conversations. |
| `since`, `to` | Conversations with a message in that time, as ISO 8601 date-times. |
| `search` | Email: names, addresses, the subject and the text. LinkedIn: the other person's name. |
| `mailbox` | Email: one mailbox, or up to 20 separated by commas. |
| `repliesOnly` | Email: with `true`, the conversations where the other side wrote back. |
| `accountId` | LinkedIn: one seat, by its `id`. |

For the next page, send `pagination.nextCursor` as `cursor`, with the same filters. See [Pagination](https://docs.outbound.dev/pagination.md#campaigns-leads-the-queue-and-conversations).

## Count conversations

`GET /v1/conversations/counts` answers how many email conversations each folder holds. `folders` picks the folders, separated by commas, and `mailbox` the mailboxes:

```bash theme={null}
curl "https://api.outbound.dev/v1/conversations/counts?folders=inbox,unread" \
  -H "Authorization: Bearer $OUTBOUND_API_KEY"
```

```json theme={null}
{ "counts": { "inbox": 221, "unread": 7 } }
```

`unread` counts the conversations with an email not yet read. On LinkedIn, the unread count is the `pagination.total` of `GET /v1/conversations?channel=linkedin&folder=unread&pageSize=1`.

## Read a conversation

Send the conversation's `channel` with it:

```bash theme={null}
curl "https://api.outbound.dev/v1/conversations/c210cDptYXlhQGZlcm53YXkuY286MTg5YzQ?channel=email" \
  -H "Authorization: Bearer $OUTBOUND_API_KEY"
```

```json theme={null}
{
  "id": "c210cDptYXlhQGZlcm53YXkuY286MTg5YzQ",
  "channel": "email",
  "mailbox": "maya@fernway.co",
  "subject": "Your Lisbon fleet",
  "participants": ["maya@fernway.co", "ana.costa@example.com"],
  "labels": [],
  "messages": [
    {
      "messageId": "18f3c2a9b7d41e01",
      "direction": "sent",
      "from": { "name": "Maya Fern", "address": "maya@fernway.co" },
      "to": [{ "name": "Ana Costa", "address": "ana.costa@example.com" }],
      "subject": "Your Lisbon fleet",
      "body": "<p>Hi Ana,</p><p>Saw Northwind Freight runs trucks out of Lisbon. Worth a short call?</p>",
      "isRead": true,
      "sentAt": "2026-11-17T09:35:00.000Z"
    },
    {
      "messageId": "18f3c2a9b7d41e02",
      "direction": "received",
      "from": { "name": "Ana Costa", "address": "ana.costa@example.com" },
      "to": [{ "name": "Maya Fern", "address": "maya@fernway.co" }],
      "subject": "Re: Your Lisbon fleet",
      "body": "<p>Happy to talk on Thursday.</p>",
      "isRead": false,
      "sentAt": "2026-11-17T15:20:00.000Z"
    }
  ]
}
```

Messages come oldest first. An email message carries its sender, recipients, subject, HTML body, labels and attachment names, and its `messageId`, which a reply takes as `inReplyToMessageId`. A LinkedIn message carries its `text`, its `sender` and when it was sent. A conversation your organization does not have answers `404` `conversation_not_found`.

## Mark, star, archive and label

`PATCH /v1/conversations/{conversationId}` changes one conversation. Send its `channel` and the changes:

```bash theme={null}
curl -X PATCH https://api.outbound.dev/v1/conversations/c210cDptYXlhQGZlcm53YXkuY286MTg5YzQ \
  -H "Authorization: Bearer $OUTBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"channel": "email", "isRead": true, "label": "interested"}'
```

```json theme={null}
{ "id": "c210cDptYXlhQGZlcm53YXkuY286MTg5YzQ", "channel": "email", "isRead": true, "label": "interested" }
```

| Field | What it does |
| - | - |
| `isRead` | Marks every message read, or with `false` unread. |
| `isFavorite` | Stars the conversation, or with `false` takes the star off. |
| `isArchived` | Moves it to Archived, or with `false` back to the inbox. |
| `isSpam` | Moves it to Spam, or with `false` back to the inbox. |
| `isDeleted` | Moves it to Trash, or with `false` back to the inbox. |
| `label` | Labels the newest email received `interested` or `not_interested`, or with `null` takes both off. |

* **Changes reach the mail provider too,** so the mailbox itself shows them. Each takes 2 to 5 seconds.
* **One move a call.** `isArchived`, `isSpam` and `isDeleted` each move the conversation, and a call takes only one of them: two answer `422`.
* **A label needs an email received.** A conversation with none answers `422` `conversation_has_no_received_email`.
* **Back to the inbox means the inbox:** taking a conversation out of Archived puts it in the inbox, even one that was only in Sent.
* **A LinkedIn chat can only be marked read,** with `isRead` true.
* Changes have their own limit: 30 a minute and 1,000 a day.

### Change many at once

`PATCH /v1/conversations` makes one change to 1 to 50 email conversations:

```bash theme={null}
curl -X PATCH https://api.outbound.dev/v1/conversations \
  -H "Authorization: Bearer $OUTBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"conversationIds": ["c210cDptYXlhQGZlcm53YXkuY286MTg5YzQ", "c210cDptYXlhQGZlcm53YXkuY286MTlhMDc"], "isArchived": true}'
```

```json theme={null}
{
  "results": [
    { "id": "c210cDptYXlhQGZlcm53YXkuY286MTg5YzQ", "status": "updated" },
    { "id": "c210cDptYXlhQGZlcm53YXkuY286MTlhMDc", "status": "updated" }
  ]
}
```

Each conversation comes back, in the order sent, with a `status`: `updated`, `not_found`, `too_large` (more emails than one change can touch), `needs_reconnect` (its mailbox must be connected again) or `failed`. An id your organization does not have is `not_found`, not an error. LinkedIn chats change one at a time. Bulk changes have their own limit: 20 a minute and 300 a day.

## Reply

```bash theme={null}
curl https://api.outbound.dev/v1/conversations/c210cDptYXlhQGZlcm53YXkuY286MTg5YzQ/reply \
  -H "Authorization: Bearer $OUTBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9b2f4c1a-6d3e-4f8a-b5c7-2e1d0a9f8b7c" \
  -d '{"channel": "email", "content": "<p>Thursday at 10:00 works. Talk then.</p>"}'
```

```json theme={null}
{ "channel": "email", "conversationId": "c210cDptYXlhQGZlcm53YXkuY286MTg5YzQ", "messageId": "18f3c2a9b7d41e09", "status": "sent" }
```

* **An email reply** goes from the conversation's mailbox to the sender of the message it answers, `inReplyToMessageId` or the newest, in the same thread and under the same subject, with any `cc` and `bcc`. Write it in HTML, with each paragraph in a `<p>`.
* **A LinkedIn reply** is a message in the chat, in plain text, up to 8,000 characters.
* **It goes at once, and cannot be taken back.** An email reply uses one of the mailbox's emails for the day.
* **Retrying is safe with a key.** Send the same `Idempotency-Key` with every try, and the reply goes out once. See [Idempotency](https://docs.outbound.dev/idempotency.md).
* **When it is refused, nothing is sent:** `422` `recipient_unsubscribed` when the recipient unsubscribed from the mailbox's emails, `422` `mailbox_needs_reconnect` when the mailbox's sign-in lapsed, `404` `message_not_found` when `inReplyToMessageId` is not in the conversation.

## Start a new conversation

### An email

`POST /v1/messages` sends an email from one of your mailboxes, `from`, to 1 to 50 recipients:

```bash theme={null}
curl https://api.outbound.dev/v1/messages \
  -H "Authorization: Bearer $OUTBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4d6e8f0a-1b2c-4d3e-8f5a-6b7c8d9e0f1a" \
  -d '{"channel": "email", "from": "maya@fernway.co", "to": ["ana.costa@example.com"], "subject": "Your Lisbon fleet", "content": "<p>Hi Ana, saw Northwind runs 40 trucks out of Lisbon. Worth a short call?</p>"}'
```

```json theme={null}
{ "channel": "email", "conversationId": "c210cDptYXlhQGZlcm53YXkuY286MTlhMDc", "messageId": "18f3c2a9b7d41e11", "status": "sent" }
```

* **It goes at once,** unless you send `scheduledAt`: then it waits until that time, and its `status` is `scheduled`. Closing your organization cancels the scheduled emails that have not gone out, and reopening it does not bring them back.
* **`from` is one of your mailboxes,** as `GET /v1/accounts?channel=email` lists it. One you do not have answers `404` `account_not_found`.
* **It uses one of the mailbox's emails for the day,** and cannot be taken back.

### A LinkedIn message

```bash theme={null}
curl https://api.outbound.dev/v1/messages \
  -H "Authorization: Bearer $OUTBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"channel": "linkedin", "accountId": "sBzWb1QeTTqF0vUpHKa2xg", "linkedinUrl": "https://www.linkedin.com/in/ana-costa", "content": "Thanks for connecting, Ana. Is a short call about your Lisbon fleet worth it?"}'
```

A LinkedIn message goes from one of your seats, `accountId`, to a connection of the seat, in plain text. With `"inMail": true`, and a `subject` if you like, it goes as an InMail instead: it reaches someone the seat is not connected to, and spends one of the seat's InMail credits. InMail needs a Premium, Sales Navigator or Recruiter seat: any other answers `422` `linkedin_inmail_not_available`.

## Invite someone on LinkedIn

```bash theme={null}
curl https://api.outbound.dev/v1/linkedin/invitations \
  -H "Authorization: Bearer $OUTBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"accountId": "sBzWb1QeTTqF0vUpHKa2xg", "linkedinUrl": "https://www.linkedin.com/in/ana-costa", "note": "Hi Ana, we both work on freight in Lisbon."}'
```

```json theme={null}
{
  "id": "7263504611092541440",
  "accountId": "sBzWb1QeTTqF0vUpHKa2xg",
  "publicIdentifier": "ana-costa",
  "linkedinUrl": "https://www.linkedin.com/in/ana-costa"
}
```

* **The note is optional,** up to 200 characters.
* **LinkedIn refuses a second invitation** to someone the seat invited recently: `409` `linkedin_invitation_already_sent`. One past the seat's allowance answers `422` `linkedin_invitation_limit_reached`.
* **A seat's allowances** are set on the seat: see [Connect sending accounts](https://docs.outbound.dev/guides/connect-sending-accounts.md#connect-a-linkedin-seat).

## Keys and limits

* **Keys.** The inbox comes with the campaigns scope. Read-only keys can list, count and read conversations. Changes and sends need a key that can write. A LinkedIn seat that may be used in campaigns only cannot be read or sent from here: `403` `linkedin_permission_denied`.
* **Rate limits.** Reading conversations and their counts: 60 calls a minute and 5,000 a day. Changing one conversation: 30 a minute and 1,000 a day. Bulk changes: 20 a minute and 300 a day. Replies, new messages and invitations share one more: 20 a minute and 600 a day. Each mailbox and seat also keeps its own daily allowance. See [Rate limits](https://docs.outbound.dev/rate-limits.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.