> ## 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.</Note>

## Request

<ParamField header="x-api-key" type="string" required>
  Your API key for authentication.
</ParamField>

<ParamField body="account_id" type="string" required>
  The unique identifier of the account to use.
</ParamField>

<ParamField body="action" type="string" required>
  Must be `"list_inbox"`.
</ParamField>

<ParamField body="params" type="object">
  <Expandable title="params properties">
    <ParamField body="count" type="integer" default={10}>
      Maximum number of conversations to return. Defaults to `10`.
    </ParamField>

    <ParamField body="category" type="string" default="INBOX">
      Filter conversations by category. One of: `"INBOX"`, `"UNREAD"`, `"MY_CONNECTIONS"`, `"INMAIL"`, `"STARRED"`. Defaults to `"INBOX"`.
    </ParamField>

    <ParamField body="cursor" type="string">
      Cursor returned by a previous response as `data.next_cursor`. Omit for the first page.
    </ParamField>

    <ParamField body="sales_nav" type="boolean" default={false}>
      Read the **Sales Nav** inbox instead of the classic one. See [Sales Nav inbox](#sales-nav-inbox) below.
    </ParamField>

    <ParamField body="unread_only" type="boolean" default={false}>
      **(Email)** Only return unread emails.
    </ParamField>
  </Expandable>
</ParamField>

<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.</Note>

## Response

<ResponseField name="success" type="boolean">
  Indicates whether the request was successful.
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="data properties">
    <ResponseField name="conversations" type="array">
      List of conversation objects.

      <Expandable title="conversation properties">
        <ResponseField name="conversation_id" type="string">
          Unique identifier of the conversation. Treat it as an opaque string and pass it back exactly as returned.
        </ResponseField>

        <ResponseField name="participant" type="object">
          The other side of the conversation. Can be a member, a company page, or — for notes-to-self — your own profile.

          <Expandable title="participant properties">
            <ResponseField name="name" type="string">Display name (member full name or company name).</ResponseField>
            <ResponseField name="headline" type="string">Headline (or company tagline if `is_organization`).</ResponseField>
            <ResponseField name="profile_url" type="string">Public profile URL (or company page URL if `is_organization`).</ResponseField>
            <ResponseField name="profile_picture" type="string">Profile picture URL (or company logo if `is_organization`).</ResponseField>
            <ResponseField name="is_organization" type="boolean">Present and `true` when the participant is a company page (e.g. sponsored premium direct messages, brand outreach). Absent for human members.</ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="last_message" type="object">
          The most recent message in the conversation.

          <Expandable title="last_message properties">
            <ResponseField name="text" type="string">Plain-text content of the message.</ResponseField>
            <ResponseField name="time" type="integer">Unix epoch timestamp in **milliseconds** when the message was sent.</ResponseField>

            <ResponseField name="sender" type="object">
              Author of the last message.

              <Expandable title="sender properties">
                <ResponseField name="name" type="string">Display name of the sender.</ResponseField>
                <ResponseField name="headline" type="string">Headline of the sender.</ResponseField>
                <ResponseField name="profile_url" type="string">Public profile URL of the sender.</ResponseField>
                <ResponseField name="profile_picture" type="string">URL of the sender's profile picture.</ResponseField>
                <ResponseField name="is_me" type="boolean">`true` when the sender is the authenticated account.</ResponseField>
              </Expandable>
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="unread" type="integer">
          Number of unread messages in the conversation. `0` when fully read.
        </ResponseField>

        <ResponseField name="type" type="string">
          Conversation type. Common values: `"normal"`, `"inmail"`, `"Sponsored"`.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="total_results" type="integer">
      Number of conversations returned in this response.
    </ResponseField>

    <ResponseField name="next_cursor" type="string">
      Cursor to send as `next_cursor` in the next request to resume pagination. `null` when the end is reached.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="metadata" type="object">
  <Expandable title="metadata properties">
    <ResponseField name="action" type="string">
      The action that was performed (`"list_inbox"`).
    </ResponseField>

    <ResponseField name="account_id" type="string">
      The account ID used for the request.
    </ResponseField>

    <ResponseField name="credits_consumed" type="integer">
      Number of credits consumed (1 per 10 results).
    </ResponseField>

    <ResponseField name="timestamp" type="string">
      ISO 8601 timestamp of the response.
    </ResponseField>
  </Expandable>
</ResponseField>

## 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](/api-reference/v2/messages/send). 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`

<ResponseExample>
  ```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 is required."
    },
    "metadata": {
      "action": "list_inbox",
      "account_id": null,
      "credits_consumed": 0,
      "timestamp": "2026-04-26T10:35:00Z"
    }
  }
  ```
</ResponseExample>

## Email inbox

For an [email mailbox](/api-reference/v2/accounts/login#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](/api-reference/v2/messages/get-conversation) 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`](/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.