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

# FAQ

> Frequently asked questions about the Inbox API

## General

<AccordionGroup>
  <Accordion title="What is Inbox?">
    Inbox is a DM management platform with a developer API and a team inbox interface, starting with X (Twitter).
    The API gives you programmatic access to conversations, prospects, and team
    workflows.
  </Accordion>

  <Accordion title="What can I build with the Inbox API?">
    Common use cases include:

    * **Messaging automation** — Send DMs programmatically with custom workflows
    * **CRM integration** — Sync conversations to HubSpot, Salesforce, etc.
    * **AI chatbots** — Build intelligent auto-reply systems
    * **Analytics dashboards** — Track engagement and conversion metrics
  </Accordion>

  <Accordion title="Which platforms are supported?">
    Currently, X (Twitter) DMs are supported. Instagram and LinkedIn are coming in Q2 2026, with TikTok and WhatsApp planned after that. See [Supported platforms](/resources/supported-platforms) for the full roadmap.
  </Accordion>

  <Accordion title="Is there a free tier?">
    All plans support a 7-day free trial. API access is available by default.
  </Accordion>

  <Accordion title="Do I need to pay to send messages?">
    Replying to contacts who have already messaged you works on all plans at no extra cost. Sending the first message to a new contact requires the **Outbound Messages addon** (\$199/mo) on a paid plan. Enable it in **Settings → Billing** or email [support@inboxapp.com](mailto:support@inboxapp.com).
  </Accordion>
</AccordionGroup>

***

## IDs and lookups

<AccordionGroup>
  <Accordion title="What's the difference between Inbox ID and Platform ID?">
    Every entity has two IDs:

    | ID Type         | Field        | Example                    | Use For                    |
    | --------------- | ------------ | -------------------------- | -------------------------- |
    | **Inbox ID**    | `id`         | `l44e15irdq4db30i77cgphhx` | All API operations         |
    | **Platform ID** | `platformId` | `1876543210987654321`      | Lookups from external data |

    Always use Inbox IDs for API calls. Use platform IDs for lookups.

    ```typescript theme={null}
    // Correct: Inbox ID for operations
    await client.get(`/threads/${thread.id}`);

    // Correct: Platform ID for lookups
    await client.get("/threads/lookup", {
      params: { externalPlatformId: "1876543210987654321" },
    });
    ```
  </Accordion>

  <Accordion title="How do I find a thread by username?">
    Use the lookup-by-username endpoint:

    ```typescript theme={null}
    const { data: threads } = await client.get("/threads/lookup-by-username", {
      params: { username: "jordanrivera" },
    });
    ```

    Returns a flat array of threads across all account links for that username. The username must be an exact match (case-insensitive the `@` prefix).

    For lookup by platform ID instead, use `GET /threads/lookup` with `externalPlatformId` and `accountLinkId`.
  </Accordion>

  <Accordion title="How do I get someone's X user ID from their username?">
    The Inbox API doesn't provide this. Use the X API to lookup users by username:

    ```bash theme={null}
    curl "https://api.twitter.com/2/users/by/username/johndoe" \
      -H "Authorization: Bearer YOUR_X_BEARER_TOKEN"
    ```
  </Accordion>
</AccordionGroup>

***

## Messaging

<AccordionGroup>
  <Accordion title="Can I send messages to new prospects?">
    Yes, using the quick send endpoint:

    ```typescript theme={null}
    await client.post("/threads/messages", {
      externalPlatformId: "1876543210987654321",
      accountLinkId: "df6jbw4h36qm5d9iu2sgn7kx",
      content: "Hello!",
    });
    ```

    This creates the thread and prospect automatically.
  </Accordion>

  <Accordion title="What are the message rate limits?">
    Rate limits are **global per team** — all endpoints share the same limits, and all API tokens for a team share the same quota.

    | Window     | Limit            |
    | ---------- | ---------------- |
    | Per minute | 300 requests     |
    | Per hour   | 10,000 requests  |
    | Per day    | 100,000 requests |

    See the [Rate Limits guide](/reference/rate-limits) for details and backoff strategies.
  </Accordion>

  <Accordion title="What's the maximum message length?">
    X DMs support up to 10,000 characters.
  </Accordion>

  <Accordion title="Can I send images or media?">
    Media attachments are not currently supported via the API. Only text messages
    can be sent.
  </Accordion>

  <Accordion title="What's the difference between quick send and standard send?">
    | Method                                            | Use When                                          |
    | ------------------------------------------------- | ------------------------------------------------- |
    | **Quick send** (`POST /threads/messages`)         | Simple one-off messages, don't need thread object |
    | **Standard send** (`POST /threads/{id}/messages`) | Multiple messages, need thread details first      |

    Quick send handles thread creation automatically.
  </Accordion>
