Inbox

Retrieve comments and replies across your connected channels, reply to them, and triage their status — all through simple, scriptable primitives. The Inbox is designed for AI agents (Claude, Cursor, Codex, and similar tools) that decide what to say, while Verlynk handles how to fetch and send it across platforms.

Verlynk does not generate reply text. You (or your agent) supply the message; Verlynk abstracts away each platform's comment API.

How it works

1. List items with inbox:list — normalized JSON across all platforms.
2. Decide externally which items deserve a reply (your logic, your agent, or a human).
3. Reply with inbox:reply <itemId> -m "...".
4. Optionally triage with inbox:status <itemId> --status CLOSED once handled.

Replying does not automatically change inboxStatus — call inbox:status explicitly if you want to mark an item CLOSED.

List inbox items

Date range is required (max 40 days).

verlynk inbox:list --from 2026-07-01 --to 2026-07-16
verlynk inbox:list --from 2026-07-01 --to 2026-07-16 --status OPEN --json
verlynk inbox:list --from 2026-07-01 --to 2026-07-16 --platform instagram --type COMMENT

Flag	Description
--from	Start date (required, YYYY-MM-DD)
--to	End date (required, max 40 days after --from)
--platform	Filter by platform (instagram, facebook, x, etc.)
--channel-id	Filter by channel/account UUID
--status	OPEN, FOLLOWUP, or CLOSED
--type	COMMENT (top-level only) or REPLY (replies only)
--by-time	newest (default) or oldest
--page	Page number (default 1)
--limit	Items per page (default 10, max 100)
--profile-id	Override profile for this command
--json	Output raw JSON

JSON response shape

{
  "items": [
    {
      "id": "b6b6a1d4-...",
      "type": "COMMENT",
      "platform": "instagram",
      "channelId": "c9f2...",
      "channelName": "My Brand",
      "inboxStatus": "OPEN",
      "createdAt": "2026-07-15T12:00:00.000Z",
      "author": { "name": "Jane Doe", "profileUrl": "https://instagram.com/janedoe" },
      "text": "Love this! Where can I buy it?",
      "isHidden": false,
      "canReply": true,
      "platformUrl": "https://instagram.com/p/.../c/...",
      "parent": null,
      "post": {
        "postId": "9e21...",
        "textPreview": "New collection just dropped 🎉",
        "publishAt": "2026-07-14T09:00:00.000Z"
      },
      "attachments": []
    }
  ],
  "pagination": { "page": 1, "limit": 10, "totalCount": 42, "totalPages": 5 }
}

• type: "REPLY" items include a parent: { id, text, author } object pointing at the top-level comment. canReply is always false for replies — reply-to-reply is not supported by any platform; reply to parent.id instead.
• canReply is derived purely from type and platform support — it does not mean "unanswered". Use inboxStatus for triage state.
• isHidden is informational only (a platform-side visibility flag) and never blocks canReply.

Reply to an inbox item

Only top-level comments (type: "COMMENT") can be replied to.

verlynk inbox:reply b6b6a1d4-... -m "Thanks so much! Link is in our bio 💜"
verlynk inbox:reply b6b6a1d4-... -m "Thanks!" --json

Flag	Description
<itemId>	Inbox item UUID from inbox:list (required, must be type: "COMMENT")
-m, --message	Reply text (required, non-empty)
--profile-id	Override profile for this command
--json	Output raw JSON

JSON response shape

{
  "ok": true,
  "itemId": "b6b6a1d4-...",
  "replyId": "f1a0...",
  "platform": "instagram",
  "message": "Thanks so much! Link is in our bio 💜"
}

replyId can be null even on success (some platforms confirm the send without returning a fresh row) — treat ok: true as the source of truth.

Update inbox item status

Status is a manual triage flag (OPEN / FOLLOWUP / CLOSED), independent from whether a reply was sent.

verlynk inbox:status b6b6a1d4-... --status CLOSED
verlynk inbox:status b6b6a1d4-... --status FOLLOWUP --json

Flag	Description
<itemId>	Inbox item UUID from inbox:list (required)
--status	OPEN, FOLLOWUP, or CLOSED (required)
--profile-id	Override profile for this command
--json	Output raw JSON

Agent workflow example

A typical agent loop: fetch open comments, decide externally which deserve a reply, generate the reply text with your own model, send it, then close the loop.

# 1. Fetch recent open comments as JSON
verlynk inbox:list --from 2026-07-01 --to 2026-07-16 --status OPEN --type COMMENT --json

# 2. (Agent reasoning happens outside Verlynk — decide which items to answer
#    and what to say. Verlynk never generates reply text.)

# 3. Send the reply the agent composed
verlynk inbox:reply <itemId> -m "<agent-generated text>" --json

# 4. Mark it handled
verlynk inbox:status <itemId> --status CLOSED --json

Constraints to design around

• Triage ≠ answered. inboxStatus is a manual flag your workflow controls — Verlynk never infers "replied" from it.
• Webhook-ingested, not live-fetched. Items appear once Verlynk's webhook receives them; there can be brief ingestion lag versus the native platform.
• 40-day window. --from/--to can span at most 40 days per call — paginate across ranges for longer backfills.
• Reply-to-reply is unsupported. Reply to the top-level comment (parent.id on a REPLY item), not to another reply.
• Comments need a linked Verlynk post. A comment only appears if it's on a post Verlynk published or imported — comments on posts Verlynk never touched won't list.
• Permissions follow the API key creator. inbox:list only returns channels where that user has comment view access; inbox:reply/inbox:status need create/edit access on the channel. An empty inbox does not necessarily mean there are no comments on the platform — check channel permissions first.

Errors

Inbox errors always include errorCode, retryable, and (when applicable) action — with --json, the CLI prints this as a single JSON object on stderr instead of free-form text, so agents don't need to scrape error strings.

errorCode	Meaning	retryable
INBOX_ITEM_NOT_FOUND	Item doesn't exist, or belongs to a different profile	No
REPLY_NOT_SUPPORTED	Item is a REPLY, or has no linked post	No
PLATFORM_NOT_SUPPORTED	Platform doesn't support replies (e.g. Pinterest, Google Business)	No
TOKEN_EXPIRED	Channel's platform connection expired — reconnect the channel	No
PROVIDER_ERROR	The social platform rejected the request	Yes
EMPTY_MESSAGE	--message was empty	No
INVALID_DATE_RANGE	--to before --from, or range exceeds 40 days	No
INBOX_ITEM_ALREADY_DELETED	Item was deleted on the platform before the reply could send	No

{
  "errorCode": "TOKEN_EXPIRED",
  "message": "The channel's connection to the platform has expired or was revoked.",
  "retryable": false,
  "action": "Reconnect the channel in Verlynk, then retry."
}

Next steps

• Posts — the posts an inbox comment links back to
• Accounts — list channel IDs to filter inbox:list
• API Reference — explore /v1/inbox directly