# Monitoring inbox

Enable inbox monitoring once, then poll a single endpoint to receive new messages across every conversation and to read the whole conversation with one person.

> The API Reference is also the SDK and CLI reference. Consecutive code fences marked `tab=HTTP`, `tab=Node`, `tab=Python` and `tab=CLI` are the same call on each surface (a fence marked `tab=HTTP,CLI` is the same text for both), and a block between `:::surface <names>` and `:::` applies only to the surfaces it names. Identifiers in the text are written as in Node and in HTTP JSON (camelCase); the Python SDK spells methods, parameters and result attributes in snake_case (`sendMessage` → `send_message`, `reconnectionLink` → `reconnection_link`), while names inside HTTP JSON stay camelCase.

Inbox monitoring lets you track **every** incoming conversation on an account, instead of syncing people one by one. It involves 2 key steps:

:::surface node
In the Node SDK this is two calls: `linkedapi.syncInbox` once per account, then `linkedapi.pollInbox()` to read the messages.
:::

:::surface python
In the Python SDK this is two calls: `linkedapi.sync_inbox` once per account, then `linkedapi.poll_inbox()` to read the messages.
:::

:::surface cli
In the CLI this is two commands: `linkedin inbox sync` once per account, then `linkedin inbox get` to read the messages.
:::

1. **Enabling**. Enable inbox sync once per account. From that point on, Linked API watches your whole inbox in the background and captures new messages across all threads.
2. **Polling**. After inbox sync is enabled, poll a single endpoint to retrieve captured messages and receive new ones — **without syncing each conversation**.