</AccordionGroup>

***

## Threads and conversations

<AccordionGroup>
  <Accordion title="What are the inbox views?">
    | View       | Description                                         |
    | ---------- | --------------------------------------------------- |
    | `default`  | Active conversations needing attention              |
    | `no-reply` | Prospect sent the last message, awaiting your reply |
    | `requests` | New message requests                                |
    | `archived` | Marked as done                                      |

    ```typescript theme={null}
    const { data } = await client.get("/threads", {
      params: { inbox: "default" },
    });
    ```
  </Accordion>

  <Accordion title="How do I archive a thread?">
    Set `done: true`:

    ```typescript theme={null}
    await client.patch(`/threads/${threadId}`, {
      done: true,
    });
    ```
  </Accordion>

  <Accordion title="Can I delete a thread?">
    Yes, but it's permanent:

    ```typescript theme={null}
    await client.delete(`/threads/${threadId}`);
    ```

    Consider archiving (`done: true`) instead.
  </Accordion>

  <Accordion title="How do I know who sent the last message?">
    Check `authorId` against your account link IDs. There is no `direction` field on messages.

    ```typescript theme={null}
    const { data: accountLinks } = await client.get("/account-links");
    const accountLinkIds = new Set(accountLinks.map((a) => a.id));

    const { data } = await client.get(`/threads/${threadId}/messages`, {
      params: { limit: 1 },
    });

    const lastMessage = data.messages[0];
    if (lastMessage && accountLinkIds.has(lastMessage.authorId)) {
      console.log("Last message was from our account");
    } else {
      console.log("Last message was from the prospect");
    }
    ```
  </Accordion>
</AccordionGroup>

***

## Prospects

<AccordionGroup>
  <Accordion title="How are prospects created?">
    Prospects are automatically created when:

    1. They send you a DM
    2. You create a thread with them
    3. You use quick send to message them

    You cannot create prospects directly.
  </Accordion>

  <Accordion title="How do I add notes to a prospect?">
    Use the context update endpoint:

    ```typescript theme={null}
    await client.patch(`/prospects/${prospectId}/context`, {
      notes: "Interested in Enterprise plan",
      valuation: 50000,
    });
    ```
  </Accordion>

  <Accordion title="Is prospect profile data real-time?">
    No. Profile data (followers, bio, etc.) is synced periodically. Check
    `isFresh`, `isStale`, and `confidence` to assess data quality.
  </Accordion>

  <Accordion title="Can a prospect have multiple tags?">
    Yes. Tags are multi-select. Statuses are single-select. Tags are updated incrementally:

    ```typescript theme={null}
    await client.patch(`/prospects/${prospectId}/context`, {
      addTags: ["t8rvk2m5j0xn4wq7ybftcael", "u9swl3n6k1yo5xr8zcgudbfm"],
      statusId: "s3km7xj9wq5p2bvnhfdteoly",
    });
    ```

    There is no `tagIds` field — use `addTags` and `removeTags` to modify tags.
  </Accordion>
</AccordionGroup>

***

## Account links

