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",
  "workspaceId": "7d2b8c11-4e5a-4a8f-b0d9-3c5e6f7a8b90",
  "platform": "instagram",
  "type": "comment",
  "state": "unread",
  "direction": "inbound",
  "authorName": "Sam Rivera",
  "authorHandle": "samrivera",
  "text": "Does this come in blue?",
  "permalink": "https://www.instagram.com/p/abc123/",
  "platformCreatedAt": "2026-09-18T14:30:00.000Z",
  "canReply": true,
  "canHide": true,
  "canDelete": true,
  "canLike": true,
  "canPin": false,
  "canEdit": false,
  "canReact": false,
  "canSendMedia": false,
  "canQuickReply": false,
  "canPrivateReply": true,
  "rating": null,
  "liked": false,
  "pinned": false,
  "reaction": null,
  "editedAt": null,
  "moderationStatus": "published",
  "post": { "id": "3a9f1d20-6c77-4b2e-9a01-8f5d2c3b4e10", "title": "Autumn drop" },
  "account": { "id": "b81e4f02-91a3-4c55-8de6-77a0c1f2d3e4", "platform": "instagram", "username": "yourbrand" }
}

moderationStatus 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 canReply: 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 postExternalId 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 canEdit is true, and needs the publish scope. The item comes back with the new text and an editedAt 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 canHide or canDelete 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 and pin

POST /v1/inbox/{id}/like
POST /v1/inbox/{id}/unlike
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 canLike is true, and the item then reports liked: true. Pin works on a comment your account wrote, where canPin is true. All four need the publish scope.

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 conversationId where the platform reports one and the sent item.

React to a message, or remove your reaction with null, where canReact 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 inboxSupported and dmSupported, so a filter can tell the truth about what it reads, plus canStartConversation for accounts that can open a DM by handle. An account with reconnectRequired: 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