Managing Amazon WorkMail (with examples)

Amazon WorkMail is a secure, cloud-based email and messaging service provided by Amazon Web Services. It allows you to manage your organization’s email accounts and provides features such as email, calendar, and contact management. In this article, we will explore eight different use cases for managing Amazon WorkMail using the AWS CLI command aws workmail.

List all WorkMail organizations

To list all WorkMail organizations, you can use the following command:

aws workmail list-organizations

Motivation: This command allows you to retrieve a list of all organizations associated with your Amazon WorkMail account. It provides an overview of your WorkMail setup and can be useful for administrative purposes.

Example Output:

{
    "OrganizationSummaries": [
        {
            "OrganizationId": "12345678-1234-5678-1234-567890abcdef",
            "Alias": "exampleorganization.com",
            "DefaultMailDomain": "exampleorganization.com",
            "DirectoryId": "d-1234567890",
            "State": "ACTIVE"
        }
    ]
}

Explanation of Arguments:

• No arguments required for this command.

The command outputs a JSON object containing detailed information about all WorkMail organizations associated with your AWS account. Each organization is represented by an OrganizationSummary object, which includes attributes such as OrganizationId, Alias, DefaultMailDomain, DirectoryId, and State.

List all users of a specific organization

To list all users of a specific organization, use the following command:

aws workmail list-users --organization-id organization_id

Motivation: This command allows you to retrieve a list of all users within a specific Amazon WorkMail organization. It can be helpful for managing and organizing your users efficiently.

Example Output:

{
    "Users": [
        {
            "Id": "u-1234567890",
            "Email": "johndoe@exampleorganization.com",
            "Name": "John Doe",
            "DisplayName": "John Doe",
            "State": "ENABLED",
            "UserRole": "USER",
            "EnabledDate": "2022-01-01T00:00:00Z"
        }
    ]
}

Explanation of Arguments:

• --organization-id (required): The identifier of the organization for which you want to list the users. You can find the organization ID using the list-organizations command.

The command outputs a JSON object containing detailed information about all users within the specified organization. Each user is represented by a User object, which includes attributes such as Id, Email, Name, DisplayName, State, UserRole, and EnabledDate.

Create a WorkMail user in a specific organization

To create a WorkMail user in a specific organization, use the following command:

aws workmail create-user --name username --display-name name --password password --organization-id organization_id

Motivation: This command allows you to create a new user account within a specific Amazon WorkMail organization. It is essential for onboarding new employees and granting them access to WorkMail features.

Example Output:

{
    "UserId": "u-1234567890"
}

Explanation of Arguments:

• --name (required): The username for the new user.
• --display-name (required): The display name for the new user.
• --password (required): The password for the new user.
• --organization-id (required): The identifier of the organization in which to create the user.

The command creates a new WorkMail user within the specified organization and outputs the UserId for the newly created user.

Register and enable a group/user to WorkMail

To register and enable a group or user to WorkMail, use the following command:

aws workmail register-to-work-mail --entity-id entity_id --email email --organization-id organization_id

Motivation: This command allows you to register and enable an existing group or user from a different directory service (such as Microsoft Active Directory) to Amazon WorkMail. It facilitates migration and integration with existing user/group accounts.

Example Output:

{
    "EntityId": "g-1234567890"
}

Explanation of Arguments:

• --entity-id (required): The identifier of the group or user from the external directory service.
• --email (required): The email address associated with the group or user.
• --organization-id (required): The identifier of the WorkMail organization to which the group or user should be registered and enabled.

The command registers and enables the specified group or user to WorkMail within the specified organization and outputs the EntityId for the registered entity.

Create a WorkMail group in a specific organization

To create a WorkMail group in a specific organization, use the following command:

aws workmail create-group --name group_name --organization-id organization_id

Motivation: This command allows you to create a new group within a specific Amazon WorkMail organization. Groups can be used for distribution lists, shared mailboxes, and collaborative purposes.

Example Output:

{
    "GroupId": "g-1234567890"
}

Explanation of Arguments:

• --name (required): The name for the new group.
• --organization-id (required): The identifier of the organization in which to create the group.

The command creates a new WorkMail group within the specified organization and outputs the GroupId for the newly created group.

Associate a member to a specific group

To associate a member to a specific group, use the following command:

aws workmail associate-member-to-group --group-id group_id --member-id member_id --organization-id organization_id

Motivation: This command allows you to add a member (user or group) to an existing WorkMail group within a specific organization. It helps manage group memberships and access permissions effectively.

Example Output:

{
    "GroupId": "g-1234567890",
    "MemberId": "u-0987654321"
}

Explanation of Arguments:

• --group-id (required): The identifier of the group to which the member should be associated.
• --member-id (required): The identifier of the member (user or group) to associate.
• --organization-id (required): The identifier of the organization in which the group and member exist.

The command associates the specified member to the specified group within the specified organization and outputs the GroupId and MemberId for reference.

Deregister and disable a user/group from WorkMail

To deregister and disable a user or group from WorkMail, use the following command:

aws workmail deregister-from-work-mail --entity-id entity_id --organization-id organization_id

Motivation: This command allows you to remove a user or group from Amazon WorkMail and disable their access to the service. It is useful for offboarding employees, removing outdated accounts, or terminating access to specific groups.

Example Output: No output is returned for this command.

Explanation of Arguments:

• --entity-id (required): The identifier of the user or group to deregister and disable.
• --organization-id (required): The identifier of the organization from which to deregister and disable the user/group.

The command deregisters and disables the specified user or group from WorkMail within the specified organization.

Delete a user from an organization

To delete a user from an organization, use the following command:

aws workmail delete-user --user-id user_id --organization-id organization_id

Motivation: This command allows you to permanently delete a user from Amazon WorkMail. It is useful for removing user accounts that are no longer needed or for cleanup purposes.

Example Output: No output is returned for this command.

Explanation of Arguments:

• --user-id (required): The identifier of the user to delete.
• --organization-id (required): The identifier of the organization from which to delete the user.

The command deletes the specified user from the organization, and no output is returned upon successful deletion.

Conclusion

In this article, we explored eight different use cases for managing Amazon WorkMail using the aws workmail CLI command. We covered commands for listing organizations, users, creating users and groups, associating members, registering entities, deregistering entities, and deleting users. These examples demonstrate the versatility and power of managing Amazon WorkMail from the command line, enabling efficient administration and control of your organization’s email accounts and communication resources.