Inbox API
The inbox plugin exposes a versioned, consumer-grade client API over the gateway WebSocket:inbox.v1.list, inbox.v1.thread, inbox.v1.action, and inbox.v1.capabilities. The
methods are registered by the inbox plugin (extensions/inbox) via
api.registerGatewayMethod and dispatched like any other gateway method.
- Wire payloads are camelCase; pagination cursors are opaque strings.
- Item ids are deterministic
<source>:<account_id>:<source_id>composites. availableActions(a string array) rides on every serialized item; clients must gate their triage UI on it — a source without an action adapter reports fewer or no actions.- The wire
PROTOCOL_VERSIONhandshake is unaffected by this API.
Scopes and ownership
inbox.v1.list,inbox.v1.thread, andinbox.v1.capabilitiesrequireoperator.sessions.read(narrow) or operator scopes;inbox.v1.actionrequiresoperator.sessions.writeor operator scopes. Unclassified methods fail closed tooperator.admin.- Ownership follows the authorization-binding decision (D8): the inbox store is
session-less, so each ingesting
(source, account_id)is bound to a user principal ininbox_account_owners. Bindings are managed withwednesdayai inbox owners bind|unbind(theinbox.owners.bind/inbox.owners.unbindgateway RPCs,operator.admin) and take effect immediately; theinbox.ownersconfig key is a load-time seed kept in sync by the CLI, and a hand edit applies at the next gateway start. Narrow-scope callers (openclaw-user-client, e.g. apps/web and WednesdayAI-glass) resolve to their user and may list, read, and action only items whose(source, account_id)they own. The check binds to the item’s stored(source, account_id), never to request params — guessing another user’s item id is denied. Unowned accounts stay operator-visible only; operator/system sees everything. Enforcement sits in the method handler, never client-side. - A narrow caller with no owned accounts gets an empty result, not an error.
Methods
inbox.v1.list
Lists inbox items, newest first, filtered and paginated.
Params:
Result:
{ items, nextBefore?, unreadTotal? } — items is an array of serialized items,
each including availableActions. unreadTotal is the caller’s authoritative unread count
(ownership-scoped, independent of the list’s own filters): client badges must read it
rather than deriving a count from loaded pages. nextBefore is present only when the page
truncated; pass it back as before to fetch the next page. Cursors are opaque: clients
must not construct or parse them, and an unparseable before fails with INVALID_REQUEST
rather than resetting the page.
inbox.v1.thread
Reads one thread with its items, interleaved by timestamp (sent + received).
Params: source (required), threadKey (required), accountId (optional).
Result: { thread, items, itemsTruncated? } — thread is the thread row (title,
participant, reply state, last-seen markers); items is the complete ordered item list
with availableActions. There is no thread-level cursor; completeness is exact up to the
server’s hard cap of 1000 items, past which the response is cut and itemsTruncated is
true.
Account ambiguity: when accountId is omitted and the source has exactly one configured
account, that account is the default. Several configured accounts → the request fails with
an INVALID_REQUEST ambiguity error rather than silently merging accounts.
inbox.v1.action
Performs a triage action on one item by id.
Params:
Result:
{ ok, reason? } — reason is set when ok is false.
Action semantics:
replycarries atextpayload, requires thereplygrant, and is confirmed through a server-side operator-approval flow before the outward send. Denial surfaces as{ ok: false, reason: "confirmation-denied" }; an approval timeout surfaces as{ ok: false, reason: "confirmation-timeout" }.convert-to-taskreturns{ ok: false, reason: "unsupported until the task bridge lands" }.recategorizeis store-level: it writes an inbox correction, setscategory_source='manual', and clears the policy flag. It needs no source adapter and never touches the source.- The other mutating actions dispatch to the registered source adapter; a source without adapter support for the action returns an unsupported-action error.
UNAVAILABLE and message
"<source> action failed: <cause>" (for example,
gmail action failed: gog binary not found on PATH; gmail ingest requires gog (openclaw/gogcli)).
Store failures return a gateway error with code UNAVAILABLE and message
inbox store unavailable, including a store write inside a source adapter, which stays a
store failure and does not surface as a source failure. Authorization, unsupported-action and
unknown-category errors return code INVALID_REQUEST. These are gateway errors, not
{ ok: false, reason } results.
inbox.v1.capabilities
Params: none (empty object).
Result: { sources: Array<{ source, actions: string[] }>, caller: Caller } — per source,
the mutating actions its adapter currently supports (intersection of the adapter’s
declared actions with the supported action set). Clients use this to hide triage
affordances up front, alongside per-item availableActions.
Caller describes the caller’s posture and mailbox scope:
posture:"operator"for operator/system connections,"narrow"for user clients.personResolved: whether the narrow identity resolved to a person (operator callers are always resolved). A narrow caller whose device is not insession.identityLinksreportsfalseand owns nothing.accounts:Array<{ source, accountId, unread }>— for a narrow caller, the accounts bound to its person ininbox_account_owners; for an operator, every ingested account.unreaduses the same predicate asunreadTotal.
caller result field is additive on the wire but not yet declared
in the strict protocol schema — any declared registry change forces a protocol major, so
declaration waits for the next one. Tolerant readers must accept the field’s presence
(and treat an absent caller as null — older gateways never send it); validators pinned
to the generated schema cannot read the new field until then.
Item shape
Every serialized item includes:id, source, accountId, sourceId, threadKey,
direction (in / out), sender, recipient, subject, preview, labels
(source-native label names, e.g. Gmail’s — distinct from category, the inbox
classification taxonomy), ts (ms epoch), sourceReadState, category, policyFlag,
deleted (boolean — the source deleted this item; the row is retained as a tombstone,
never erased), deletedAt (first tombstone timestamp, ms epoch, or null), archived
(boolean — this item is archived; archived items are excluded from unreadTotal and
caller.accounts[].unread), and availableActions: string[].
sender, recipient, subject, and preview are raw sender-controlled UTF-8. Any
consumer feeding them into a model context MUST apply its own untrusted-content fencing —
the agent tool surface does this server-side; the client API does not.
Message bodies
Email bodies (gmail, ms365) are stored as markdown rendered from the message’s HTML part, or from its plain-text part when there is no HTML. Links, headings, lists, quotes, and data tables survive; scripts, styles, tracking pixels, and layout tables do not. The raw HTML and plain-text variants are kept alongside the rendering. Chat sources (WhatsApp, Discord, iMessage, …) store message text unchanged. Search matches against the markdown. The agentinbox.read tool returns the markdown body by default; variant: "html" or
variant: "text" returns the stored raw variant instead (null when the source delivered
none). A body that inbox.read fetches on demand keeps its raw variants even when it
renders to no markdown (an image-only message), so the variant reads still work. Rows
ingested before markdown rendering keep their original body until a re-ingest or
wednesdayai inbox backfill --convert re-renders them.
A rendering is replaced at most once: when gmail’s push delivers only the plain-text body
and a later re-ingest of the same message brings its HTML part, the HTML rendering
supersedes the plain-text one. An HTML rendering is final. Each raw variant is stored once:
a later ingest can add a missing HTML or plain-text variant but never changes a stored one.
Wire-schema note: includeArchived / includeDeleted and the deleted / deletedAt /
archived item fields are additive on the wire but not yet declared in the strict
protocol schema — any declared registry change forces a protocol major, so declaration
waits for the next one. Tolerant readers must accept the fields’ presence; validators pinned to the generated
schema cannot send the new params until then.
Retention and deletion
The inbox never erases ingested data. When a source reports an item deleted (Gmail deletion pushes, Microsoft 365 deletion notifications), the row is marked, not removed:deleted is set to true with the first tombstone timestamp kept in deletedAt, and the
row is retained permanently.
Item state machine:
active ↔ archived— archiving is reversible through source truth; there is no unarchive action.active | archived → deleted— deletion is terminal. Deleted dominates archived: a deleted item keeps its archived state underneath, but archived has no visibility effect while deleted.
- Default list views (
inbox.v1.list, the agentinbox.listtool, the CLI), unread counts, and search exclude deleted items. includeDeleted: trueoninbox.list/inbox.v1.listopts in to tombstoned rows, returned with theirdeleted/deletedAtmark.- The thread view (
inbox.v1.thread) is the historical view: it always includes deleted rows with their mark.
Source enablement
Inbox ingestion is opt-in: dual-capable channel sources (e.g. bluebubbles, discord, whatsapp-web) ingest into the inbox only withinbox.sources.<id>.enabled: true; dedicated
inbox-only sources (gmail, ms365) are enabled by their existing hooks.gmail /
inbox.ms365 config block — no inbox.sources key is required or read for them.
For whatsapp-web specifically: with the source enabled, every chat on the linked account
(both live messages and history batches) is ingested, unread state tracks the phone
(read receipts stop for history and group traffic; phone chats.update unread-count
clears are mirrored as chat-level read marks), and reply / mark-read become available
once listed under plugins.entries.inbox.grants.inbox.actions (both default-deny). reply always goes through the operator
approval flow and honours the WhatsApp channel’s outbound allowFrom policy; mark-read
sends a read receipt on the phone (sock.readMessages on the stored native message key).
Read state is one-way for whatsapp-web: once a row is read, a re-delivered message never
returns it to unread (WhatsApp mark-unread is not mirrored).
Thread keys are E.164 for resolved DMs, the group JID for groups, and the raw JID
(including LID-only chats) as fallback; replies always target the thread key, so a group
reply goes to the group.
Backfill
Backfill pulls source history into the inbox store soinbox.search answers over
multi-year mailboxes, not just first-run forward. It is manual and resumable: an operator
runs wednesdayai inbox backfill, or the agent drives the inbox.backfill tool. Backfill
reuses the live write path — every page upserts through the same store machinery that
live ingestion uses, so dedupe identity, pending tombstone intents, and thread rollups
apply unchanged — but never fans out as live ingest signal (no urgent nudges, no
classify-on-ingest, no next-turn side effects).
wednesdayai inbox backfill
--since, --all, and --convert are mutually exclusive. Flag semantics:
--since Xresumes an existing checkpoint only when its anchor equals X; a checkpoint for a different anchor is abandoned and a fresh ranged walk starts.--allforces a fresh full walk regardless of any persisted checkpoint.- With neither flag the walk is full history (
since = null) and resumes an unfinished checkpoint whose anchor is also null.
whatsapp.history.fetch, on-demand history on the linked phone): a
chat whose phone fetch times out (phone offline) is skipped for that run without failing
the walk. Only chats with stored messages are walked — live traffic or pairing-time history
seeds a chat with no rows. The anchor is the oldest row’s native message key; a row written
before the feed existed (no native key) anchors on a key rebuilt from its
<threadKey>:<message id> source id, and only legacy rows keyed by a bare uuid are skipped
with a warning. A chat counts as exhausted when the phone returns fewer native history
entries than the page size, counting entries the inbox does not store (reactions, protocol
messages). Rows upsert on the same <threadKey>:<message id> source id the live feed writes, so a
re-run over the same history inserts nothing new.
Interruption (including Ctrl-C) needs no special handling: each committed page advances
the checkpoint, so the next run resumes where the walk stopped. The CLI prints a live
progress line per account (pages, scanned, inserted) and a final summary per
account (scanned, inserted, updated, tombstoned, resumed vs fresh walk).
A precondition or fetch failure — source not enabled, source not configured, unknown source,
account not enabled for the source, invalid --since, or a missing transport — prints one
line to stderr with no stack trace and exits with status 1 (for example,
inbox source bluebubbles is not enabled). Each committed page advances the checkpoint, so
the next run resumes where the walk stopped.
Conversion mode
--convert (tool: mode: "convert") fetches nothing from the source. It walks the stored
gmail or ms365 rows of each enabled account whose body has not been rendered to markdown,
recovers the raw HTML/text from the stored source payload (or, for gmail rows hydrated
before rendering existed, from the stored body), renders it, and writes the markdown and the
raw variants in place. A row that live ingest renders while the conversion runs is left
alone. There is no checkpoint: converted rows never qualify again, so an interrupted run
simply continues on the next invocation, and a second run converts nothing. Rows with no
recoverable body (a gmail body gog truncated) count as skipped; inbox.read still hydrates
them on demand. The summary per account reads
Convert <source> <account>: <scanned> scanned, <converted> converted, <skipped> skipped.
inbox.backfill tool
The agent surface is a plugin tool — no gateway method and no grant (backfill is
source-read plus store-local write, the same class as the read-side tools). Ops:
Run status is
running, done, error, or cancelled; the snapshot carries mode.
Per-account progress counters: pages, scanned, inserted, updated, tombstoned,
plus resumed and done; convert runs also report converted and skipped.
Mutual exclusion is per (source, accountId) across both modes: different pairs may run
concurrently, the same pair may not (two runs would race the same rows, and two fetch walkers
the same checkpoint). Finished runs stay queryable; the last 20 are retained.
Errors: unknown source (names the supported ids), source not enabled, an accountId
outside the enabled list (names the enabled accounts), an invalid since timestamp,
since+all together, mode: "convert" with since or all, mode: "convert" on a
source other than gmail or ms365, and a conflict error when the (source, accountId) pair
already has a running run.
Checkpoints and resume
Checkpoints ride the existing inbox cursor rows — no new table, no schema change — under the scopebackfill:<accountId> (collision-free with the existing bare account scopes,
reconcile:<account>, and ms365-delta:<folderId>). The value is JSON
{"v":1,"since":<epoch-ms|null>,"position":<opaque string|null>,"done":<bool>};
position is fetcher-opaque and persisted verbatim.
Per-page atomicity mirrors the live scanner contract: inside one per-account ingest lock
the runner upserts the page item by item, then advances the cursor. A throw skips the
cursor advance; the resumed run re-fetches that page and the deduped upserts converge. A
corrupt checkpoint warns and starts a fresh walk (same convergence argument). A
next === position no-progress guard terminates a walk whose fetcher keeps returning its
own resume token.
Tombstones and classification
Deletion receipts that beat the ingest still win: a pending tombstone intent recorded before a backfilled id is inserted applies at upsert, so the row lands deleted with its tombstone timestamp (counted astombstoned in progress). Backfill itself never calls
source deletion APIs.
Backfilled inbound rows land unclassified and are picked up by the existing classify
retry sweep — unchanged: rows older than 60 seconds become eligible, whole-backlog
passes keyset-page 200 rows at a time, and a full analysis queue ends a pass without
consuming any item’s attempt budget. After a large backfill, live classification
degrades to the sweep’s cadence until the backlog drains; no item is lost.
Versioning
Method names are versioned. A breaking change ships a newinbox.v2.* family registered
side-by-side with inbox.v1.*; nothing is mutated in place. Clients discover which
methods the connected gateway serves via the hello-ok features.methods advertisement and
should feature-detect rather than assume.
Consumers
- First consumer: the apps/web v2 client chat (narrow
openclaw-user-clientidentity). - Second consumer: WednesdayAI-glass — server-side action execution there sidesteps iOS app-to-app restrictions.
- apps/control is not an inbox UI surface.