How to Manage Amazon WorkMail Using AWS CLI (with examples)

Amazon WorkMail is a secure, managed business email and calendar service with support for existing desktop and mobile email clients. The AWS Command Line Interface (CLI) provides a powerful platform to interact with AWS services directly from a command-line shell. In this article, we explore various use cases for the AWS CLI command aws workmail, which allows us to manage Amazon WorkMail entities such as organizations, users, and groups.

Use Case 1: List All WorkMail Organizations

Code:

aws workmail list-organizations

Motivation:

Listing all WorkMail organizations is fundamental in managing, monitoring, and troubleshooting operations. It allows administrators to have a complete overview of existing WorkMail setups in their AWS environment, ensuring that everything is running smoothly and no organizations are missing or misconfigured.

Explanation:

• aws workmail list-organizations: This command calls the list-organizations method from the WorkMail API, which returns a list of all WorkMail organizations under the user’s AWS account.

Example Output:

{
  "OrganizationSummaries": [
    {
      "OrganizationId": "m-1234567890",
      "Alias": "example1",
      "ErrorMessage": null,
      "State": "ACTIVE"
    },
    {
      "OrganizationId": "m-0987654321",
      "Alias": "example2",
      "ErrorMessage": null,
      "State": "ACTIVE"
    }
  ]
}

Use Case 2: List All Users of a Specific Organization

Code:

aws workmail list-users --organization-id organization_id

Motivation:

Listing users in a specific WorkMail organization is essential for managing user accounts, auditing user activity, and verifying user access. This functionality helps administrators maintain an up-to-date user directory, facilitating efficient management and issue resolution.

Explanation:

• aws workmail list-users: This portion of the command invokes the list-users action.
• --organization-id organization_id: This flag specifies the ID of the WorkMail organization whose users you want to list. The organization ID is a unique identifier allowing the command to target a specific organization.

Example Output:

{
  "Users": [
    {
      "Id": "user-1",
      "Email": "user1@example.com",
      "Name": "User One",
      "State": "ENABLED",
      "MailboxPermissionList": []
    },
    {
      "Id": "user-2",
      "Email": "user2@example.com",
      "Name": "User Two",
      "State": "ENABLED",
      "MailboxPermissionList": []
    }
  ]
}

Use Case 3: Create a WorkMail User in a Specific Organization

Code:

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

Motivation:

Creating new users in a WorkMail organization is a routine task performed during onboarding or organizational restructuring. This operation is crucial for expanding teams and ensuring that all team members have access to necessary communications tools.

Explanation:

• aws workmail create-user: This invokes the creation of a new WorkMail user.
• --name username: The username for the new WorkMail account. It is used as part of their email address.
• --display-name name: The full name that will be displayed in address books and email listings.
• --password password: A password for the new user’s email account. It should adhere to your organization’s security policies.
• --organization-id organization_id: This uniquely identifies the WorkMail organization where the user will be added.

Example Output:

{
  "UserId": "user-1234567890"
}

Use Case 4: Register and Enable a Group/User to WorkMail

Code:

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

Motivation:

Registering and enabling an entity—be it a user or group—to WorkMail is key for maintaining active email entities. This step is often required after creating a user or group to allow them to start receiving and sending emails in WorkMail.

Explanation:

• aws workmail register-to-work-mail: This action registers the specified entity with WorkMail.
• --entity-id entity_id: This represents the unique identifier of the entity (user or group) to register.
• --email email: The email address to assign to this entity, enabling them to receive and send emails.
• --organization-id organization_id: Identifies the organization within WorkMail where the entity will be registered.

Example Output:

{}

Use Case 5: Create a WorkMail Group in a Specific Organization

Code:

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

Motivation:

Creating groups in WorkMail simplifies the process of sending emails to multiple users by using a single email address. This is particularly useful for teams and departments to enhance collaboration and communication efficiency.

Explanation:

• aws workmail create-group: This command triggers the creation of a new WorkMail group.
• --name group_name: Specifies the name of the group, which serves as part of the group’s email address.
• --organization-id organization_id: This identifies the specific WorkMail organization where the group will be created.

Example Output:

{
  "GroupId": "group-1234567890"
}

Use Case 6: Associate a Member to a Specific Group

Code:

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

Motivation:

Associating a member to a group is critical for facilitating group communications and ensuring that individuals in a team or department can collaborate through group emails. This role is essential to keep teams organized and efficient.

Explanation:

• aws workmail associate-member-to-group: This command associates a user or member with a specified group.
• --group-id group_id: The unique identifier for the group where the member will be added.
• --member-id member_id: Represents the user or member’s unique identifier within WorkMail.
• --organization-id organization_id: The organization ID ensures the command affects the correct WorkMail organization.

Example Output:

{}

Use Case 7: Deregister and Disable a User/Group from WorkMail

Code:

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

Motivation:

Deregistering and disabling a user or group is an essential operation for retiring accounts, managing cost, and securing organizational data. This function is often utilized during offboarding efforts and when organizational structures change.

Explanation:

• aws workmail deregister-from-work-mail: This action removes the specified entity from being managed by WorkMail.
• --entity-id entity_id: Identifies which user or group’s registration is to be withdrawn.
• --organization-id organization_id: Ensures the command is executed in the correct WorkMail organization.

Example Output:

{}

Use Case 8: Delete a User from an Organization

Code:

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

Motivation:

Deleting a user is a critical step in removing inactive or former employees from the organization’s contact list and freeing up resources. This action ensures that outdated or unnecessary accounts are not available in the system, enhancing security and organizational cleanliness.

Explanation:

• aws workmail delete-user: This command calls for the removal of a specified user from WorkMail.
• --user-id user_id: The unique identifier for the user you wish to delete.
• --organization-id organization_id: This specifies the WorkMail organization from which the user will be removed.

Example Output:

{}

Conclusion:

Managing Amazon WorkMail using the AWS CLI offers significant flexibility and power, enabling you to automate and streamline the management of your email services. Whether you need to list, create, or delete users and groups, these command-line tools provide robust solutions that are scalable and customizable to your organization’s specific needs. By understanding these use cases, administrators can ensure effective management of their Amazon WorkMail resources.