Inbox

The inbox collects what people say to your accounts: comments under your posts, mentions of your accounts elsewhere, reviews left on your business, and direct messages. Every item is stored once, tagged with the account it arrived on, and can be answered, liked, resolved, snoozed, hidden or deleted from the API. These endpoints need the inbox scope. Anything that acts on a platform beyond a plain reply (a like, a pin, an edit, a reaction, a new conversation, an attachment) also needs the publish scope.

List items

GET /v1/inbox

curl "https://api.fopost.com/v1/inbox?workspace_id=7d2b8c11-4e5a-4a8f-b0d9-3c5e6f7a8b90&state=unread" \
  -H "X-API-Key: $FOPOST_API_KEY"

An item looks like this:

{
  "id": "0f1c4a1e-8f3c-4c62-9f6a-2a4b1a9e77d1",
  "workspace_id": "7d2b8c11-4e5a-4a8f-b0d9-3c5e6f7a8b90",
  "platform": "instagram",
  "type": "comment",
  "state": "unread",
  "direction": "inbound",
  "author_name": "Sam Rivera",
  "author_handle": "samrivera",
  "text": "Does this come in blue?",
  "permalink": "https://www.instagram.com/p/abc123/",
  "platform_created_at": "2026-09-18T14:30:00.000Z",
  "can_reply": true,
  "can_hide": true,
  "can_delete": true,
  "can_like": true,
  "can_repost": false,
  "can_bookmark": false,
  "can_pin": false,
  "can_edit": false,
  "can_react": false,
  "can_send_media": false,
  "can_quick_reply": false,
  "can_private_reply": true,
  "rating": null,
  "liked": false,
  "reposted": false,
  "bookmarked": false,
  "pinned": false,
  "reaction": null,
  "edited_at": null,
  "moderation_status": "published",
  "post": { "id": "3a9f1d20-6c77-4b2e-9a01-8f5d2c3b4e10", "title": "Autumn drop" },
  "account": { "id": "b81e4f02-91a3-4c55-8de6-77a0c1f2d3e4", "platform": "instagram", "username": "yourbrand" }
}

moderation_status is the platform's own state for a comment where it reports one: published, held (waiting on a decision, invisible on the post until then), spam, or rejected. It is null on the networks that do not say.

The can_* flags tell you what the platform allows for that item before you try. A platform whose API reads comments but cannot answer them returns can_reply: false. An action the platform does not offer answers 409 with unsupported_platform.

A review item is a rating left on the business itself rather than a comment on a post: a Google Business review or a Facebook Page recommendation. It carries rating, the stars out of five, which is null on every other type. Its post_external_id is the review itself, so listing by that pair returns the review and your response as one thread.

DM attachments are listed under attachments, each with a url served by the API. That link grants nothing on its own: workspace membership is checked on every request, and the bytes come through FoPost rather than from a platform URL.

Threads and conversations

Two views group the same items the way the dashboard does.

GET /v1/inbox/posts
GET /v1/inbox/conversations

/posts returns one row per platform post that has collected comments, with counts and the latest comment. Pass kind=mentions for the posts your account was tagged in, or kind=reviews for one row per review, each carrying its rating. /conversations returns one row per DM thread, latest first. Both accept workspace_id, platform, account_id, state, q, sort and pagination.

To read a thread, list items with the pair the row gives you:

curl "https://api.fopost.com/v1/inbox?account_id=$ACCOUNT&post_external_id=17895695668004550" \
  -H "X-API-Key: $FOPOST_API_KEY"

Reply

POST /v1/inbox/{id}/reply

curl -X POST https://api.fopost.com/v1/inbox/0f1c4a1e-8f3c-4c62-9f6a-2a4b1a9e77d1/reply \
  -H "X-API-Key: $FOPOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "text": "It does. Blue lands next week." }'

The reply is posted on the platform as the connected account and the item is settled. The response carries the updated item and a reply with the platform's id and link for it. A 409 means the account is disconnected or the platform cannot reply; a 502 means the platform refused the reply and message says why; a 503 means this deployment holds no credentials for that platform's API yet.

A reply to a DM can carry more than text, where the item allows it. Both need the publish scope.

curl -X POST https://api.fopost.com/v1/inbox/0f1c4a1e-8f3c-4c62-9f6a-2a4b1a9e77d1/reply \
  -H "X-API-Key: $FOPOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "text": "Here is the size chart.", "media_ids": ["5c0e2a44-1b7d-4f3e-9c21-6a8b0d4e2f17"], "quick_replies": ["Order now", "Talk to us"] }'

