Migrate IMAP to Google Workspace: A Universal Mailbox Playbook

Generic IMAP migrations are the most common kind in the wild and the least documented. Most guides assume you are moving from a named cloud provider (Microsoft 365, Gmail, Yahoo) and skip the actual majority case: a company on cPanel mail, Plesk, Dovecot-on-a-VPS, or an old Roundcube install that has been running since 2014. This guide is for that case. We will use Google's Data Migration Service to pull from a generic IMAP source into Workspace, with the throttling, auth, and folder-mapping detail that determines whether the project takes a weekend or a month.

What "generic IMAP" actually means#

If your current mail server is anything other than a named cloud product, you are doing a generic IMAP migration. Common cases:

• cPanel / WHM mail (Dovecot under the hood, with a cPanel admin layer)
• Plesk mail (also typically Dovecot or Courier)
• Roundcube as a web UI sitting on top of Dovecot or Cyrus
• iRedMail, Mailcow, or other self-hosted stacks
• Custom Dovecot or Cyrus deployments on a Linux VPS
• Old Postfix + Courier setups still running on bare metal

All of these speak standard IMAP over port 993 with TLS. Workspace's Data Migration Service treats them identically: hostname, port, credentials, go.

The differences show up in auth: cPanel has a master admin user that can proxy as any mailbox; Dovecot has "master users"; Cyrus has SASL proxy. We will cover each.

For an even more general view of how the IMAP protocol behaves during migrations, see our IMAP protocol glossary — it is the reference for the flags, namespaces, and STATUS responses that drive every IMAP migration.

Pre-migration audit#

Pull a source inventory from your hosting control panel. The exact path depends on the stack:

