FAQ - Inbox API

General

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.

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

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 for the full roadmap.

Is there a free tier?

All plans support a 7-day free trial. API access is available by default.

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.

IDs and lookups

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.

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

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

How do I find a thread by username?

Use the lookup-by-username endpoint:

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.

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:

curl "https://api.twitter.com/2/users/by/username/johndoe" \
  -H "Authorization: Bearer YOUR_X_BEARER_TOKEN"

Messaging

Can I send messages to new prospects?

Yes, using the quick send endpoint:

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

This creates the thread and prospect automatically.

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 for details and backoff strategies.

What's the maximum message length?

X DMs support up to 10,000 characters.

Can I send images or media?

Media attachments are not currently supported via the API. Only text messages can be sent.

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.

Threads and conversations

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

const { data } = await client.get("/threads", {
  params: { inbox: "default" },
});

How do I archive a thread?

Set done: true:

await client.patch(`/threads/${threadId}`, {
  done: true,
});

Can I delete a thread?

Yes, but it’s permanent:

await client.delete(`/threads/${threadId}`);

Consider archiving (done: true) instead.

How do I know who sent the last message?

Check authorId against your account link IDs. There is no direction field on messages.

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");
}

Prospects

How are prospects created?

Prospects are automatically created when:

They send you a DM
You create a thread with them
You use quick send to message them

You cannot create prospects directly.

How do I add notes to a prospect?

Use the context update endpoint:

await client.patch(`/prospects/${prospectId}/context`, {
  notes: "Interested in Enterprise plan",
  valuation: 50000,
});

Is prospect profile data real-time?

No. Profile data (followers, bio, etc.) is synced periodically. Check isFresh, isStale, and confidence to assess data quality.

Can a prospect have multiple tags?

Yes. Tags are multi-select. Statuses are single-select. Tags are updated incrementally:

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

There is no tagIds field — use addTags and removeTags to modify tags.

Account links

How do I connect a new X account?

Account connections are managed through the Inbox dashboard:

Go to inboxapp.com
Navigate to Settings → Accounts
Make sure you have the Chrome extension installed
Click Open X and select the account to link

The API is read-only for account links.

Can I send from multiple accounts?

Yes. Specify the accountLinkId when sending:

await client.post("/threads/messages", {
  externalPlatformId: "1876543210987654321",
  accountLinkId: "df6jbw4h36qm5d9iu2sgn7kx",
  content: "Hello from sales!",
});

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.

Team and members

How do I assign a thread to a team member?

await client.patch(`/threads/${threadId}`, {
  assigneeId: 'r3km7xj9wq5p2bvnhfdteoly'
});

Can I create team members via API?

No. Team member management is done through the Inbox dashboard.

How do I get unassigned threads?

const { data } = await client.get('/threads', {
  params: {
    'filters[assignees][noAssignee]': true
  }
});

Technical

What's the base URL?

https://inboxapp.com/api/v1

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.

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.

How do I filter threads?

Use the filters parameter with bracket notation:

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

See the Query Parameters guide for a full reference of filter keys.

Is there a webhook for new messages?

Webhooks are not currently available. Use polling to check for new messages.

Is there an official SDK?

Not yet. Use any HTTP client (axios, fetch) with the REST API.

Still have questions?

Browse the API Reference for endpoint details
Check Troubleshooting for common issues
Visit the Help Center
Email support at support@inboxapp.com

API reference

Complete endpoint documentation

Troubleshooting

Common issues and fixes

Quick start

Send your first message

Core concepts

Understand the data model

​General

​IDs and lookups

​Messaging

​Threads and conversations

​Prospects

​Account links

​Team and members

​Technical

​Still have questions?