REST APIGET

Inbox mentions

List the posts and comments that mention your accounts on Facebook, Instagram, Threads, Bluesky and Mastodon, reply to them and mark them read.

GEThttps://post.adaptlypost.com/post/api/v1/inbox/mentions

Returns posts and comments that mention your accounts, newest first. Answers { mentions, total, hasMore, nextCursor }.

API Key (Bearer token)

Permission:inbox.readRoles and permissions

Every role holds inbox.read, so any valid key can read the inbox.

Query parameters

Parameter	Type	Description
`accountIds`	`string[]`	Only these accounts, by the id from GET /social-accounts. Repeat the key or separate values with commas. Up to 50
`platforms`	`PlatformType[]`	Only these platforms. Repeat the key or separate values with commas
`statuses`	`InboxStatus[]`	Only items in these states: UNREAD, READ or DONE. Repeat the key or separate values with commas
`since`	`string (ISO 8601)`	Only items created on the platform at or after this date-time
`search`	`string`	Text to search for
`limit`	`number`	Items per page, 1 to 100. Default 25
`cursor`	`string`	The nextCursor of the previous page. nextCursor is null on the last page

About 10 minutes, not real time

AdaptlyPost reads each connected account every 10 minutes and keeps what it finds. The lists answer from that copy, so a new comment, mention, message or review shows up within about 10 minutes. POST /api/v1/inbox/refresh asks for a read now. Webhook events come from the same reads.

Channels that need a reconnect

Every channel is open to the API. When a connection lacks the platform permission for a channel or action, including permissions the platform is still reviewing for AdaptlyPost, GET /api/v1/inbox/summary shows the channel as RECONNECT_REQUIRED and every write on it answers 403 inbox_reconnect_required. An expired token answers the same. Ask the user to reconnect the account in AdaptlyPost; retrying does not help.

Mention fields

Field	Description
`id`	Mention id. Use it with the endpoints below
`accountId`	The account the item belongs to: its id from GET /social-accounts
`platform`	The platform, as a PlatformType
`accountName`	Display name of that account
`platformMentionId`	The platform's id of the post or comment that mentions the account
`author`	Who wrote it: id (the platform's user id), name, username and avatarUrl. id, username and avatarUrl can be null
`text`	The text that mentions the account
`permalink`	Public link on the platform, or null when the platform gives none
`thumbnailUrl`	Image of the post, or null
`createdAt`	When it was created on the platform
`status`	UNREAD, READ or DONE. Only AdaptlyPost keeps this state; the platform does not see it
`replied`	True when your account replied through AdaptlyPost
`repliedAt`	When your account last replied, or null
`capabilities`	canReply: false when the platform does not let the account answer, as with Instagram mentions
`replies`	Replies sent through AdaptlyPost, oldest first, each with id, text, permalink and createdAt. Replies written in the platform's own app are not listed

Reply to a mention

POSThttps://post.adaptlypost.com/post/api/v1/inbox/mentions/:id/reply

Answers the post or comment that mentions the account, from that account, and answers 201 with the mention. On Mastodon the reply keeps the visibility of the original post.

API Key (Bearer token)

Permission:inbox.replyRoles and permissions

Writes need inbox.reply (Admin and Editor) and an active AdaptlyPost plan. Without the plan they answer 403 subscription_required.

Body parameters

Parameter	Type	Description
`text`REQUIRED	`string`	The reply. It follows the platform's comment limit: Threads 500, Bluesky 300, Mastodon 500 and Facebook 8000 characters

Mark as read or done

POSThttps://post.adaptlypost.com/post/api/v1/inbox/mentions/status

Sets the status of up to 100 mentions and answers { mentions, unreadCount }.

API Key (Bearer token)

Permission:inbox.replyRoles and permissions

Body parameters

Parameter	Type	Description
`ids`REQUIRED	`string[]`	1 to 100 ids from the list
`status`REQUIRED	`InboxStatus`	UNREAD, READ or DONE

Refusals

A refused call answers { statusCode, error, code, message }. Branch on code. message explains the refusal in words.

Code	Status	When, and what to do
`inbox_item_not_found`	404	The id does not exist or belongs to another workspace. Stop
`inbox_action_unsupported`	400	The platform, or this item, does not allow this hide, delete or like. capabilities says what applies. Stop
`inbox_reconnect_required`	403	The connection lacks the permission for this channel or action, including one still in platform review, or its token expired. Ask the user to reconnect the account in AdaptlyPost. Do not retry
`inbox_reply_invalid`	400	The text is empty or over the limit. The message names the limit. Fix the text
`inbox_messaging_window_closed`	400	Facebook or Instagram: the 24-hour reply window has passed. Stop
`inbox_rate_limited`	429	The platform rate limited AdaptlyPost. Retry after a while
`inbox_platform_error`	503	The platform failed. Retry later
`permission_denied`	403	The key's role lacks inbox.read or inbox.reply. Do not retry
`subscription_required`	403	A write without an active AdaptlyPost plan. Do not retry

List new mentions

curl --request GET \
  --url 'https://post.adaptlypost.com/post/api/v1/inbox/mentions?statuses=UNREAD&since=2026-11-01T00:00:00Z' \
  --header 'Authorization: Bearer <api-key>'

Reply to a mention

curl --request POST \
  --url https://post.adaptlypost.com/post/api/v1/inbox/mentions/mnt_41c7e0b2/reply \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{ "text": "Thanks for the shout-out!" }'

Mark a mention as read

curl --request POST \
  --url https://post.adaptlypost.com/post/api/v1/inbox/mentions/status \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{ "ids": ["mnt_41c7e0b2"], "status": "READ" }'

200

{
  "mentions": [
    {
      "id": "mnt_41c7e0b2",
      "accountId": "conn_bsky_001",
      "platform": "BLUESKY",
      "accountName": "adaptlypost.com",
      "platformMentionId": "at://did:plc:4k2x.../app.bsky.feed.post/3lb2x7q",
      "author": {
        "id": "did:plc:7f3q2m",
        "name": "Marta Nowak",
        "username": "marta.bsky.social",
        "avatarUrl": null
      },
      "text": "Scheduling a month of posts with @adaptlypost.com took me 20 minutes",
      "permalink": "https://bsky.app/profile/marta.bsky.social/post/3lb2x7q",
      "thumbnailUrl": null,
      "createdAt": "2026-11-07T18:03:10.000Z",
      "status": "UNREAD",
      "replied": false,
      "repliedAt": null,
      "capabilities": { "canReply": true },
      "replies": []
    }
  ],
  "total": 3,
  "hasMore": false,
  "nextCursor": null
}