• cPanel: WHM → List Accounts → click any account → Email Accounts. Or via SSH: find /home/*/mail -maxdepth 3 -type d -name "cur" shows every Maildir.
• Plesk: Mail → Mailboxes, or via CLI: plesk bin mail --list.
• Dovecot direct: doveadm mailbox status -A messages lists every mailbox with item counts.

Capture for each mailbox:

• Primary email address (this becomes the source side of the DMS mapping)
• Total size in GB
• Total item count
• Folder structure depth (deeper than eight nested levels causes problems)
• Whether 2FA / app passwords are required on the source

Workspace preparation#

Provision Workspace:

1. Verify the destination domain via TXT record. Wait for propagation (usually under an hour).
2. Bulk-create users via CSV upload. The Email column should exactly match the source mailbox addresses you intend to migrate.
3. Assign licences. Business Standard (2 TB per user) is appropriate for most generic-IMAP migrations; if any mailbox exceeds 30 GB, you cannot use Starter.
4. Do not change MX records yet. Workspace stays invisible to users until cutover.

Setting up DMS for IMAP#

In the Workspace Admin Console:

1. Navigate to Account → Data Migration → Set up data migration.
2. Migration source: Other email server (IMAP).
3. Connection protocol: IMAP.
4. Server: your source hostname (e.g., mail.yourdomain.com or srv12.hostingco.example).
5. Port: 993.
6. Authentication: TLS/SSL.
7. Role account: if your IMAP server supports proxy auth, enter the role account credentials here. If not, leave blank — DMS will prompt for per-user credentials when you add users.

Then Select migration start date and migration options:

• Date range: usually "all time" for an initial migration. Filter later if needed.
• Migrate deleted email: usually no.
• Migrate junk email: usually no.
• Folder exclusions: add Trash, Spam, and any folder you do not want to bring over.

Authentication: role accounts vs per-user#

Dovecot master users (cPanel, Plesk, most stacks):

# /etc/dovecot/conf.d/auth-master.conf.ext
passdb {
  driver = passwd-file
  args = /etc/dovecot/master-users
  master = yes
  pass = yes
}

Create a master user dms-migration with a strong password. In DMS, the role account format is typically dms-migration*user@domain — the asterisk separator tells Dovecot "authenticate as dms-migration and proxy to user@domain". Confirm your Dovecot config matches this format; some stacks use dms-migration%user@domain or other separators.

cPanel admin auth: cPanel allows the account holder's main login to access any mailbox under that account. If all your mailboxes are under one cPanel account, you can use the cPanel main user as the role account.

Per-user app passwords: if proxy auth is not available, you generate or collect app passwords for each user. This is operationally heavier but more secure — each access is auditable per user.

Adding users and starting#

Add migration users in DMS via CSV upload. The format depends on your auth choice:

• Role account: two columns, SourceAccount, DestinationAccount.
• Per-user: three columns, SourceAccount, Password, DestinationAccount.

For per-user CSVs, store the file in a secrets manager and delete after the migration completes. Treat it like a password file because it is one.

1. Pilot with three users

   Small (under 2 GB), medium (5 to 10 GB), large (20 GB or more). Let each complete fully before scaling.

2. Validate the pilot

   Per pilot user, log into Workspace Gmail. Check label counts (Workspace converts source folders to labels), total item count, sent items, read/unread state, and any starred or flagged items.

3. Scale in waves of 50

   DMS handles parallelism well on the destination side; your bottleneck is usually source-side throttling. Watch for Too many simultaneous connections and reduce batch size if it appears.

4. Export calendars and contacts separately

   Generic IMAP hosts do not move CalDAV/CardDAV data through DMS. Export ICS and vCard files via the web UI of each account or via the CalDAV/CardDAV admin tools, then import into Google.

5. Run delta migrations

   24 hours before cutover, run a delta. After MX cutover, run a final delta to capture in-flight messages.

Folder mapping and IMAP namespaces#

Generic IMAP servers vary in their folder naming. Common variants:

• INBOX, Sent, Drafts, Trash, Junk (standard)
• INBOX.Sent, INBOX.Drafts (hierarchical under INBOX, common on Cyrus)
• Sent Items, Deleted Items (Outlook-flavoured)
• Sent Messages (Apple Mail flavour)

DMS auto-maps the common variants to Workspace's equivalent labels:

Source folder	Destination label
Sent, Sent Items, Sent Messages	Sent
Drafts	Drafts
Trash, Deleted Items, Bin	Trash (usually excluded)
Junk, Spam	Spam (usually excluded)
INBOX	Inbox

Custom folders (Projects, Clients, Archive 2019) become same-named labels. Nested folders become labels with slashes.

If your source uses hierarchical separators that DMS does not auto-detect, you will see folders appear with the literal separator character in the label name. Test this in your pilot; if it occurs, the fix is to flatten the hierarchy on the source side via IMAP RENAME before migration.

DNS preparation#

Publish before cutover (do not wait):

• SPF: v=spf1 include:_spf.google.com ~all. If you currently include your hosting provider's SPF (e.g., include:spf.example-host.com), remove that include or keep it during a transition window.
• DKIM: enable in Admin Console → Apps → Gmail → Authenticate email. Publish the generated TXT record.
• DMARC: start at p=none with a reporting address, tighten to p=quarantine after 30 days of clean reports.

Change MX records only at the cutover moment.

Cutover sequence#

T-7 days: first user comms.

T-48 hours: drop MX TTL to 300 seconds.

T-24 hours: full DMS delta pass.

T-2 hours: notify users mail will be unavailable during the MX switch.

T-0: change MX records to Google's published values. Verify with dig MX yourdomain.com @8.8.8.8 @1.1.1.1.

T+15 minutes: send a test from an external account.

T+1 hour: run the final DMS delta.

T+24 hours: verify SPF, DKIM, DMARC alignment via Google Postmaster Tools.

Where Mailbox Taxi fits#

DMS is purpose-built for bulk IMAP-to-Workspace transfers. It does the full-mailbox case well.

Mailbox Taxi covers the cases where DMS is heavyweight or impractical:

• Single-mailbox transfers where setting up DMS is more work than the move
• Filtered migrations: only certain folders, certain date ranges, certain attachment sizes
• Re-runs for individual users after a DMS failure, without restarting the whole DMS job
• Air-gapped or restricted source servers where you do not want to expose IMAP credentials to a third-party cloud service
• Source servers without proxy auth where collecting per-user app passwords for DMS is impractical

It runs locally, speaks IMAP to both sides, and gives you per-folder control. Use DMS for the bulk and Mailbox Taxi for the outliers.

For the wider source-side reference, the IMAP migration guide is the right pillar. For the Gmail destination case (slightly different optimisations), see IMAP to Gmail. For Microsoft 365 as the destination, IMAP to Office 365.

Common errors and fixes#

AUTHENTICATIONFAILED — almost always wrong credentials, wrong proxy-auth separator, or 2FA blocking the source account. Re-test by IMAP-connecting from a local mail client with the same credentials.

Too many simultaneous connections — source-side throttling. Reduce DMS concurrent batch size. If your host is cPanel, you can request the host raise the per-account or per-server IMAP connection limit.

Folder UTF-7 conversion error — non-ASCII characters in folder names. Rename via webmail or IMAP RENAME before migrating.

Message too large for destination — Workspace accepts up to 50 MB per message via DMS. Messages over that limit fail. Export them via your source webmail's "Save as EML" feature, then upload to Drive or attach to a fresh message in Gmail.

STARTTLS handshake failed — your source IMAP server is presenting an expired or untrusted certificate. Renew the cert (Let's Encrypt is free) before migration. DMS will not skip cert validation.

OAuth2 token expired — not applicable for generic IMAP (no OAuth involved). If you see this, you accidentally configured DMS for OAuth instead of basic IMAP. Re-create the migration with IMAP auth.

Post-cutover validation#

Three checks in week one:

1. Per-user item count delta: compare source mailbox total items (from doveadm mailbox status -A messages or cPanel) to destination label totals. Variance under 1 percent is normal.
2. DNS alignment: Google Postmaster Tools shows SPF and DKIM passing within 72 hours.
3. End-user smoke tests: pick five users across departments, walk through their normal workflow.

After 30 days of stable Workspace operation, you can decommission the old IMAP server. Keep a read-only snapshot of the source mail store for another 90 days as a cold archive in case anything was missed.

For the wider program view across all migration types, the Workspace migration guide ties everything together.