An Easy Way to Migrate Emails to the Amazon Workmail

Have you decided to move your resources to AWS? Resources are not only about storage or anything to build your application, right? Something you use to communicate with your customers or business partners is also an important thing. Amazon Workmail is the answer for our email service.

I've created some posts in this series but those are for something built from scratch. Then, I thought what if we want to migrate our emails from the current hosting provider to AWS? So in this section, I'll show you the easy way that AWS already provided at no cost. Actually, there are two migration specialists we can use but here I choose one of them which doesn't require us to install anything. It's web-based so we can easily access it anywhere. We will use audriga.

Before we migrate, we need to do a few things "carefully" because the state of our domain or the email itself is in use. So, these are the steps I created to do before we migrate all emails.

1. Announce your migration schedule a few days before you do that to all email users and tell them the next steps they should take after the migration process has been done, such as changing the default password, etc.

2. Start to create the Amazon Workmail resources, consisting of an organization, some users along with the emails as the target and an administrator (I'll tell you what it's used for later).

3. I suggest you do the migration at a time when the users are not actively using their emails like at midnight for example as we usually do for maintenance.

4. Set the required DNS records provided by AWS except the MX record. But if there is no more email transaction at that time, you can go ahead with all records.

5. Start migrating the emails.

Since I don't have email hosted somewhere, I'll do two types of migration. First is manual migration from Outlook to Workmail. Then, the second one is batch migration between two Workmail organizations (here we will also see how to migrate either from or to Workmail).

Now we are ready to go!

Create The Amazon Workmail Resources

In this step, we just need to create an organization along with registering the external domain. Here I use the domain dhona.xyz.

$ aws workmail create-organization --alias dhona --domains DomainName=dhona.xyz --region us-east-1

Note*: it's not mandatory to use an external domain since AWS gives us a domain alias for each organization subdomain.awsapps.com.

Set The Required DNS Records

Please set the DNS records generated by Workmail and make sure all are verified.

$ aws workmail get-mail-domain --domain-name dhona.xyz --organization-id m-44968df215c443dea726cd731821614a --region us-east-1
DkimVerificationStatus: PENDING
IsDefault: false
IsTestDomain: false
OwnershipVerificationStatus: PENDING
Records:
(the record will be shown here)

Once we set the DNS properly, it should be successfully verified.

Start The Migration Process

1. Manual Migration

This method we can use to migrate a single email or only for a few users (small quantities). So in the beginning, we will create one email user as the target of Outlook's email.

$ aws workmail create-user --organization-id m-44968df215c443dea726cd731821614a --name dhonaxyz --display-name "Nurul Ramadhona" --password $password --region us-east-1
$ aws workmail register-to-work-mail --organization-id m-44968df215c443dea726cd731821614a --entity-id bdb219b2-c7ed-4c0e-8e04-293b5bd69127 --email dhonaxyz@dhona.xyz --region us-east-1
$ aws workmail describe-user --user-id bdb219b2-c7ed-4c0e-8e04-293b5bd69127 --organization-id m-44968df215c443dea726cd731821614a --region us-east-1
DisplayName: Nurul Ramadhona
Email: dhonaxyz@dhona.xyz
EnabledDate: '2023-03-26T12:52:35.822000+07:00'
Name: dhonaxyz
State: ENABLED
UserId: bdb219b2-c7ed-4c0e-8e04-293b5bd69127
UserRole: USER

As I mentioned above, we will use audriga. Here are the steps on how to use it:

• Open the link => https://app.workmail.audriga.com/?client=workmail

• Select the provider (source and target).

• Enter the email account details (source and target).

Because we migrate in user mode, we should enter the email and password manually. Make sure both passed the validation checks.

• Start the migration (we can leave the screen because we will get an email notification once the migration has been configured, started and completed).

• Check if the emails exist on the target email (the source email currently has two emails, each one email on Inbox and Sent Items).

2. Batch migration

We have successfully migrated a single account. That's good, right? But what if we have a large number of users? Should we migrate all one by one?

Don't worry! We can use a template file (usually in .csv) for uploading the users' details. This is a common thing for managing email services.

Since we will do batch migration. Please create some target users along with the emails on the Workmail. Make sure all users are created and enabled. You can use the following Ansible playbook I created:

- name: workmail-users
  hosts: localhost
  connection: local
  gather_facts: no

  tasks:
    - name: create users
      command: aws workmail create-user --organization-id your-org-id --name "{{ item.username }}" --display-name "{{ item.fullname }}" --password "{{ item.pass }}" --region your-choosen-region
      loop: 
         - { username: "user1", pass: "passwordup2U!", fullname: "User 1"}
         - { username: "user2", pass: "passwordup2U!", fullname: "User 2"}
         - { username: "user3", pass: "passwordup2U!", fullname: "User 3"}
         - { username: "user4", pass: "passwordup2U!", fullname: "User 4"}
         - { username: "user5", pass: "passwordup2U!", fullname: "User 5"}
      tags: [create]

    - name: list users
      shell: "aws workmail list-users --organization-id your-org-id --region your-choosen-region --query 'Users[?Name==`{{ item.username }}`].Id' >> id-list.txt"
      loop: 
         - { username: "user1" }
         - { username: "user2" }
         - { username: "user3" }
         - { username: "user4" }
         - { username: "user5" }
      tags: [list]

    - name: list users id
      shell: 'cat id-list.txt'
      register: list_id
      tags: [list]

    - debug:
        var: list_id.stdout_lines
      tags: [list]

    - name: enable users
      command: aws workmail register-to-work-mail --organization-id your-org-id --entity-id "{{ item.userid }}" --email "{{ item.email }}" --region your-choosen-region
      loop: 
         - { userid: "user1id", email: "user1@your.domain" }
         - { userid: "user2id", email: "user2@your.domain" }
         - { userid: "user3id", email: "user3@your.domain" }
         - { userid: "user4id", email: "user4@your.domain" }
         - { userid: "user5id", email: "user5@your.domain" }
      tags: [enable]

Note*: Please enter the value with your own user's details as well as the number of users. Then, run the 'enable' tag separately as we need the entity-id values after the 'create' and 'list' tags.

Here I create 5 users as example:

We also need to enable migration permission and choose an administrator. By using administrator, we can migrate all emails without providing each user's password. Yes, we only use the credential of the administrator as it has access to all users.

Then, because I migrate between two Workmail organizations. I'll create one more organization as I do for the target organization. I'll migrate from nurul.awsapps.com to dhona.xyz which both are hosted on Workmail. But if you currently have emails hosted somewhere, you don't need to do this.

Now, we are ready to migrate the emails! The steps are similar to the manual migration above, so here I'll mention the difference between them:

• Select the provider (source and target).

Because I'll do migration between two Workmail organizations, I choose the same source and target provider. In case the source (your current email service) is hosted somewhere, please choose to add the missing provider or server and enter the details needed.

• Configure the account by choosing to add multiple accounts, then upload the .csv file. Here's the example:

• Start the migration.

• Check the email.

Here before I did migration, I sent a test email to all source emails. As we can see above there are 5 accounts that have been migrated and each contains 1 email. Then, I'll log in to one of those five users to see if the email exists.

That's it! It's very easy, right? AWS has provide us the easy way and the self-service as well, so we can do it independently anytime we need to migrate to Amazon Workmail.

Alright! Last but not least, don't forget to follow me for more content! Thank you!