# Runbook: move Gmail / Google Workspace (or any IMAP account) to Bundle Mail

> For AI agents acting for a Bundle admin. Human version: https://bundle.direct/blog/migrate-from-gmail-google-workspace
> Last checked against Bundle on 2026-10-25.

## Goal

Import every Google Workspace user's mail into Bundle mailboxes, keep new mail syncing while the domain's MX records move to Bundle, then stop syncing. Optionally import other accounts over IMAP. Google is only read (`gmail.readonly`).

## How you act

- Everything is in the Bundle web app (https://app.bundle.direct) → **Settings → Mail**, signed in as an **admin** (IMAP: an admin or a member of the target mailbox). Bot tokens can't reach these routes.
- Drive the user's signed-in session. Don't create accounts.
- **Never ask for passwords, app passwords or service-account keys in chat.** The human enters them in the field, or a password manager / secret-handoff tool fills them without revealing them to you.
- DNS changes affect live mail delivery. Confirm with the user before changing MX records, and save the current zone first.

## Prerequisites

- [ ] Bundle Mail is turned on for the workspace (beta, enabled per workspace on request). If **Settings → Mail** is missing, stop and tell the user to ask Bundle (https://bundle.direct/#founders).
- [ ] The domain is added in **Settings → Mail → Domains** and verified with the TXT record `_bundle-verify` = `bundle-verify=<token>` (needed for Bundle's client ID).
- [ ] A Google Workspace **super admin** is available, with an address on that verified domain.
- [ ] At least one Bundle mailbox exists ("Create a mailbox first: imported mail goes into one.").
- [ ] Access to the domain's DNS provider (human or tool), for the MX switch.

## Steps: Google Workspace

1. **Human step (Google admin approval):** in https://admin.google.com → **Security → Access and data control → API controls → Manage domain-wide delegation → Add new**:
   - Client ID: `116748696740436449695`
   - Scopes: `https://www.googleapis.com/auth/gmail.readonly,https://www.googleapis.com/auth/admin.directory.user.readonly`
   It can take minutes (up to 24 h) to apply.
2. Bundle: **Settings → Mail → Import mail → Connect Google Workspace**. **Super admin's address** = the admin's address; leave **Service account key (JSON)** empty; **Connect**. Bundle checks delegation immediately and explains if it's missing. (Alternative: the company's own service account key JSON, pasted by the human.)
3. The connection enters **Waiting for you** with **Choose whose mail to import**. For each person (menu "Mailbox for <email>"): an existing mailbox, **New mailbox <address>** (the person's own; held unreadable until they join if they aren't a member yet), or **Don't import**. Confirm the mapping with the user.
4. Click **Import N people**. Phases: Connecting → Counting messages → Importing → Syncing. People skipped for lack of a mailbox start automatically when a matching mailbox appears (checked every 10 min) unless set to Don't import.

## Steps: IMAP (any provider)

1. **Settings → Mail → Import mail → Add IMAP account**. **Import into**: the mailbox.
2. **Email address or username**: presets fill **IMAP server**, **Port** 993, **Security** SSL/TLS for Gmail (`imap.gmail.com`), Outlook/Hotmail/Live/MSN (`outlook.office365.com`), iCloud (`imap.mail.me.com`), Yahoo (`imap.mail.yahoo.com`), Zoho (`imap.zoho.com`), UOL (`imap.uol.com.br`), Terra (`imap.terra.com.br`). Others: enter by hand (ports below 1024 other than 143/993 and private hosts are refused).
3. **Human step (secret):** the account's **app password** goes into **Password** (Gmail: https://myaccount.google.com/apppasswords; requires 2-Step Verification).
4. **Check** → **Folders to import** (all but Drafts and virtual Starred/Important by default) → **Start import**.
5. Microsoft 365 work accounts may have IMAP disabled by the tenant; OAuth for IMAP isn't supported. IMAP messages over 24 MB are skipped (counted as failed).

## Switch MX (after history has caught up)

1. Save the current DNS zone (export it) so it can be restored.
2. Records from **Settings → Mail → Domains** (also **Download zone file**):
   - MX `@` → `mx1.bundle.direct` (10), `mx2.bundle.direct` (20)
   - TXT `@` → `v=spf1 include:_spf.bundle.direct ~all` (merge into one SPF record)
   - CNAME `bundle1._domainkey` → `<domainId>.dkim.bundle.direct`; CNAME `bounce` → `bounce.bundle.direct`; CNAME `_dmarc` → `_dmarc-<domainId>.bundle.direct`; optional CNAME `mta-sts` → `mta-sts.bundle.direct`
   - Remove the old MX records, the old SPF include and the old `_dmarc` record.
3. **Check DNS now** until the domain shows Receiving and Sending.
4. Keep the Google/IMAP connection syncing (every 5 minutes) for a few days so mail still arriving at Google comes over.
5. When nothing new arrives: **Remove** the connection ("Stop syncing? The mail already imported stays."). **Human step:** delete the delegation entry in the Google Admin console.

## Mapping and limits

- Gmail INBOX → Inbox; SENT → Sent; archived/user labels → Archive; SPAM → Spam; TRASH → Trash; UNREAD/STARRED kept; DRAFT not imported; label names not kept. IMAP folders map the same way.
- Threads rebuilt from Message-ID/In-Reply-To/References. Duplicates (same Message-ID) skipped. Nothing is marked read at the source.
- History never notifies. AI tab sorting for history: inbox, last 30 days, ≤ 200 per account.
- ~5–10 messages/s per connection (100k messages: a few hours). 200 connections per workspace, 10 per mailbox. Gmail messages over 24 MB stream in.
- Changes made in Gmail after import (archive, read, delete) are not synced; only new mail is.

## Under the hood (signed-in session only)

`GET /v1/w/:ws/mail/sync` (list, with progress), `POST /v1/w/:ws/mail/sync` (create), `PATCH /v1/w/:ws/mail/sync/:syncId` (pause/resume, password, folders, mapping/start), `DELETE /v1/w/:ws/mail/sync/:syncId` (stop; imported mail stays), `POST /v1/w/:ws/mail/sync/imap/probe` (log in, list folders). Prefer the UI.

## Verify

1. Each connection's phase reaches **Syncing**; no account in **Needs attention** (if so, read the reason: wrong password, delegation missing, user suspended).
2. Open two mailboxes: the oldest and newest threads are there with original dates; Sent shows as the person's messages.
3. After the MX switch, send a test message from an outside address and confirm it arrives in Bundle (not via sync).

## Rollback

- Before MX: **Pause** or **Remove** connections; imported mail stays in Bundle (delete it there if unwanted). Remove the Google delegation entry.
- After MX: restore the saved DNS zone (old MX, SPF, DMARC). Mail resumes at Google once DNS propagates; mail that reached Bundle in between stays in Bundle.
