Inbox
Use UniPost Inbox APIs to list, sync, and reply to normalized Instagram, Facebook, Threads, and X conversations. X Inbox requires the Basic plan or higher.
Availability
Statussupported
Inbox APIs are available for supported plans and are gated by the workspace plan.
Current support6 available sources
Instagram, Facebook, Threads, and X replies are available.
Auth modelBearer <token>In header
HTTP requests use a workspace API key or authenticated dashboard token. Customer WebSocket backends send the API key in the Authorization header; the UniPost Dashboard sends its Clerk session token in the token query field. Keep API keys server-side, map the authenticated app user to external_user_id, and never put API keys in a URL.
Scope modelrequired
API-key requests must use managed_user plus external_user_id for one managed user, or workspace for an aggregate. Workspace scope requires a creator-bound key whose creator is still owner/admin.
Supported endpoints
GET /v1/inboxlist
List inbox items for the selected scope. See the endpoint reference.
GET /v1/inbox/unread-countread
Return the unread item count for the selected scope.
GET /v1/inbox/{id}read
Fetch one item only when it belongs to the selected scope.
POST /v1/inbox/{id}/readwrite
Mark one item in the selected scope as read.
POST /v1/inbox/mark-all-readwrite
Mark every item in the selected scope as read.
POST /v1/inbox/{id}/replywrite
Reply to a supported comment or thread. See the endpoint reference.
POST /v1/inbox/{id}/thread-stateworkflow
Update scoped workflow state such as open, assigned, or resolved.
GET /v1/inbox/{id}/media-contextread
Fetch scoped media context for a supported Inbox item.
POST /v1/inbox/syncsync
Trigger selected-scope polling or a bounded X backfill. See the endpoint reference.
GET /v1/inbox/x-outbound-operations/{requestID}read
Inspect the durable outcome of a scoped X reply operation.
GET /v1/inbox/wsrealtime
Subscribe to events for one explicit Inbox scope.
Supported sources
ig_commentsupported
Comments on connected Instagram Business or Creator accounts.
ig_dmsupported
Instagram DMs when the connected account and permissions are eligible.
threads_replysupported
Comments and replies on connected Threads content.
fb_commentsupported
Comments on connected Facebook Page posts.
fb_dmsupported
Private messages for connected Facebook Pages.
x_replysupported
Eligible public replies that summon a connected X account.
more_sourcescoming soon
Additional inbox sources and workflow coverage will be added over time.
Query params
inbox_scopestring
Required on every API-key Inbox request.
Valuesmanaged_user | workspace
external_user_idstring
Required for managed_user scope and rejected for workspace scope. Derive it from the authenticated app user on your server.
sourceOptionalstring
Filter by normalized source.
Valuesig_comment | ig_dm | threads_reply | fb_comment | fb_dm | x_reply
is_readOptionalboolean
Filter unread or read items.
is_ownOptionalboolean
Filter items authored by the connected account or by an external user.
limitOptionalinteger
Maximum number of items to return. Defaults to 50 and caps at 500.
Scope and authentication order
Authentication and explicit scope resolution run before the Inbox plan gate. A request that is both mis-scoped and plan-ineligible therefore returns the scope error before 402.
INBOX_SCOPE_LOOKUP_FAILED is a transient 500 produced before the selected endpoint runs. Retry the same request with bounded exponential backoff. Do not treat every 5xx as safe to retry, especially after an uncertain write outcome.
For the complete server boundary, Connect Session, real-time relay, and owner/admin workflow, follow the Inbox integration guide.
Response
200 OK
data[]array
Normalized inbox items sorted by received_at descending.
data[].idstring
Stable UniPost inbox item identifier.
data[].sourcestring
One of ig_comment, ig_dm, threads_reply, fb_comment, fb_dm, x_reply.
data[].social_account_idstring
Connected account that owns the item.
data[].thread_keystring
Stable key used to group related messages and replies.
data[].thread_statusstring
Workflow state.
Valuesopen | assigned | resolved
data[].author_namestring
Best available author display name.
data[].bodystring
Comment or message body.
data[].is_readboolean
Whether the item has been read in UniPost.
data[].is_ownboolean
Whether the item was authored by the connected account.
data[].received_atstring
Inbound or outbound activity timestamp.
request_idstring
Request identifier for debugging and support.
Errors
error.codestring
INBOX_SCOPE_REQUIRED when API-key scope is omitted; also INBOX_SCOPE_INVALID, INBOX_SCOPE_LOOKUP_FAILED, MANAGED_USER_NOT_FOUND, INSUFFICIENT_ROLE, API_KEY_CREATOR_REQUIRED, UNAUTHORIZED, PLAN_FEATURE_NOT_AVAILABLE, or VALIDATION_ERROR.
error.messagestring
Human-readable error message.
request_idstring
Request identifier for debugging and support.