# Monitoring the inbox

Enable whole-inbox monitoring once, then poll a single endpoint to receive new messages across every conversation in your standard and Sales Navigator inboxes.

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

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

> 💡 **Inbox monitoring vs. [conversation syncing](/docs/working-with-conversations).** [`st.syncConversation`](/docs/action-st-sync-conversation) watches one specific person and retrieves that conversation's full history. `st.syncInbox` watches your **entire** inbox but only captures messages that arrive **after** it is enabled. Use conversation syncing when you need the history of specific people; use inbox monitoring when you need to react to any new incoming message.

## 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). You only need to do this once per account. Standard and Sales Navigator inboxes can both be enabled on the same account; polled messages are tagged with a `type` so you can tell them apart.

**Workflow:**

```json
{
  "actionType": "st.syncInbox"
}
```

**Completion:**

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

## Polling

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:

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

- `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, both standard and Sales Navigator messages are returned:
  - `st` – standard inbox messages only.
  - `nv` – Sales Navigator inbox messages only.
- `threadId` (optional) – restrict the result to a single conversation thread.

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

```json
{
  "success": true,
  "result": {
    "messages": [
      {
        "id": "f4d92946-8821-6da6-ff4c-c36f0671292a",
        "type": "st",
        "threadId": "2-abc123...",
        "personUrn": "urn:li:member:123456789",
        "personUrl": "https://www.linkedin.com/in/person1",
        "sender": "them",
        "text": "Hi! Are you available for a quick chat?",
        "time": "2023-01-02T10:35:00Z"
      },
      {
        "id": "2a1b7f25-daba-5e20-70e9-c6427bb4f660",
        "type": "st",
        "threadId": "2-abc123...",
        "personUrn": "urn:li:member:123456789",
        "personUrl": "https://www.linkedin.com/in/person1",
        "sender": "us",
        "text": "Sure, let's talk this afternoon.",
        "time": "2023-01-02T10:38: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` or `nv`).
  - `threadId` – identifier of the conversation thread. Pass it to [`st.sendMessage`](/docs/action-st-send-message) / [`nv.sendMessage`](/docs/action-nv-send-message) to reply directly into the thread.
  - `personUrn` – [URN](/docs/core-concepts#linkedin-urns) of the other participant, or `null` if LinkedIn does not expose it.
  - `personUrl` – LinkedIn URL of the other participant.
  - `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.

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

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

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