<AccordionGroup>
  <Accordion title="How do I connect a new X account?">
    Account connections are managed through the Inbox dashboard:

    1. Go to [inboxapp.com](https://inboxapp.com)
    2. Navigate to **Settings → Accounts**
    3. Make sure you have the [Chrome extension installed](https://chromewebstore.google.com/detail/inbox/manipndiogdfeenejomojogbbcbenioe)
    4. Click **Open X** and select the account to link

    The API is read-only for account links.
  </Accordion>

  <Accordion title="Can I send from multiple accounts?">
    Yes. Specify the `accountLinkId` when sending:

    ```typescript theme={null}
    await client.post("/threads/messages", {
      externalPlatformId: "1876543210987654321",
      accountLinkId: "df6jbw4h36qm5d9iu2sgn7kx",
      content: "Hello from sales!",
    });
    ```
  </Accordion>

  <Accordion title="Are rate limits per account or per API key?">
    Rate limits are per team — all API tokens for the same team share the same
    quota. The limits are 300 requests per minute, 10,000 per hour, and 100,000
    per day across all endpoints.
  </Accordion>
</AccordionGroup>

***

## Team and members

<AccordionGroup>
  <Accordion title="How do I assign a thread to a team member?">
    ```typescript theme={null}
    await client.patch(`/threads/${threadId}`, {
      assigneeId: 'r3km7xj9wq5p2bvnhfdteoly'
    });
    ```
  </Accordion>

  <Accordion title="Can I create team members via API?">
    No. Team member management is done through the Inbox dashboard.
  </Accordion>

  <Accordion title="How do I get unassigned threads?">
    ```typescript theme={null}
    const { data } = await client.get('/threads', {
      params: {
        'filters[assignees][noAssignee]': true
      }
    });
    ```
  </Accordion>
</AccordionGroup>

***

## Technical

<AccordionGroup>
  <Accordion title="What's the base URL?">
    `https://inboxapp.com/api/v1`
  </Accordion>

  <Accordion title="How do I handle pagination?">
    Use cursor-based pagination with `cursorId` and `cursorTimestamp`. Only `GET /threads` and `GET /threads/{id}/messages` are paginated — other list endpoints return all results as a flat array.

    ```typescript theme={null}
    let cursorId: string | undefined;
    let cursorTimestamp: string | undefined;

    do {
      const { data } = await client.get("/threads", {
        params: {
          limit: 100,
          ...(cursorId && { cursorId, cursorTimestamp }),
        },
      });

      // Process data.threads
      cursorId = data.nextCursor?.id;
      cursorTimestamp = data.nextCursor?.timestamp;
    } while (cursorId);
    ```

    See the [Pagination guide](/reference/pagination).
  </Accordion>

  <Accordion title="How do I filter threads?">
    Use the `filters` parameter with bracket notation:

    ```typescript theme={null}
    const { data } = await client.get("/threads", {
      params: {
        inbox: "default",
        "filters[tags][selectedIds][0]": "t8rvk2m5j0xn4wq7ybftcael",
        "filters[assignees][noAssignee]": true,
      },
    });
    ```

    See the [Query Parameters guide](/reference/query-parameters) for a full reference of filter keys.
  </Accordion>

  <Accordion title="Is there a webhook for new messages?">
    Webhooks are not currently available. Use polling to check for new messages.
  </Accordion>

  <Accordion title="Is there an official SDK?">
    Not yet. Use any HTTP client (axios, fetch) with the REST API.
  </Accordion>
</AccordionGroup>

***

## Still have questions?

* Browse the [API Reference](/api-reference/introduction) for endpoint details
* Check [Troubleshooting](/resources/troubleshooting) for common issues
* Visit the [Help Center](https://helpcenter.inboxapp.com)
* Email support at [support@inboxapp.com](mailto:support@inboxapp.com)

<CardGroup cols={2}>
  <Card title="API reference" icon="code" href="/api-reference/introduction">
    Complete endpoint documentation
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/resources/troubleshooting">
    Common issues and fixes
  </Card>

  <Card title="Quick start" icon="rocket" href="/quickstart">
    Send your first message
  </Card>

  <Card title="Core concepts" icon="book" href="/guides/core-concepts">
    Understand the data model
  </Card>
</CardGroup>