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

# List Inbox

> Retrieve a list of conversations from the inbox.

## Overview

Returns a paginated list of conversations from the inbox. Filter by category and paginate with the `next_cursor` value.

> [!NOTE]
>
> This endpoint consumes **1 credit per 10 results** returned. The platform returns up to **25 conversations per internal request**, so larger `total_results` values trigger multiple upstream calls automatically. Ignore this if you're on per-seat pricing: usage is unlimited.

## Request

**x-api-key** `string` *required*

Your API key for authentication.

**account\_id** `string` *required*

The unique identifier of the account to use.

**action** `string` *required*

Must be `"list_inbox"`.

**params** `object`

**params properties**

**count** `integer` (default: 10)

Maximum number of conversations to return. Defaults to `10`.

**category** `string` (default: INBOX)

Filter conversations by category. One of: `"INBOX"`, `"UNREAD"`, `"MY_CONNECTIONS"`, `"INMAIL"`, `"STARRED"`. Defaults to `"INBOX"`.

**cursor** `string`

Cursor returned by a previous response as `data.next_cursor`. Omit for the first page.

**sales\_nav** `boolean` (default: false)

Read the **Sales Nav** inbox instead of the classic one. See [Sales Nav inbox](#sales-nav-inbox) below.

**recruiter** `boolean` (default: false)

Read the **Recruiter** mailbox. See [Recruiter inbox](#recruiter-inbox) below.

**unread\_only** `boolean` (default: false)

**(Email)** Only return unread emails.

> [!NOTE]
>
> Works for **email** mailboxes too — the response keeps the same shape (`conversations` / `total_results`), each email mapped to a conversation. See [Email inbox](#email-inbox) below.

## Response

**success** `boolean`

Indicates whether the request was successful.

**data** `object`

**data properties**

**conversations** `array`

List of conversation objects.

**conversation properties**

**conversation\_id** `string`

Unique identifier of the conversation. Treat it as an opaque string and pass it back exactly as returned.

**participant** `object`

The other side of the conversation. Can be a member, a company page, or — for notes-to-self — your own profile.

**participant properties**

**name** `string`

Display name (member full name or company name).

**headline** `string`

Headline (or company tagline if `is_organization`).

**profile\_url** `string`

Public profile URL (or company page URL if `is_organization`).

**profile\_picture** `string`

Profile picture URL (or company logo if `is_organization`).

**is\_organization** `boolean`

Present and `true` when the participant is a company page (e.g. sponsored premium direct messages, brand outreach). Absent for human members.

**last\_message** `object`

The most recent message in the conversation.

**last\_message properties**

**text** `string`

Plain-text content of the message.

**time** `integer`

Unix epoch timestamp in **milliseconds** when the message was sent.

**sender** `object`

Author of the last message.

**sender properties**

**name** `string`

Display name of the sender.

**headline** `string`

Headline of the sender.

**profile\_url** `string`

Public profile URL of the sender.

**profile\_picture** `string`

URL of the sender's profile picture.

**is\_me** `boolean`

`true` when the sender is the authenticated account.

**unread** `integer`

Number of unread messages in the conversation. `0` when fully read.

**type** `string`

Conversation type. Common values: `"normal"`, `"inmail"`, `"Sponsored"`.

**total\_results** `integer`

Number of conversations returned in this response.

**next\_cursor** `string`

Cursor to send as `next_cursor` in the next request to resume pagination. `null` when the end is reached.

**metadata** `object`

**metadata properties**

**action** `string`

The action that was performed (`"list_inbox"`).

**account\_id** `string`

The account ID used for the request.

**credits\_consumed** `integer`

Number of credits consumed (1 per 10 results).

**timestamp** `string`

ISO 8601 timestamp of the response.

## Sales Nav inbox

InMail threads live in a separate store and never appear in the classic inbox. Set `sales_nav: true` to read them. Same envelope and paging, with:

* `conversation_id` = the Sales Nav **thread id**, also returned as `threadId` by [Send Message](https://docs.linkupapi.com/api-reference/v2/messages/send.md). Only usable with `sales_nav: true` — the two id spaces are not interchangeable.
* `participant` / `last_message.sender` add `recipient_urn`, `sales_nav_url`, `connection_level`, `first_name`, `last_name`; no `headline`
* extra: `total_message_count`, `archived`, `last_message.subject`

```json 200 theme={null}
{
  "success": true,
  "data": {
    "conversations": [
      {
        "conversation_id": "urn:li:msg_conversation:(urn:li:fsd_profile:ACoAA...,2-MDZiY2ExOTgtM2NjNy00OTU4LTgyNjUtZWFlMmIwZjM1NTlmXzEwMA==)",
        "participant": {
          "name": "Jane Doe",
          "headline": "Founder at Acme Corp",
          "profile_url": "https://www.linkedin.com/in/jane-doe-42",
          "profile_picture": "https://media.licdn.com/dms/image/v2/.../profile.jpg"
        },
        "last_message": {
          "text": "Sounds good, talk soon!",
          "time": 1777147641366,
          "sender": {
            "name": "Jane Doe",
            "headline": "Founder at Acme Corp",
            "profile_url": "https://www.linkedin.com/in/jane-doe-42",
            "profile_picture": "https://media.licdn.com/dms/image/v2/.../profile.jpg",
            "is_me": false
          }
        },
        "unread": 0,
        "type": "normal"
      }
    ],
    "total_results": 1,
    "next_cursor": "REVTQ0VORElORyYxNzc0OTU4MDE2NjQzJjItWlRFMk1qazBaV1F0Wm1JMFlpMDBNR1k1TFRrMlptTXRaRGcwWVRjM05qUTJZakExWHpFd01BPT0="
  },
  "metadata": {
    "action": "list_inbox",
    "account_id": "your-account-id",
    "credits_consumed": 1,
    "timestamp": "2026-04-26T10:35:00Z"
  }
}
```

```json Success (Sales Nav) theme={null}
{
  "success": true,
  "data": {
    "conversations": [
      {
        "conversation_id": "2-OTQwMTJlODEtOTUxMy00NGNlLWIyNmQtMDJjYTU4MmQyMTcxXzEwMA==",
        "participant": {
          "name": "Jessica Jensen",
          "first_name": "Jessica",
          "last_name": "Jensen",
          "profile_url": "https://www.linkedin.com/in/ACwAAA...",
          "sales_nav_url": "https://www.linkedin.com/sales/lead/ACwAAA...",
          "recipient_urn": "urn:li:fs_salesProfile:(ACwAAA...,NAME_SEARCH,JUf-)",
          "profile_picture": "https://media.licdn.com/...",
          "connection_level": "2",
          "is_me": false
        },
        "last_message": {
          "text": "Thanks for reaching out. I'd like to learn more.",
          "time": 1785236943298,
          "subject": "Quick question",
          "sender": {
            "name": "Jessica Jensen",
            "recipient_urn": "urn:li:fs_salesProfile:(ACwAAA...,NAME_SEARCH,JUf-)",
            "is_me": false
          }
        },
        "unread": 0,
        "type": "inmail",
        "total_message_count": 8,
        "archived": false
      }
    ],
    "total_results": 1,
    "next_cursor": "1785228162040"
  },
  "metadata": {
    "action": "list_inbox",
    "account_id": "your-account-id",
    "credits_consumed": 1,
    "timestamp": "2026-04-28T12:00:00Z"
  }
}
```

```json 400 theme={null}
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "account_id or account_ids is required"
  },
  "metadata": {
    "action": "list_inbox",
    "account_id": null,
    "credits_consumed": 0,
    "timestamp": "2026-04-26T10:35:00Z"
  }
}
```

## Recruiter inbox

Recruiter InMails live in a third, separate store. Set `recruiter: true`. Same envelope, with:

* `folder`: `INBOX` (default), `UNREAD`, `AWAITING_REPLY`, `ACCEPTED`, `ACCEPTED_BUT_NOT_RESPONDED`, `DECLINED`, `ARCHIVED`, `CANCELED`, `SCHEDULED`
* paging with `count` + `offset` (no cursor)
* `conversation_id` = the Recruiter thread id, for [Get Conversation](https://docs.linkupapi.com/api-reference/v2/messages/get-conversation.md#recruiter-conversations) and replies
* extra: `subject`, `request_state`, `can_reply`, `archived`, `total_message_count`
* `last_message` is the thread's **opening** message (the only one LinkedIn lists) — read the rest with Get Conversation

### Inbox summary

`action: "inbox_summary"` returns the mailbox counters without listing it: `unread`, `awaiting_reply_unseen` and `recent_messages`. **0.1 credit**.

```json theme={null}
{ "account_id": "your-account-id", "action": "inbox_summary", "params": {} }
```

## Email inbox

For an [email mailbox](https://docs.linkupapi.com/api-reference/v2/accounts/login.md#email-mailbox), `list_inbox` returns the **same structure** (`conversations` / `total_results` / `next_cursor`) — each email is mapped to a conversation. Differences:

* `conversation_id` is the thread id (Gmail) — pass it to [Get Conversation](https://docs.linkupapi.com/api-reference/v2/messages/get-conversation.md) to fetch the full thread.
* `id` is the provider message id — use it with `mark_as_read` / `mark_as_unread` / `archive` / `trash` and attachment download.
* `participant` and `last_message.sender` carry `{ name, email }` (no `profile_url` / `headline`).
* `last_message` adds `subject`; `text` is the body snippet.
* Extra per-item fields: `message_id`, `in_reply_to`, `is_bounce`, `has_attachments`.

Also accepts `unread_only`, `label_ids` (read a folder other than INBOX — see [`list_labels`](https://docs.linkupapi.com/api-reference/v2/messages/manage-emails)), and **cursor pagination** (`cursor` in, `next_cursor` out) — same model as LinkedIn (Gmail has no offset).

```json 200 (email) theme={null}
{
  "success": true,
  "data": {
    "conversations": [
      {
        "conversation_id": "1a09b5fe5c04c6d6",
        "id": "1a09b5fe5c04c6d6",
        "participant": { "name": "John Doe", "email": "john@example.com" },
        "last_message": {
          "text": "Sure, let's chat Thursday.",
          "subject": "Re: Quick question",
          "time": 1789398178000,
          "sender": { "name": "John Doe", "email": "john@example.com", "is_me": false }
        },
        "unread": 1,
        "type": "email",
        "message_id": "<CAF...@mail.gmail.com>",
        "in_reply_to": "<178928915191...@gmail.com>",
        "is_bounce": false,
        "has_attachments": false
      }
    ],
    "total_results": 1,
    "next_cursor": "MDA2MjQxMDE2Mzc1MTEyNDY3MzE="
  },
  "metadata": { "action": "list_inbox", "account_id": "your-email-account-id", "credits_consumed": 1, "timestamp": "2026-09-14T12:00:00Z" }
}
```

## Search (email)

`action: "search"` searches the whole mailbox and returns the **same shape** (`conversations` / `total_results` / `next_cursor`). Pass `query` (Gmail accepts its native syntax, e.g. `from:john subject:invoice`). Works on Gmail, Outlook and IMAP. Cursor pagination applies.

```json Request theme={null}
{ "account_id": "your-email-account-id", "action": "search", "params": { "query": "invoice from:john", "count": 20 } }
```


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