Inbox MS365 — Entra ID setup
How to connect a Microsoft 365 mailbox as an inbox source. The credentials below live in theinbox.ms365 config block; token handling is automatic after initial sign-in.
:::warning
Never commit real tenant ids, client ids/secrets, or token files to the repo. Put secrets
in environment-managed secret management and reference them from config.
:::
1. Register the Entra app
- In the Azure portal → Microsoft Entra ID → App registrations, choose New registration.
- Name it (e.g.
openclaw-inbox). Supported account type: single tenant is the normal case. - No redirect URI is required for the device-code flow.
- Under Authentication → Advanced settings, set Allow public client flows to Yes and save. Device-code sign-in runs WITHOUT a client secret, so Entra rejects it unless the app is enabled as a public client — skipping this step leaves the first sign-in failing.
- Copy the Application (client) ID and the Directory (tenant) ID/domain — these
become
inbox.ms365.clientIdandinbox.ms365.tenantId.
2. Pick an auth mode
Application-permission blast radius: app-only tokens carry application permissions
that can read every mailbox in the tenant, not just the configured one. Restrict the
app’s data access with an application access policy
in Exchange Online (e.g.
New-ApplicationAccessPolicy -AppId <clientId> ...). This is a
documented limitation of the Graph application model — the configured mailbox key
selects the mailbox the source reads, but it does not narrow the token itself.
Delegated
- Add delegated Graph permissions:
Mail.ReadWrite,Mail.Send, plusoffline_access(usually granted by default) andUser.Read. - Grant admin consent if your tenant requires it for these scopes.
- No client secret is needed for device-code sign-in.
App-only
- Add application Graph permissions:
Mail.ReadWrite,Mail.Send. - Grant admin consent (required for application permissions).
- Create a client secret under Certificates & secrets — this becomes
inbox.ms365.clientSecret(sensitive; keep it out of committed config). - Set
inbox.ms365.mailboxto the mailbox Graph should operate on.
3. Configure
inbox.ms365 block is also the inbox enablement: ms365 is a dedicated inbox-only
source, so no inbox.sources.ms365 key is required or read.
Optional keys:
inbox.ms365.authMode—"delegated"(default) or"appOnly".inbox.ms365.scopes— delegated OAuth scopes. Default["Mail.ReadWrite","Mail.Send","offline_access"]. Keepoffline_access: the Microsoft identity v2 endpoint issues refresh tokens only when the initial token request grantsoffline_access; without it every token expiry requires a fresh device-code sign-in. App-only mode ignores this key and always requestshttps://graph.microsoft.com/.default.inbox.ms365.tokenStorePath— token cache file. Default<stateDir>/inbox/ms365-token.json, written with0600permissions. Protect the state directory accordingly.inbox.ms365.notificationUrl— full public HTTPS URL of the ms365 webhook route (e.g.https://gateway.example.com/plugins/inbox/ms365-graph). When set, the source creates Graph change-notification subscriptions against that URL; when unset, no subscriptions are created and the source runs delta-poll-only (works fine for credential-less/dev setups, at the cost of polling latency).
4. Sign in (delegated)
Sign-in is always something you start. The gateway never starts a sign-in by itself. You can start it three ways; each shows a verification URL and a short code.-
Control UI. Open Channels. The Microsoft 365 inbox panel shows the sign-in state.
Select Start sign-in, then open the URL in any browser and enter the code. The panel needs
an operator connection with
operator.admin. -
Ask the agent. Ask it to sign the inbox in to Microsoft 365. The
inbox.ms365_signintool asks you to approve the request, then replies with the URL and code. Only the owner can use the tool, and it starts nothing if you deny the approval or let it time out. -
CLI on the gateway host.
inbox.ms365.tokenStorePath and renewed automatically
after that. The gateway picks up the sign-in on its next eligible poll, normally within 15
minutes. An existing failure cooldown can delay that poll.
Only one sign-in runs at a time. Starting another while a code is pending is refused, and the
refusal carries the pending code. A code expires after about 15 minutes; start again after
that. The gateway methods behind the panel are inbox.ms365.signin.start and
inbox.ms365.signin.status, both operator.admin.
App-only mode needs no interactive sign-in; login loads a token silently, reusing an unexpired
cached token or acquiring one with client credentials, and the panel shows no start button.
In delegated mode without cached credentials, the source makes no calls to Microsoft.
If Microsoft rejects a refresh token, that one failed refresh removes the rejected grant;
subsequent polls make no network calls until you sign in. The source never starts sign-ins
in the background. On entering the signed-out state, it requests an agent nudge that says:
agentTurn.agents grant for the inbox plugin. The bundled inbox
plugin ships this grant as a manifest default (agents: ["main"]), so you need no manual
config when your default agent is main. To target a different agent, or to turn the nudge
off, set plugins.entries.inbox.grants.agentTurn.agents explicitly. Your setting always
overrides the manifest default, and an empty list turns the nudge off:
Polling backoff
The delta poll runs every 15 minutes. After a failed pass (Graph 5xx, network, token endpoint) the source waits longer before the next attempt. The wait doubles from 15 minutes up to a cap of 2 hours, with some randomness so attempts don’t line up, and is never shorter than a GraphRetry-After. These waits are minimum cooldowns: the next attempt runs on the
first 15-minute poll after the cooldown ends, so actual spacing can include another poll
interval. Each failure logs one warning with the earliest retry time. Renewal has its own
cooldown, so delta failures do not suppress the daily renewal. A failed renewal is retried
at its next daily tick. A successful pass resets its own cooldown. A Graph 429 pauses every Graph
call (live ingest, actions, backfill) until the Retry-After window ends, so nothing retries
while the mailbox is throttled.
First sync
A folder’s first delta round is a baseline. It pages the folder’s existing mail with slim requests, stores the delta checkpoint, and ingests none of that history. The baseline ingests no mail received more than 10 minutes before it started. Its start is fixed when Graph answers the folder’s first page, so a retry after a failed first page keeps it. Mail received from that point on reaches the live ingest, so a first sync never floods consumers with push alerts, classification or nudges for old messages. Mail that already exists in the mailbox is imported separately withopenclaw inbox backfill --source ms365, which never fans out as live signal. When the
baseline completes, the log records it:
5. Verify
- The configured tenant/client id parse and the token file appears under the state dir after sign-in.
inbox.list/inbox.searchreturn ms365 items alongside other sources.- With
notificationUrlset, Graph subscription renewal should log no duplicate subscriptions on restart. - On first sync, the delta poll logs
ms365 delta baseline established; existing mail is not imported (run: openclaw inbox backfill --source ms365)for each folder, and no mail received more than 10 minutes before the baseline started reaches the live ingest.
6. Change notifications (webhook route)
Wheninbox.ms365.notificationUrl is set, the source registers the Graph notification
route at /plugins/inbox/ms365-graph (exact match, plugin auth — Graph cannot
present a gateway token; the per-subscription clientState secret is the route’s auth
mechanism). Point notificationUrl at the full public HTTPS URL of that route, e.g.
https://gateway.example.com/plugins/inbox/ms365-graph.
Behavior:
- Validation handshake —
POST ?validationToken=...is answered200 text/plainechoing the URL-decoded token (Graph webhook contract). - Change notifications — every entry’s
clientStateis verified against the persisted per-subscription secret BEFORE any dispatch; missing/mismatched entries are rejected without ingest or reconciliation. - Lifecycle notifications —
reauthorizationRequiredtriggers renewal,subscriptionRemovedtriggers recreate,missedtriggers a delta resync pass. - Renewal — subscriptions are renewed daily against Graph’s 7-day maximum lifetime
(10,080 minutes); subscription id, resource, and
clientStatepersist in the inbox cursor rows so restarts resume without duplicates. A 409 on create (lost create response) is recovered by adopting the ownership-verified existing subscription, never by creating a duplicate. - Delta fallback — each folder is polled in slim paged rounds: delta requests select
isRead,categories,parentFolderId,receivedDateTimeand carryPrefer: odata.maxpagesize=100, and one page is fetched per request. Every page commits its checkpoint to the folder’s own cursor row as JSON{"link":...,"mode":"baseline"|"resync"|"live","since":...}(mid-round checkpoints also carry the round’s"started"time; a baseline whose first page has been fetched but not yet committed stores"link":null, so a retry keeps the baseline’s start), so a failed page resumes from the last committed page on the next poll instead of restarting at page 1.@removedentries are verified at mailbox level before account-scoped replica tombstoning (rows are marked deleted, never removed; a moved message keeps its row). A Graph sync reset (410, or a 40XsyncStateNotFound/resyncRequired) restarts the folder once as a deletion-free resync that re-ingests only mail received since the last sync point minus 10 minutes (legacy bare cursors take the full deletion-free resync). Folders fail independently. An ordinary error on one folder does not block the others, and it still arms the polling cooldown. A signed-out account or a Graph429stops the pass at once, because the sign-in gate and the throttle window own those cases. A signed-out skip does not arm the cooldown.
notificationUrl unset, no subscriptions are created (one warn at startup) and the
source runs delta-poll-only.
Backfill
wednesdayai inbox backfill --source ms365 [--account <id>] [--since <iso>] [--all] pulls
mailbox history into the inbox store with the manual, resumable, per-page checkpointed
contract described in Inbox API. The ms365-specific
behavior:
- Folder coverage — the walk covers Inbox and then Sent Items — the same
folder set the delta poll covers. That parity holds for delta polling only: with
delegated auth and
notificationUrlconfigured, the live change-notification subscription targets the wholesaleme/messagesresource and verified notifications ingest without a folder filter, so Archive-only mail can be ingested live even though backfill never walks it. - Paging — Graph list pages of
$top=100, ordered byreceivedDateTime desc, paged by the response’s@odata.nextLink(which embeds the$skiptoken) and replayed verbatim — never re-assembled. With--since, the first page of each folder adds a server-side$filter=receivedDateTime ge <since>; a client-side timestamp guard under that filter drops anything older that a$skiptokenboundary still returns. - Checkpoints — the opaque resume position is JSON
{"f":<folder index>,"link":<nextLink|null>}in thebackfill:<account>cursor row: the walk exhausts Inbox, advances to Sent Items, then reports done. - Throttling and sign-in: pages use the same Graph client rules as the live delta poll.
The client retries once after a
Retry-Afterof up to 30 s. A longer wait ends the run with a typed throttling error and pauses that client until the window passes. The checkpoint lets the next run resume from the last committed page. Backfill never starts a sign-in. When signed out, the run stops at once withms365 sign-in required — start it from the Control UI (Channels → Microsoft 365 inbox) or run `wednesdayai inbox ms365 login` on the gateway host. - Message shape — backfill pages and the live
GET /me/messages/{id}fetch send the same explicit$select(MS365_MESSAGE_SELECT, includinginternetMessageHeaders), so backfilled rows carry the sameraw_jsonfields as live-ingested ones. Attachment metadata is hydrated per message exactly as on ingest. A--allre-walk also addsinternetMessageHeadersto rows stored before the select carried them; it never replaces a storedraw_jsonfield (#2544).
inbox.ms365 config block itself (tenantId + clientId required):
the CLI fails with inbox source ms365 is not configured, and in the agent tool an
unconfigured ms365 is simply not a registered backfill source. The walk is single-mailbox
— the configured mailbox — matching the source’s account model.