Migration Guide

Migrate Email from a Local Mail System to Microsoft 365

Step by step, using the DKS Portal and the DKS Profile Migration Agent — from creating the batch to verifying the last mailbox.

Overview

This covers moving mailboxes from a local/on-premises mail system (Outlook connected via POP3, IMAP, or on-prem Exchange) into Microsoft 365. The DKS Agent runs on each end user's machine and does the actual work in three stages: Export the local mailbox to a PST, Reconfigure the Outlook profile to point at the new M365 mailbox, then Import the PST into it. The Portal orchestrates and tracks every machine; it never touches the mailbox content itself.

This is a management and orchestration layer for a real migration process, not an automatic, zero-touch black box. Expect to review readiness, handle a few machines that need manual attention (ambiguous accounts, closed Outlook, etc.), and verify results before calling a batch complete.

Prerequisites

  • A Customer record for this organization in the Portal.
  • The target Microsoft 365 tenant ready: licenses assigned and mailboxes already provisioned for every user you're migrating.
  • End-user machines on Windows 10/11 with Outlook installed, currently connected to the local mail system.
  • A network share reachable from those machines, to hold exported PST backups.
  • Staff access to the Portal ([Authorize(Policy = "Staff")] pages: Batches, Agent Installer, Devices).

Step 1 — Create the Customer

Portal → Customers → Add Customer, if one doesn't already exist for this organization.

Step 2 — Create the Migration Batch

Portal → Batches → Create Migration Batch:

  • Customer: the one from Step 1.
  • Source Platform: IMAP or Exchange — whichever matches the local mail system.
  • Destination Platform: Microsoft 365.
  • Migration Type: Export + Reconfigure + Import — the standard agent-driven pipeline for this scenario.
  • Backup PST Path: the network share from the prerequisites (e.g. \\NAS\PST-Migration\CustomerName).
  • Import Target Folder: leave empty to merge into the mailbox's normal folders (Inbox→Inbox, Sent Items→Sent Items, etc.), or set a subfolder name to land everything under one folder instead.

Step 3 — Generate an Agent Token

Portal → Agent Installer → select the batch → Generate New Token. This token is what ties every machine that installs the agent back to this specific batch and customer.

Step 4 — Deploy the Agent

Push DKSProfileAgent.msi to the target machines with this batch's Agent Token and Customer Code. See the separate GPO Deployment Guide for the full step-by-step (one GPO Scheduled Task, no per-customer installer needed).

Step 5 — User mapping (only if a machine has more than one account)

The agent auto-detects the source mailbox when a machine has exactly one POP3/IMAP account configured — no mapping needed. If a machine has multiple accounts, the agent can't tell which one to migrate on its own, and will stop with “Needs Manual Action.” For those cases, add a user mapping (CSV import on the batch, or set the target mailbox directly on the device) so the agent knows which account is which user's.

Step 6 — Let the first pass run automatically

Once installed and a user signs in, the agent registers with the Portal and automatically detects Outlook, scans the profile, and locates the source mailbox/PST — no button required for this part. Check Portal → Devices: a row appears for each machine, with its current step (e.g. PstFound, or Needs Manual Action if a mapping is required — see Step 5).

Step 7 — Run the migration steps

From the Devices page, open a device and send each remaining step as a command:

  1. Export PST — copies the local mailbox to the backup path from Step 2.
  2. Reconfigure Profile — points Outlook at the new Microsoft 365 mailbox.
  3. Import PST — brings the exported mail into the new mailbox.

Each command is picked up on the agent's next check-in (roughly every 30 seconds). Progress and a per-item log (which messages migrated, skipped, or failed) stream back to that device's detail page as it runs.

Step 8 — Verify

  • Confirm the M365 mailbox actually has the migrated folders and a sensible item count.
  • Check the device's log for anything marked Failed or Warning and re-run just that step if needed (Retry Failed).
  • Once every device in the batch reports Completed, mark the batch complete.

Step 9 — Decommission (optional)

Once a machine's migration is verified, send the Uninstall command to remove the agent. If the batch has PST cleanup enabled, this also removes the source and backup PST files — only do this after you're confident the migration succeeded, since it's not reversible.

Questions during a migration? Contact your DKS support representative.