Skip to main content

Synced Mailboxes

Synced Mailboxes import Outlook mail into Files as .eml files plus attachments. Sync is one-way and additive: a remote delete, an empty listing, or a truncated walk never removes local files. Messages already imported are never re-imported — a message body does not change, so re-runs and layout updates stay safe.

Developer (individual) accounts cannot create mailbox watches. Callers degrade quietly on access errors rather than showing a hard failure.

Getting Started​

  1. Connect Outlook Mail under Integrations (user-level OAuth). You can also start the connection from the mailbox wizard in Files
  2. Open Files and switch to Synced Mailboxes
  3. Create watches: the wizard ticks Inbox and Sent Items by default. Each selected top-level folder becomes its own watch, sharing connection, schedule, and ingest options. Destinations are siblings under the parent you pick (for example Mail/Inbox, Mail/Sent Items)

Sent Items is a sibling of Inbox in Outlook, not a child — including subfolders of Inbox never imports Sent Items. Nested selections that overlap are blocked.

How mail lands in Files​

The local tree mirrors the mailbox folder tree:

Mail/Inbox/
Mail/Inbox/2026-08-11 Invoice [AbCd1234].eml
Mail/Inbox/Projects/Alpha/2026-08-11 Kickoff [Ef567890].eml
Mail/Inbox/Projects/Alpha/2026-08-11 Kickoff [Ef567890]/plan.pdf

Rules that keep this usable:

  • The body filename is YYYY-MM-DD Subject [token].eml. The token is derived from the provider id so two messages with the same subject do not overwrite each other, and a re-import overwrites in place
  • Attachments go in a subfolder named after the .eml, only if the message has attachments
  • Duplicate attachment names inside one message get (2), (3)
  • Very long paths flatten under the destination root rather than dropping the message

Older watches used a per-message subfolder layout. Mail imported that way stays where it is. A destination can contain both layouts; that is expected.

After import, .eml files and attachments go through the files pipeline (extract, optional categorize, optional ingest) like any other synced file.

Watch settings​

SettingWhat it controls
Include subfoldersWalk children of the watched root
Folder rulesInclude or exclude specific mail folders
Message filtersSince date, from addresses, subject contains
Ingest body / attachmentsWhether to store the .eml and/or attachments
Minimum attachment sizeSkip tiny attachments
CollectionsDefault collections on imported files
Lock destinationRead-only Files tree while the watch is active
ScheduleCron + timezone

Delta is per mail folder. A newly discovered subfolder bootstraps itself without forcing the rest of the mailbox to re-list. If a folder's change feed expires, only that folder re-bootstraps.

The first sync of a mailbox (bootstrap) does not fire a per-message "new mail" event for every historical message — that would overwhelm agents. A single mail sync completed event fires instead. Features that attribute mail to customers run a backfill after that first import.

Destination lock and connections​

A mail destination behaves like a folder-sync destination: content mutations are refused while locked; metadata (organization, collections, folder defaults) is still allowed.

You cannot place a mail destination inside, around, or equal to another active folder or mailbox destination. You also cannot create a second watch on a mail folder another watch on the same connection already covers.

Deleting an Integrations connection is blocked (HTTP 409) while folder or mailbox watches still use it — including paused watches. Disconnect the watches first. The UI can list blockers before you confirm.

Caps and partial runs​

Large mailboxes are walked with caps (folder count, depth, pages and time per folder). Hitting a cap finishes the run as partial with the gap visible in history, rather than silently importing less. Budget exhaustion on one folder keeps that folder's cursor and continues the walk — it does not restart that folder forever.

Resetting sync state clears change-feed cursors only. Already-imported messages stay skipped on the next bootstrap.

Customers and mail​

If Customers is enabled, attributed mail appears on the customer Mail tab. Matching uses contact addresses and verified domains. See the Customers guide for proposals, backfill, and why a first mailbox import is attributed in a sweep.

Best Practices​

  • Tick Inbox and Sent Items when you need both sides of a conversation
  • Use since-date and sender filters on large mailboxes before widening scope
  • Keep the destination dedicated to mail — do not mix it with a cloud folder mirror
  • Leave old layout folders in place; do not "clean up" by moving files the engine no longer tracks by path
  • Connect Outlook from Integrations or the wizard, then manage watches in Files — not the other way around

Troubleshooting​

First import finished but agents did not run per message​

Problem: You expected a workflow on every historical email. Solution: Bootstrap suppresses per-message events on purpose. Bind follow-up work to mail-sync-completed for the first import, or rely on customer mail backfill. Later (delta) mail can trigger per-message events.

The same email imported twice after I moved it in Outlook​

Problem: A moved message looks new. Solution: Outlook assigns a new id when mail changes folder. The platform also keys on the internet message id so a move should skip. If you still see a duplicate, check that both watches do not cover overlapping folders.

Cannot delete the Outlook connection​

Problem: Delete is blocked. Solution: Open connection dependencies and disconnect or delete the mailbox (and folder) watches first.

Developer account: mailbox tab errors​

Problem: Creating a watch fails. Solution: Mailbox sync is a corporate feature. Individual developer tenants cannot create watches.

Prerequisites​

  • An Outlook Mail connection in Integrations
  • The integrations access capability (corporate plans)

⏱️ Read time: 12 minutes | 📊 Difficulty: intermediate | 🔄 Last updated: 2026-08-30