A media id from another workspace answers 404, the same as one that does not exist.

Change state

PATCH /v1/inbox/{id}

Edit your own comment

PATCH /v1/inbox/{id}

Send { "text": "..." } instead of a state to change a comment your account wrote, on the platform. Available where can_edit is true, and needs the publish scope. The item comes back with the new text and an edited_at time.

To read a whole thread at once, the way opening a chat does:

POST /v1/inbox/read

with workspace_id, account_id, and either post_external_id or conversation_id.

Moderate

POST /v1/inbox/{id}/hide
POST /v1/inbox/{id}/unhide
DELETE /v1/inbox/{id}

Hide and delete act on the platform, not just in FoPost. They are available where the item's can_hide or can_delete is true. A hidden item stays in the inbox with hidden: true. Delete also removes a reply your account wrote; deleting your own reply needs the publish scope.

Like, repost, bookmark and pin

POST /v1/inbox/{id}/like
POST /v1/inbox/{id}/unlike
POST /v1/inbox/{id}/repost
POST /v1/inbox/{id}/unrepost
POST /v1/inbox/{id}/bookmark
POST /v1/inbox/{id}/unbookmark
POST /v1/inbox/{id}/pin
POST /v1/inbox/{id}/unpin

Like acts as the connected account: a like on most networks, an upvote on Reddit, a favourite on Mastodon. It is available where can_like is true, and the item then reports liked: true. Repost puts the post on the account's own timeline and bookmark saves it privately; both exist on X, where can_repost and can_bookmark are true, and the item reports reposted and bookmarked. Pin works on a comment your account wrote, where can_pin is true. Every one of these needs the publish scope, and the undo route reverses it.

On X each call is a pass-through API call billed to the workspace like a read. If X's own balance is spent the call answers 402 with platform_balance_spent, and nothing is charged.

X posts beyond the inbox

GET /v1/x/posts/{id}?account_id=
GET /v1/x/search?q=&account_id=

Both read through the X account you name with account_id, and both need the inbox scope. The lookup returns one post by its X id with its author and public metrics; 404 means X has no post with that id. The search is X's recent search over the last seven days, up to 512 characters of query, max_results from 10 to 100, and a next_token in meta for the next page. Each call, and each page, is one metered X read. Following a user from an account is on the accounts page.

Direct messages

Start a conversation:

POST /v1/inbox/conversations

curl -X POST https://api.fopost.com/v1/inbox/conversations \
  -H "X-API-Key: $FOPOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "comment_id": "0f1c4a1e-8f3c-4c62-9f6a-2a4b1a9e77d1", "text": "Sending you the details here." }'

The response is 201 with the conversation_id where the platform reports one and the sent item.

React to a message, or remove your reaction with null, where can_react is true. Instagram has one reaction, a heart, so any emoji sends it.

POST /v1/inbox/{id}/react

{ "reaction": "❤️" }

Show the typing indicator in a thread while someone writes an answer, then clear it with on: false:

POST /v1/inbox/conversations/{conversationId}/typing

{ "account_id": "b81e4f02-91a3-4c55-8de6-77a0c1f2d3e4", "on": true }

All of these need the publish scope.

Replies awaiting approval

An automation or the agent can draft a reply that a person still has to send. Nothing reaches a platform until it is approved.

GET /v1/inbox/approvals
POST /v1/inbox/approvals/{id}/approve
POST /v1/inbox/approvals/{id}/reject

Approve takes an optional text to send an edited version instead of the draft. A 409 means the reply was already decided.

Coverage

GET /v1/inbox/accounts
GET /v1/inbox/platforms
GET /v1/inbox/unread-count

/accounts lists every active connected account with inbox_supported and dm_supported, so a filter can tell the truth about what it reads, plus can_start_conversation for accounts that can open a DM by handle. An account with reconnect_required: true was connected before the inbox asked for a permission it needs and is not polled until someone reconnects it; everything else that account does keeps working. /platforms lists which networks feed the inbox today and which are coming.

Poll now

POST /v1/inbox/refresh

Fetches new comments and messages for every inbox-capable account in the workspace_id you pass, instead of waiting for the next scheduled poll. The response reports how many accounts were polled and how many new items arrived. Platforms that bill per read are read on this call, so use it when someone is waiting, not on a timer of your own.

Next