Skip to main content

Current mailbox onboarding flow

mailGen/ECS_MovePST_To_TempSQL/GraphOneTimeUserOnboarder imports connected Outlook mailboxes. Prepare Microsoft Graph application access, PostgreSQL, Kafka, object storage, and search before starting onboarding.

Start and resume​

Use Connect and provision one mailbox for the supported /onboarding actions. The Microsoft connector requires a prepared, persisted tenant connection before its button is available.

Link the intended Microsoft identity if needed, select your owned connected account, and choose Start onboarding or Set up mailbox. The actor needs mail.onboarding. A pre-existing mailbox row or mailboxId is not a start prerequisite.

The BFF requests onboarding through app.onboarding.commands.v1. The command carries app-user and connected-account identity. The worker validates authorization before creating or loading a durable run. It resolves the provider mailbox ID separately. These identities serve different purposes.

Checkpoints let retryable steps resume without discarding the whole run. Startup also inspects incomplete runs. Replay requires explicit run authorization.

Import sequence​

  1. Resolve identity. Resolve providerMailboxUserId and check it against the authorized Entra subject. Create or update the mailbox-owner record, tenant connection, and local mailbox.
  2. Prepare synchronization. Create webhook subscriptions and initial puller state, then read the folder tree and reference data, including categories.
  3. Store messages. Read per-folder message metadata and upload bodies to S3. Store metadata and object keys in PostgreSQL.
  4. Export raw data. With Application permission MailboxItem.Export.All and tenant administrator consent, use Graph exportItems. Decode FastTransfer data and extract file attachments. Store their objects and metadata.
  5. Prepare search. Run indexing after durable metadata, body, export, and attachment storage passes its barrier.
  6. Assign order. Persist a stable mailbox queue partition and release work held for initialization.
  7. Complete initialization. Record lifecycle completion and queue mailbox.onboarding.initializingDone.

Raw export and FastTransfer attachment extraction are mandatory. The strict completion barrier checks both stages as well as reference data, messages, and indexing. A missing export permission cannot be replaced by ordinary mail-read access. See Graph application permissions.

The BFF opens the workspace after onboarding and its final initialization operation complete. Folder and message imports use Graph delta reads. Message requests use Prefer: IdType="ImmutableId" for stable IDs across moves within one mailbox.

Production boundary​

The production worker does not delete or reset test mail at startup. Development erasure is a separate, explicit workflow. See storage and recovery.