Photo by Brett Jordan on Unsplash

Migrating your email mailbox to Amazon WorkMail

So, you used to have an email provider for the domain you own, but that’s going away, and you need a new email provider, and you found out that Amazon has WorkMail, and you want to migrate your email addresses over to that. If this describes you, I will tell you how I handled that situation, and hopefully the differences between your experience and mine are minor enough to make this helpful.

What you’ll need:

• Write access to your domain’s DNS records
• An AWS account
• A day or so to devote to the process
• $4 per month per email address

What to do:

1. Login to AWS and load up the AWS WorkMail console:
   https://us-east-1.console.aws.amazon.com/workmail/
2. Organizations > Create organization.
   * Under Organization settings: External Domain, enter your domain name and choose an alias.
   * Create organization.
   This takes a few minutes to complete.
3. Select your new organization > Domains > (your domain name)
   * Click Copy All button.
4. Now load up your DNS records for editing as text (not a UI).
   * Delete any line that has “ MX “ in it. These are your own mail records that directed mail for your domain to your old mailbox.
   * Paste your clipboard contents to the bottom of this file.
   * Save.
5. Wait a while for Amazon to become aware of the DNS change and verify the domain. This usually takes several minutes, maybe a few hours, technically it can take up to 48 hours but likely won’t need that long. The page from step 3 above will tell you when your domain is verified.
6. In AWS WorkMail select your new organization > Users > Create user.
   * Set user name to the part before the @ in your email address.
   * Set display name to the same thing.
   * Under Email setup: email address: type your user name, change the domain to your newly verified domain.
   * Enter the password you already use for this email address at your old mail provider. You could use a new password, but I didn’t see any point, and if you don’t know your old password you won’t be able to migrate its contents.
   * Save.
7. Do this again for every email address on your domain that you want to migrate.
8. Do this again one last time for a new email that doesn’t exist already which is required to migrate the email data over from your old mailbox to the new one:
   * Set user name & display name to “migrator” (or something else if you already have a user named this).
   * Under Email setup: email address: type “migrator” and change the domain to your newly verified domain.
   * Save.
9. In AWS WorkMail Select your new organization > Organization settings.
   * Under Migration, select Edit
   * Turn on “Migration enabled”
   * Set the Migration administrator to the new migrator@(your domain) user.
   * Save.
10. Navigate to https://workmail.audriga.com/#start and fill out the form there. This is a mail migration service offered to AWS WorkMail users for free.
    * Wait for them to email you with permission to use their system.
11. Click the link Audriga sent you. It’s probably this:
    https://app.workmail.audriga.com/mig/?client=workmail
    * Accept the TOS & Privacy Policy.
    * Select your current mail provider. I had to add mine by selecting Add provider or server > enter your provider’s mail server (e.g. mail.example.com).
    * Select the correct AWS WorkMail region for your new provider (mine is us-east-1 as you can see from the WorkMail console URL in step 1).
    * Under Additional information, enter an email address to receive the updates about your migration. This shouldn’t be an email address you’re migrating.
    * Click Proceed.
12. For each user you entered in steps 5 & 6, add them to the Source account (custom) and Destination account (WorkMail (US)) areas here. The user name and password for Source and Destination are the same for each individual email address being migrated.
    * Use the Check buttons to make sure you’ve got the credentials right.
    * Click Confirm after each user added.
    * Click proceed when finished.
13. Confirm the migration and watch your inbox for updates on it. This can take a few hours.
14. When the migration is done, you will have:
    - Updated your domain’s MX records to point to Amazon WorkMail servers.
    - Added your email users to Amazon WorkMail.
    - Migrated all your old mail contents to Amazon WorkMail servers.
    - But your email client is still pointing at your old provider’s mail servers, so the final move is updating that.
15. Open this document: https://docs.aws.amazon.com/workmail/latest/userguide/clients.html
    * Identify which email client you use.
    * Follow the instructions that are specific to your client. You might have thought that email settings wouldn’t be client-specific, but with Amazon WorkMail they actually are, so this really does matter.
    * If the instructions had you add a new account in your mail client, be sure you remove the old account that is still pointing at your old servers.
16. Verify you can send and receive emails with your email client through WorkMail.
    * Compose a new email to your migrated email address from that same migrated email address.
    * Send it.
    * When you receive it, that proves everything’s working.
17. Done. 🎉 Now clean up by turning off migration support in WorkMail. In AWS WorkMail Select your new organization > Organization settings.
    * Under Migration, select Edit
    * Turn off “Migration enabled”
    * Save.
18. Party hard. 💃