> 💡 **This is the default way to read messages.** The inbox captures every new message on the account, and the same endpoint returns the whole conversation with one person when you pass [`personUrl`](#polling-one-person). See the [Messaging overview](/docs/messaging-overview) for which tool fits which task.

## Enabling

[Execute a workflow](/docs/executing-workflows) with the [`st.syncInbox`](/docs/action-st-sync-inbox) action (or [`nv.syncInbox`](/docs/action-nv-sync-inbox) for Sales Navigator, [`rc.syncInbox`](/docs/action-rc-sync-inbox) for Recruiter Lite). You only need to do this once per account. The standard, Sales Navigator and Recruiter Lite inboxes can all be enabled on the same account; polled messages are tagged with a `type` so you can tell them apart.

```json tab=HTTP
{
  "actionType": "st.syncInbox"
}
```

```typescript tab=Node
const workflow = await linkedapi.syncInbox.execute({});

const { errors } = await linkedapi.syncInbox.result(workflow.workflowId);
```

```python tab=Python
workflow = linkedapi.sync_inbox.execute()

result = linkedapi.sync_inbox.result(workflow.workflow_id)
```

```bash tab=CLI
linkedin inbox sync         # standard inbox
linkedin inbox sync --nv    # Sales Navigator inbox
```

:::surface http
**Completion:**

```json
{
  "actionType": "st.syncInbox",
  "success": true
}
```
:::

Enabling only switches monitoring on: the action records the setting and returns. The messages themselves are picked up afterwards by a sync that runs periodically, so the first ones appear on the next sync rather than the moment the action completes.

> **Note:** When that sync finds new messages in a thread – including messages you send yourself – it opens the profile page of the other participant in that thread to resolve their public URL – but only when Linked API does not already know it, so a person is visited once rather than on every message. Those visits are made from your own account, and such a visit is visible to the person whose profile is opened. The Recruiter Lite sync never opens a profile, see [Recruiter Lite inbox](#recruiter-lite-inbox).

## Polling

:::surface http
Unlike enabling, you don't execute workflows to poll the inbox. Instead, send a `POST` request to the following endpoint:

```text
POST https://api.linkedapi.io/inbox/poll
```

The request body is a single object. All fields are optional:
:::

:::surface node,python,cli
Unlike enabling, polling is a direct request, not a workflow. All parameters are optional:
:::

```json tab=HTTP
{
  "since": "2023-01-01T00:00:00Z",
  "type": "st",
  "threadId": "2-abc123..."
}
```

```typescript tab=Node
const { data, errors } = await linkedapi.pollInbox({
  since: "2023-01-01T00:00:00Z", // Optional: only messages after this timestamp
  type: "st",                     // Optional: "st" | "nv" | "rc"; omit for all
  threadId: "2-abc123..."         // Optional: restrict to a single thread
});
```

```python tab=Python
from linkedapi import InboxPollRequest

result = linkedapi.poll_inbox(
    InboxPollRequest(
        since="2023-01-01T00:00:00Z",  # Optional: only messages after this timestamp
        type="st",                       # Optional: "st" | "nv" | "rc"; omit for all
        thread_id="2-abc123...",        # Optional: restrict to a single thread
    )
)
```

```bash tab=CLI
linkedin inbox get --since 2023-01-01T00:00:00Z --type st --thread-id 2-abc123...
```

:::surface node
In the Node SDK this is the `pollInbox` method; it takes the fields below and returns the `result` object below as `data`, so the messages are in `data.messages`.
:::

:::surface python
In the Python SDK this is the `poll_inbox` method; it takes the fields below as an `InboxPollRequest`. It returns the messages themselves: `result.data` is a list of `InboxMessage` objects with the fields below in snake_case, so iterate `result.data` directly. To read one person's conversation, pass an `InboxPersonPollRequest` instead – see [Polling one person](#polling-one-person).
:::

:::surface cli
In the CLI this is `linkedin inbox get`:

```bash
linkedin inbox get [flags]
```

| Flag | Type | Description |
| --- | --- | --- |
| `--since` | string | Only retrieve messages after this ISO timestamp |
| `--type` | string | Filter by inbox type: `st`, `nv` or `rc` (default: all types) |
| `--thread-id` | string | Restrict to a single conversation thread |
| `--person` | string | LinkedIn profile URL, or a Recruiter profile URL. Return the whole known conversation with this person, including history loaded by `message get`, instead of the whole inbox |


> Requires inbox monitoring to be enabled once with `inbox sync`. With `--person`, history loaded by `message get` is returned even without inbox monitoring.

With `--person`, the `--json` output carries `threads` next to `messages`, and each message carries `inboxMessageId`:

- `inboxMessageId` – `id` of the same message in `inbox get` output without `--person`, or `null` if the inbox did not capture it.
- `threads` – every thread with the person, each with `threadId` (may be `null`), `type`, `personUrn`, `historyFrom` (the earliest message Linked API has) and `historyComplete` (`true` only when the thread was read back to its first message). If `historyComplete` is `false` and you need earlier messages, run `message get <person-url>` once.

See [Monitoring inbox](/docs/monitoring-inbox#polling-one-person) for the full field reference.
:::

- `since` (optional) – timestamp indicating the starting point for retrieving messages. If not provided, all captured messages are returned.
- `type` (optional) – enum to filter by inbox type. If omitted, messages of every inbox type are returned:
  - `st` – standard inbox messages only.
  - `nv` – Sales Navigator inbox messages only.
  - `rc` – Recruiter Lite inbox messages only, see [Recruiter Lite inbox](#recruiter-lite-inbox).
- `threadId` (optional) – restrict the result to a single conversation thread.
- `personUrl` (optional) – return the conversation with one person instead of the whole inbox. See [Polling one person](#polling-one-person) for how this changes the response.

:::surface http
If your request is correct, you will receive the following response:
:::

:::surface node
**Result** – `data` is the `result` object below:
:::

:::surface python
**Result** – `result.data` is the `messages` list below, as `InboxMessage` objects with snake_case fields:
:::

:::surface cli
**Output** – with `--json` or into a pipe, the CLI prints this `result` as `data`, so the messages are in `data.messages`:
:::

```json
{
  "success": true,
  "result": {
    "messages": [
      {
        "id": "f4d92946-8821-6da6-ff4c-c36f0671292a",
        "type": "nv",
        "threadId": "2-abb123...",
        "personUrn": "urn:li:member:987654321",
        "personHashedUrl": "https://www.linkedin.com/in/ACwAA9FmKpQ4T1r7XbNz",
        "personPublicUrl": null,
        "sender": "them",
        "text": "Saw your post on pipeline automation. Can you share more?",
        "time": "2023-01-02T10:42:00Z"
      },
      {
        "id": "2a1b7f25-daba-5e20-70e9-c6427bb4f660",
        "type": "st",
        "threadId": "2-abc123...",
        "personUrn": "urn:li:member:123456789",
        "personHashedUrl": "https://www.linkedin.com/in/ACoAA2DdsSV83B48UDvgO5jPo3Gho0o",
        "personPublicUrl": "https://www.linkedin.com/in/person1",
        "sender": "us",
        "text": "Sure, let's talk this afternoon.",
        "time": "2023-01-02T10:38:00Z"
      },
      {
        "id": "f4d92946-8821-6da6-ff4c-c36f0671292a",
        "type": "st",
        "threadId": "2-abc123...",
        "personUrn": "urn:li:member:123456789",
        "personHashedUrl": "https://www.linkedin.com/in/ACoAA2DdsSV83B48UDvgO5jPo3Gho0o",
        "personPublicUrl": "https://www.linkedin.com/in/person1",
        "sender": "them",
        "text": "Hi! Are you available for a quick chat?",
        "time": "2023-01-02T10:35:00Z"
      }
    ]
  }
}
```

- `messages` – flat array of messages across all threads, ordered newest first.
  - `id` – unique identifier for the message.
  - `type` – inbox type the message belongs to (`st`, `nv` or `rc`).
  - `threadId` – identifier of the conversation thread. Pass it to [`st.sendMessage`](/docs/action-st-send-message) / [`nv.sendMessage`](/docs/action-nv-send-message) / [`rc.sendMessage`](/docs/action-rc-send-message) to reply directly into the thread.
  - `personUrn` – [URN](/docs/data-conventions#linkedin-urns) of the other participant, or `null` if LinkedIn does not expose it. Always `null` on Recruiter Lite messages.
  - `personHashedUrl` – [hashed](/faq/what-are-hashed-url-and-public-url) LinkedIn URL of the other participant. This is the form the inbox exposes; every action that takes a person URL accepts it. The standard and Sales Navigator inboxes return different hashed values for the same person, so match people on `personUrn` rather than on the `personUrl` string when you need identity across both surfaces. Always `null` on Recruiter Lite messages.
  - `personPublicUrl` – [public](/faq/what-are-hashed-url-and-public-url) LinkedIn URL of the other participant, or `null` if it has not been resolved. It can be `null` on **any** message, including the first one in a thread.
  - `personRecruiterUrl` – the candidate's Recruiter profile URL, `https://www.linkedin.com/talent/profile/…`, on every Recruiter Lite message; `null` on standard and Sales Navigator messages. See [Recruiter Lite inbox](#recruiter-lite-inbox).
  - `personUrl` – **deprecated**, replaced by `personHashedUrl`, which carries the same value. Still returned so existing integrations keep working; do not use it in new code.
  - `sender` – enum indicating who sent the message. Possible values:
    - `us` – message was sent by you (through the LinkedIn UI or the Linked API).
    - `them` – message was sent by the other person.
  - `text` – message text.
  - `time` – timestamp when the message was sent or received.

> 💡 **Handling `personPublicUrl`.** A person is resolved by the periodic sync, and only when their thread produces a message after monitoring was enabled. The field is therefore `null` for everyone you have not heard from yet, and some people are never resolvable at all – so always handle `null` rather than assuming a message carries a public URL. Messages captured before this field existed, and people whose resolution did not succeed, stay `null` until that person sends another message or Linked API learns their public URL another way, for example through [`st.openPersonPage`](/docs/action-st-open-person-page). On standard and Sales Navigator messages, `personHashedUrl` is always present and is the safe input for follow-up actions. Recruiter Lite messages carry `personRecruiterUrl` instead, see [Recruiter Lite inbox](#recruiter-lite-inbox).

The inbox only captures messages that arrive after monitoring is enabled – unless you ask for one person with [`personUrl`](#polling-one-person), which also returns history loaded for that person. If inbox monitoring is not enabled on the account, the request still succeeds with an empty `messages` array.

**Recommended flow for integrations:**

1. Leave `since` empty on the first request to retrieve everything captured so far.
2. For subsequent requests, pass the **timestamp of the most recent message** you received as `since` to fetch only newer messages.
3. Continue polling with an advancing `since`. Whenever new messages arrive, update `since` to the latest message time.

`since` is inclusive and message times are whole minutes, so the messages at the latest time come back on the next request. Remember their `id`s and skip them, so you never process – or reply to – the same message twice.

> 💡 For push-based delivery instead of polling, subscribe to the inbox [Webhook Events](/docs/webhook-event-types#inbox-events). They fire for accounts with inbox monitoring enabled and carry the same message fields.

## Polling one person

Pass `personUrl` to read the whole known conversation with one person. Besides the messages the inbox captured, the result includes that person's earlier history if it was loaded with [`st.syncConversation`](/docs/action-st-sync-conversation) or [`nv.syncConversation`](/docs/action-nv-sync-conversation) – a message present in both appears once. Loaded history is returned even if inbox monitoring is not enabled on the account.

```json tab=HTTP
{
  "personUrl": "https://www.linkedin.com/in/person1"
}
```

```typescript tab=Node
const { data, errors } = await linkedapi.pollInbox({
  personUrl: "https://www.linkedin.com/in/person1"
});
```

```python tab=Python
from linkedapi import InboxPersonPollRequest

result = linkedapi.poll_inbox(
    InboxPersonPollRequest(
        person_url="https://www.linkedin.com/in/person1",
    )
)
```

```bash tab=CLI
linkedin inbox get --person https://www.linkedin.com/in/person1
```

- `personUrl` – [public or hashed](/faq/what-are-hashed-url-and-public-url) LinkedIn URL of the person. A hashed URL, standard or Sales Navigator, always matches their standard and Sales Navigator conversations. A public URL matches only once Linked API knows this person's public URL; if inbox messages from this person carry `personPublicUrl: null`, pass their `personHashedUrl` instead. A Recruiter profile URL matches the candidate's Recruiter Lite conversations, see [Recruiter Lite inbox](#recruiter-lite-inbox).
- `since`, `type` and `threadId` (optional) – work as described above and narrow the messages further. Leave `since` empty to get the full conversation.

:::surface http
If your request is correct, you will receive the following response:
:::

:::surface node
**Result** – `data` is the `result` object below, with `messages` and `threads`:
:::

:::surface python
**Result** – `result.data` is an `InboxPersonPollResult` with the `messages` and `threads` below, in snake_case:
:::

:::surface cli
**Output** – with `--json` or into a pipe, the CLI prints this `result` as `data`, with `messages` and `threads`:
:::

```json
{
  "success": true,
  "result": {
    "messages": [
      {
        "id": "8c0a1f3e-5b7d-4e21-9a6c-2f4d8e1b7c90",
        "inboxMessageId": "8c0a1f3e-5b7d-4e21-9a6c-2f4d8e1b7c90",
        "type": "st",
        "threadId": "2-abc123...",
        "personUrn": "urn:li:member:123456789",
        "personHashedUrl": "https://www.linkedin.com/in/ACoAA2DdsSV83B48UDvgO5jPo3Gho0o",
        "personPublicUrl": "https://www.linkedin.com/in/person1",
        "sender": "them",
        "text": "Thanks, the deck looks great. Let's talk next week.",
        "time": "2023-03-14T16:05:00Z"
      },
      {
        "id": "2a1b7f25-daba-5e20-70e9-c6427bb4f660",
        "inboxMessageId": "e61c94d2-0b3a-4f8e-b5d7-91a2c3e4f5a6",
        "type": "st",
        "threadId": "2-abc123...",
        "personUrn": "urn:li:member:123456789",
        "personHashedUrl": "https://www.linkedin.com/in/ACoAA2DdsSV83B48UDvgO5jPo3Gho0o",
        "personPublicUrl": "https://www.linkedin.com/in/person1",
        "sender": "us",
        "text": "Here is the deck we discussed.",
        "time": "2023-03-14T10:20:00Z"
      },
      {
        "id": "f4d92946-8821-6da6-ff4c-c36f0671292a",
        "inboxMessageId": null,
        "type": "st",
        "threadId": "2-abc123...",
        "personUrn": "urn:li:member:123456789",
        "personHashedUrl": "https://www.linkedin.com/in/ACoAA2DdsSV83B48UDvgO5jPo3Gho0o",
        "personPublicUrl": "https://www.linkedin.com/in/person1",
        "sender": "them",
        "text": "Hi! Are you available for a quick chat?",
        "time": "2022-11-02T10:35:00Z"
      }
    ],
    "threads": [
      {
        "threadId": "2-abc123...",
        "type": "st",
        "personUrn": "urn:li:member:123456789",
        "historyFrom": "2022-11-02T10:35:00Z",
        "historyComplete": true
      }
    ]
  }
}
```

- `messages` – messages exchanged with this person across all their threads, ordered newest first. Each message carries the same fields as in the response above, plus `inboxMessageId`:
  - `id` – identifier of the message in this view. It stays the same between requests, including after new messages arrive, but it can differ from the `id` the same message has in the response without `personUrl`.
  - `inboxMessageId` – `id` of the same message in the response without `personUrl`, which is also `messageId` in [inbox webhook events](/docs/webhook-event-types#inbox-events), or `null` if the inbox did not capture this message – for example, history from before monitoring was enabled. Use it to match this view against the messages you have already received from the inbox.
  - `threadId` – may be `null` in this view: a thread whose history was loaded through the person's profile keeps `threadId: null` until Linked API discovers the thread during the syncing period. After `syncUntil`, the same conversation can appear twice in `threads` – once with `threadId: null` (the loaded history, which tells you how far back it goes) and once with the inbox's `threadId`. To reply to such a person, pass `personUrl` to [`st.sendMessage`](/docs/action-st-send-message).
- `threads` – every thread with this person that Linked API knows about, listed regardless of `since`.
  - `threadId` – identifier of the thread, or `null` as described above.
  - `type` – inbox type of the thread (`st`, `nv` or `rc`).
  - `personUrn` – [URN](/docs/data-conventions#linkedin-urns) of the person, or `null` if LinkedIn does not expose it.
  - `historyFrom` – time of the earliest message Linked API has in this thread, or `null` if it has none.
  - `historyComplete` – `true` only when Linked API has read this thread back to its very first message, so `historyFrom` is where the conversation starts. `false` means earlier messages may exist that Linked API has not read.

If Linked API has no messages with this person, `messages` is empty; `threads` can still list a known thread with `historyFrom: null`.

> 💡 If `historyComplete` is `false` and you need earlier messages, see [Loading conversation history](/docs/working-with-conversations).

Messages from the inbox and from the loaded history are matched by sender, minute and text within the same thread, so two identical messages sent in the same minute stay two messages. In rare cases the two copies of one message are recorded with a different minute, and then the message appears twice.

> 💡 To check whether a person answered your message, see [Did this lead reply?](/docs/messaging-overview#did-this-lead-reply) in the Messaging overview.

## Recruiter Lite inbox

On an account with a [Recruiter Lite](/docs/recruiter-lite-overview) seat, enable the Recruiter inbox with [`rc.syncInbox`](/docs/action-rc-sync-inbox). Its messages come from the same endpoint, tagged `type: "rc"`; pass `type: "rc"` to get only them. A Recruiter Lite message looks like this:

```json
{
  "id": "5b0e2c7a-3f41-4d9b-8e62-1a7c9d4f0b35",
  "type": "rc",
  "threadId": "2-RXhhbXBsZVJlY3J1aXRlclRocmVhZA==",
  "personUrn": null,
  "personHashedUrl": null,
  "personPublicUrl": "https://www.linkedin.com/in/jane-example",
  "personRecruiterUrl": "https://www.linkedin.com/talent/profile/AEMAAB0xExampleProfileId1",
  "sender": "them",
  "text": "Thanks for reaching out! Happy to talk next week.",
  "time": "2026-03-10T09:12:00Z"
}
```

It differs from a standard or Sales Navigator message in these ways:

- **What is captured.** The sync reads Recruiter's Inbox and Awaiting reply folders at most every 30 minutes, within the account's [working hours](/docs/working-hours). So an InMail you send appears as a `sender: "us"` message before the candidate replies. Each sync looks only at the 30 most recent conversations of each folder and opens those that are new or changed: a conversation further down is not read until new activity brings it back up. Archived conversations are not read. See [What the sync reads](/docs/action-rc-sync-inbox#what-the-sync-reads).
- **No earlier history.** Messages from before the minute `rc.syncInbox` enabled monitoring are not imported, and no action loads them. In [Polling one person](#polling-one-person), a Recruiter thread therefore always has `historyComplete` set to `false`.
- **`threadId`** identifies the Recruiter conversation. Pass it to [`rc.sendMessage`](/docs/action-rc-send-message) to reply in it.
- **Person fields.** `personRecruiterUrl` is always set: the candidate's Recruiter profile URL, in the form [`rc.searchPeople`](/docs/action-rc-search-people) returns as `recruiterProfileUrl`. It is set even for a conversation started in Recruiter itself with someone whose profile Linked API never opened. Pass it to [`rc.sendMessage`](/docs/action-rc-send-message) or [`rc.openPersonPage`](/docs/action-rc-open-person-page) to address the candidate, or back to this endpoint as `personUrl` to read their Recruiter conversations. `personUrn` and `personHashedUrl` are `null`: Recruiter does not expose them. `personPublicUrl` is the candidate's public LinkedIn URL once Linked API has seen it on their Recruiter profile, through [`rc.openPersonPage`](/docs/action-rc-open-person-page) or a new InMail from [`rc.sendMessage`](/docs/action-rc-send-message); otherwise it is `null`. The sync itself never opens a profile.
- **`personUrl` in the request** also takes the candidate's Recruiter profile URL, `https://www.linkedin.com/talent/profile/<id>`, such as `recruiterProfileUrl` from [`rc.searchPeople`](/docs/action-rc-search-people) or the `personRecruiterUrl` of their messages. It then returns their Recruiter conversations only. A public or hashed `/in/` URL finds a Recruiter conversation only through the candidate's public URL, so only after `rc.openPersonPage` or a new InMail has seen it on their Recruiter profile. Until then, it returns none of their Recruiter messages.
- **Webhooks.** The `inbox.messageReceived` and `inbox.messageSent` [webhook events](/docs/webhook-event-types#inbox-events) fire for Recruiter Lite messages too, with `type: "rc"` and the same fields.

:::surface node
In the Node SDK, `linkedapi.pollInbox({ type: "rc" })` returns only the Recruiter Lite messages.
:::

:::surface python
In the Python SDK, `InboxPollRequest(type="rc")` returns only the Recruiter Lite messages. To read one candidate's Recruiter conversations, pass their Recruiter profile URL as `person_url` in `InboxPersonPollRequest`.
:::

:::surface cli
`linkedin inbox get --type rc` returns only the Recruiter Lite messages. `--person` takes a Recruiter profile URL, and the `--json` output carries `personRecruiterUrl`.
:::

In AI assistants, the MCP server's `get_inbox` tool takes `rc` as its `type` filter, and a Recruiter profile URL to read one candidate's Recruiter conversations.

> This page provides examples of [workflows](/docs/building-workflows) and their [completions](/docs/executing-workflows). For detailed documentation on constraints, parameters, and possible results of specific actions, always refer to the corresponding [action documentation pages](/docs/actions-overview).
