Skip to main content

​
General

Inbox is a unified API for managing DM conversations across messaging platforms. Currently supporting X (Twitter), with Instagram, LinkedIn, TikTok, and WhatsApp coming soon.
Common use cases include:
  • Outreach automation — Send personalized DMs at scale
  • CRM integration — Sync conversations to HubSpot, Salesforce, etc.
  • AI chatbots — Build intelligent auto-reply systems
  • Analytics dashboards — Track engagement and conversion metrics
Currently, only X (Twitter) is supported. Instagram, LinkedIn, TikTok, and WhatsApp support is planned.
Check the current pricing at inboxapp.com. API access is typically included in paid plans.

​
IDs and Lookups

Every entity has two IDs:
ID TypeFieldExampleUse For
Inbox IDidthread_abc123All API operations
Platform IDplatformId1876543210987654321Lookups 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: { prospectPlatformId: '1876543210987654321' }
});
You can’t lookup directly by username. First find the prospect:
// 1. Get the prospect's platform ID (you need to know it or find it via X API)
const platformId = '987654321';

// 2. Lookup the thread
const { data } = await client.get('/threads/lookup', {
  params: {
    prospectPlatformId: platformId,
    accountLinkId: 'acc_abc123'
  }
});
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

Yes, using the quick send endpoint:
await client.post('/threads/messages', {
  prospectPlatformId: '987654321',  // X user ID
  accountLinkId: 'acc_abc123',
  text: 'Hello!'
});
This creates the thread and prospect automatically.
CategoryLimit
API requests (read)100/minute
API requests (write)30/minute
Message sending10/minute per account
See the Rate Limits guide for details.
X DMs support up to 10,000 characters.
Media attachments are not currently supported via the API. Only text messages can be sent.
MethodUse 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

ViewDescription
defaultActive conversations needing attention
no-replyYou sent last message, awaiting reply
requestsNew message requests
archivedMarked as done
const { data } = await client.get('/threads', {
  params: { inboxView: 'default' }
});
Set done: true:
await client.patch(`/threads/${threadId}`, {
  done: true
});
Yes, but it’s permanent:
await client.delete(`/threads/${threadId}`);
Consider archiving (done: true) instead.
Check if the last message is inbound (from the prospect):
const { data } = await client.get(`/threads/${threadId}/messages`, {
  params: { limit: 1 }
});

const hasUnread = data.messages[0]?.direction === 'inbound';

​
Prospects

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.
Use the context update endpoint:
await client.patch(`/prospects/${prospectId}/context`, {
  notes: 'Interested in Enterprise plan',
  valuation: 50000
});
No. Profile data (followers, bio, etc.) is synced periodically. It may be slightly stale.
Yes. Tags are multi-select. Statuses are single-select.
await client.patch(`/prospects/${prospectId}/context`, {
  tagIds: ['tag_a', 'tag_b', 'tag_c'],  // Multiple tags
  statusId: 'status_one'                 // Only one status
});
Account connections are managed through the Inbox dashboard:
  1. Go to inboxapp.com
  2. Navigate to Settings → Connected Accounts
  3. Click Connect X Account
The API is read-only for account links.
Yes. Specify the accountLinkId when sending:
await client.post('/threads/messages', {
  prospectPlatformId: '987654321',
  accountLinkId: 'acc_sales_account',  // Choose which account
  text: 'Hello from sales!'
});
API rate limits are per API key. Message sending limits are per account link.

​
Team and Members

await client.patch(`/threads/${threadId}`, {
  assignedToMemberId: 'member_abc123'
});
No. Team member management is done through the Inbox dashboard.
const { data } = await client.get('/threads', {
  params: {
    'filter[noAssignee]': true
  }
});

​
Technical

https://inboxapp.com/api/v1
Use cursor-based pagination:
let cursor = undefined;

do {
  const { data } = await client.get('/threads', {
    params: {
      limit: 100,
      ...(cursor && {
        'cursor[id]': cursor.id,
        'cursor[timestamp]': cursor.timestamp
      })
    }
  });

  // Process data.threads
  cursor = data.nextCursor;
} while (cursor);
See the Pagination guide.
Use bracket notation:
// Array of tag IDs
params: {
  'filter[tagIds][0]': 'tag_a',
  'filter[tagIds][1]': 'tag_b'
}
See the Query Parameters guide.
Webhooks are not currently available. Use polling to check for new messages.
Not yet. Use any HTTP client (axios, fetch) with the REST API.

​
Still Have Questions?

API Reference

Complete endpoint documentation

Troubleshooting

Common issues and fixes

Quick Start

Send your first message

Core Concepts

Understand the data model