Amazon WorkMail examples using Amazon CLI - Amazon Command Line Interface
Actions
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Amazon WorkMail examples using Amazon CLI

The following code examples show you how to perform actions and implement common scenarios by using the Amazon Command Line Interface with Amazon WorkMail.

Actions are code excerpts from larger programs and must be run in context. While actions show you how to call individual service functions, you can see actions in context in their related scenarios and cross-service examples.

Scenarios are code examples that show you how to accomplish a specific task by calling multiple functions within the same service.

Each example includes a link to GitHub, where you can find instructions on how to set up and run the code in context.

Topics

Actions

The following code example shows how to use associate-delegate-to-resource.

Amazon CLI

To add a delegate to a resource

The following associate-delegate-to-resource command adds a delegate to a resource.

aws workmail associate-delegate-to-resource \
    --organization-id m-d281d0a2fd824be5b6cd3d3ce909fd27 \
    --resource-id r-68bf2d3b1c0244aab7264c24b9217443 \
    --entity-id S-1-1-11-1111111111-2222222222-3333333333-3333

This command produces no output.

The following code example shows how to use associate-member-to-group.

Amazon CLI

To add a member to a group

The following associate-member-to-group command adds the specified member to a group.

aws workmail associate-member-to-group \
    --organization-id m-d281d0a2fd824be5b6cd3d3ce909fd27 \
    --group-id S-1-1-11-1122222222-2222233333-3333334444-4444 \
    --member-id S-1-1-11-1111111111-2222222222-3333333333-3333

This command produces no output.

The following code example shows how to use create-alias.

Amazon CLI

To create an alias

The following create-alias command creates an alias for the specified entity (user or group).

aws workmail create-alias \
    --organization-id m-d281d0a2fd824be5b6cd3d3ce909fd27 \
    --entity-id S-1-1-11-1122222222-2222233333-3333334444-4444 \
    --alias exampleAlias@site.awsapps.com

This command produces no output.

  • For API details, see CreateAlias in Amazon CLI Command Reference.

The following code example shows how to use create-group.

Amazon CLI

To create a new group

The following create-group command creates a new group for the specified organization.

aws workmail create-group \
    --organization-id m-d281d0a2fd824be5b6cd3d3ce909fd27 \
    --name exampleGroup1

Output:

{
    "GroupId": "S-1-1-11-1122222222-2222233333-3333334444-4444"
}

  • For API details, see CreateGroup in Amazon CLI Command Reference.

The following code example shows how to use create-resource.

Amazon CLI

To create a new resource

The following create-resource command creates a new resource (meeting room) for the specified organization.

aws workmail create-resource \
    --organization-id m-d281d0a2fd824be5b6cd3d3ce909fd27 \
    --name exampleRoom1 \
    --type ROOM

Output:

{
    "ResourceId": "r-7afe0efbade843a58cdc10251fce992c"
}

  • For API details, see CreateResource in Amazon CLI Command Reference.

The following code example shows how to use create-user.

Amazon CLI

To create a new user

The following create-user command creates a new user.

aws workmail create-user \
    --organization-id m-d281d0a2fd824be5b6cd3d3ce909fd27 \
    --name exampleName \
    --display-name exampleDisplayName \
    --password examplePa$$w0rd

Output:

{
    "UserId": "S-1-1-11-1111111111-2222222222-3333333333-3333"
}

  • For API details, see CreateUser in Amazon CLI Command Reference.

The following code example shows how to use delete-access-control-rule.

Amazon CLI

To delete an access control rule

The following delete-access-control-rule example deletes the specified access control rule from the specified Amazon WorkMail organization.

aws workmail delete-access-control-rule \
    --organization-id m-n1pq2345678r901st2u3vx45x6789yza \
    --name "myRule"

This command produces no output.

For more information, see Working with Access Control Rules in the Amazon WorkMail Administrator Guide.

The following code example shows how to use delete-alias.

Amazon CLI

To delete an alias

The following delete-alias command deletes the alias for the specified entity (user or group).

aws workmail delete-alias \
    --organization-id m-d281d0a2fd824be5b6cd3d3ce909fd27 \
    --entity-id S-1-1-11-1122222222-2222233333-3333334444-4444 \
    --alias exampleAlias@site.awsapps.com

This command produces no output.

  • For API details, see DeleteAlias in Amazon CLI Command Reference.

The following code example shows how to use delete-group.

Amazon CLI

To delete an existing group

The following delete-group command deletes an existing group from Amazon WorkMail.

aws workmail delete-group \
    --organization-id m-d281d0a2fd824be5b6cd3d3ce909fd27 \
    --group-id S-1-1-11-1122222222-2222233333-3333334444-4444

This command produces no output.

  • For API details, see DeleteGroup in Amazon CLI Command Reference.

The following code example shows how to use delete-mailbox-permissions.

Amazon CLI

To delete mailbox permissions

The following delete-mailbox-permissions command deletes mailbox permissions that were previously granted to a user or group. The entity represents the user that owns the mailbox, and the grantee represents the user or group for whom to delete permissions.

aws workmail delete-mailbox-permissions \
    --organization-id m-d281d0a2fd824be5b6cd3d3ce909fd27 \
    --entity-id S-1-1-11-1122222222-2222233333-3333334444-4444 \
    --grantee-id S-1-1-11-1111111111-2222222222-3333333333-3333

This command produces no output.

The following code example shows how to use delete-resource.

Amazon CLI

To delete an existing resource

The following delete-resource command deletes an existing resource from Amazon WorkMail.

aws workmail delete-resource \
    --organization-id m-d281d0a2fd824be5b6cd3d3ce909fd27 \
    --resource-id r-7afe0efbade843a58cdc10251fce992c

This command produces no output.

  • For API details, see DeleteResource in Amazon CLI Command Reference.

The following code example shows how to use delete-user.

Amazon CLI

To delete a user

The following delete-user command deletes the specified user from Amazon WorkMail and all subsequent systems.

aws workmail delete-user \
    --organization-id m-d281d0a2fd824be5b6cd3d3ce909fd27 \
    --user-id S-1-1-11-1111111111-2222222222-3333333333-3333

This command produces no output.

  • For API details, see DeleteUser in Amazon CLI Command Reference.

The following code example shows how to use deregister-from-work-mail.

Amazon CLI

To disable an existing entity

The following deregister-from-work-mail command disables an existing entity (user, group, or resource) from using Amazon WorkMail.

aws workmail deregister-from-work-mail \
    --organization-id m-d281d0a2fd824be5b6cd3d3ce909fd27 \
    --entity-id S-1-1-11-1111111111-2222222222-3333333333-3333

This command produces no output.

The following code example shows how to use describe-group.

Amazon CLI

To retrieve information for a group

The following describe-group command retrieves information about the specified group.

aws workmail describe-group \
    --organization-id m-d281d0a2fd824be5b6cd3d3ce909fd27 \
    --group-id S-1-1-11-1122222222-2222233333-3333334444-4444

Output:

{
    "GroupId": "S-1-1-11-1122222222-2222233333-3333334444-4444",
    "Name": "exampleGroup1",
    "State": "ENABLED"
}

  • For API details, see DescribeGroup in Amazon CLI Command Reference.

The following code example shows how to use describe-organization.

Amazon CLI

To retrieve information for an organization

The following describe-organization command retrieves information for the specified Amazon WorkMail organization.

aws workmail describe-organization \
    --organization-id m-d281d0a2fd824be5b6cd3d3ce909fd27

Output:

{
    "OrganizationId": "m-d281d0a2fd824be5b6cd3d3ce909fd27",
    "Alias": "alias",
    "State": "Active",
    "DirectoryId": "d-926726012c",
    "DirectoryType": "VpcDirectory",
    "DefaultMailDomain": "site.awsapps.com",
    "CompletedDate": 1522693605.468,
    "ARN": "arn:aws:workmail:us-west-2:111122223333:organization/m-n1pq2345678r901st2u3vx45x6789yza"
}

For more information, see Working with Organizations in the Amazon WorkMail Administrator Guide.

The following code example shows how to use describe-resource.

Amazon CLI

To retrieve information for a resource

The following describe-resource command retrieves information about the specified resource.

aws workmail describe-resource \
    --organization-id m-d281d0a2fd824be5b6cd3d3ce909fd27 \
    --resource-id r-7afe0efbade843a58cdc10251fce992c

Output:

{
    "ResourceId": "r-7afe0efbade843a58cdc10251fce992c",
    "Name": "exampleRoom1",
    "Type": "ROOM",
    "BookingOptions": {
        "AutoAcceptRequests": true,
        "AutoDeclineRecurringRequests": false,
        "AutoDeclineConflictingRequests": true
    },
    "State": "ENABLED"
}

The following code example shows how to use describe-user.

Amazon CLI

To retrieve user information

The following describe-user command retrieves information about the specified user.

aws workmail describe-user \
    --organization-id m-d281d0a2fd824be5b6cd3d3ce909fd27 \
    --user-id S-1-1-11-1111111111-2222222222-3333333333-3333

Output:

{
    "UserId": "S-1-1-11-1111111111-2222222222-3333333333-3333",
    "Name": "exampleUser1",
    "Email": "exampleUser1@site.awsapps.com",
    "DisplayName": "",
    "State": "ENABLED",
    "UserRole": "USER",
    "EnabledDate": 1532459261.827
}

  • For API details, see DescribeUser in Amazon CLI Command Reference.

The following code example shows how to use disassociate-delegate-from-resource.

Amazon CLI

To remove a member from a resource

The following disassociate-delegate-from-resource command removes the specified member from a resource.

ws workmail disassociate-delegate-from-resource \
    --organization-id m-d281d0a2fd824be5b6cd3d3ce909fd27 \
    --resource-id r-68bf2d3b1c0244aab7264c24b9217443 \
    --entity-id S-1-1-11-1111111111-2222222222-3333333333-3333

This command produces no output.

The following code example shows how to use disassociate-member-from-group.

Amazon CLI

To remove a member from a group

The following disassociate-member-from-group command removes the specified member from a group.

aws workmail disassociate-member-from-group \
    --organization-id m-d281d0a2fd824be5b6cd3d3ce909fd27 \
    --group-id S-1-1-11-1122222222-2222233333-3333334444-4444 \
    --member-id S-1-1-11-1111111111-2222222222-3333333333-3333

This command produces no output.

The following code example shows how to use get-access-control-effect.

Amazon CLI

To get the effect of access control rules

The following get-access-control-effect example retrieves the effect of the specified Amazon WorkMail organization's access control rules for the specified IP address, access protocol action, and user ID.

aws workmail get-access-control-effect \
    --organization-id m-n1pq2345678r901st2u3vx45x6789yza \
    --ip-address "192.0.2.0" \
    --action "WindowsOutlook" \
    --user-id "S-1-1-11-1111111111-2222222222-3333333333-3333"

Output:

{
    "Effect": "DENY",
    "MatchedRules": [
        "myRule"
    ]
}

For more information, see Working with Access Control Rules in the Amazon WorkMail Administrator Guide.

The following code example shows how to use get-mailbox-details.

Amazon CLI

To get a user's mailbox details

The following get-mailbox-details command retrieves details about the specified user's mailbox.

aws workmail get-mailbox-details \
    --organization-id m-n1pq2345678r901st2u3vx45x6789yza \
    --user-id S-1-1-11-1111111111-2222222222-3333333333-3333

Output:

{
    "MailboxQuota": 51200,
    "MailboxSize": 0.03890800476074219
}

For more information, see Managing User Accounts in the Amazon WorkMail Administrator Guide.

The following code example shows how to use list-access-control-rules.

Amazon CLI

To list access control rules

The following list-access-control-rules example lists the access control rules for the specified Amazon WorkMail organization.

aws workmail list-access-control-rules \
    --organization-id m-n1pq2345678r901st2u3vx45x6789yza

Output:

{
    "Rules": [
        {
            "Name": "default",
            "Effect": "ALLOW",
            "Description": "Default WorkMail Rule",
            "DateCreated": 0.0,
            "DateModified": 0.0
        },
        {
            "Name": "myRule",
            "Effect": "DENY",
            "Description": "my rule",
            "UserIds": [
            "S-1-1-11-1111111111-2222222222-3333333333-3333"
            ],
            "DateCreated": 1581635628.0,
            "DateModified": 1581635628.0
        }
    ]
}

For more information, see Working with Access Control Rules in the Amazon WorkMail Administrator Guide.

The following code example shows how to use list-aliases.

Amazon CLI

To list aliases for a member

The following list-aliases command lists aliases for the specified member (user or group).

aws workmail list-aliases \
    --organization-id m-d281d0a2fd824be5b6cd3d3ce909fd27 \
    --entity-id S-1-1-11-1111111111-2222222222-3333333333-3333

Output:

{
    "Aliases": [
        "exampleAlias@site.awsapps.com",
        "exampleAlias1@site.awsapps.com"
    ]
}

  • For API details, see ListAliases in Amazon CLI Command Reference.

The following code example shows how to use list-group-members.

Amazon CLI

To list group members

The following list-group-members command lists the members of the specified group.

aws workmail list-group-members \
    --organization-id m-d281d0a2fd824be5b6cd3d3ce909fd27 \
    --group-id S-1-1-11-1122222222-2222233333-3333334444-4444

Output:

{
    "Members": [
        {
            "Id": "S-1-1-11-1111111111-2222222222-3333333333-3333",
            "Name": "exampleUser1",
            "Type": "USER",
            "State": "ENABLED",
            "EnabledDate": 1532459261.827
        }
    ]
}

The following code example shows how to use list-groups.

Amazon CLI

To retrieve a list of groups

The following list-groups command retrieves summaries of the groups in the specified organization.

aws workmail list-groups \
    --organization-id m-d281d0a2fd824be5b6cd3d3ce909fd27

Output:

{
    "Groups": [
        {
            "Id": "S-1-1-11-1122222222-2222233333-3333334444-4444",
            "Name": "exampleGroup1",
            "State": "DISABLED"
        },
        {
            "Id": "S-4-4-44-1122222222-2222233333-3333334444-4444",
            "Name": "exampleGroup2",
            "State": "ENABLED"
        }
    ]
}

  • For API details, see ListGroups in Amazon CLI Command Reference.

The following code example shows how to use list-mailbox-permissions.

Amazon CLI

To retrieve mailbox permissions

The following list-mailbox-permissions command retrieves the mailbox permissions associated with the specified entity's mailbox.

aws workmail list-mailbox-permissions \
    --organization-id m-d281d0a2fd824be5b6cd3d3ce909fd27 \
    --entity-id S-1-1-11-1111111111-2222222222-3333333333-3333

Output:

{
    "Permissions": [
        {
            "GranteeId": "S-1-1-11-1122222222-2222233333-3333334444-4444",
            "GranteeType": "USER",
            "PermissionValues": [
                "FULL_ACCESS"
            ]
        }
    ]
}

The following code example shows how to use list-organizations.

Amazon CLI

To retrieve a list of organizations

The following list-organizations command retrieves summaries of non-deleted organizations.

aws workmail list-organizations

Output:

{
    "OrganizationSummaries": [
        {
            "OrganizationId": "m-d281d0a2fd824be5b6cd3d3ce909fd27",
            "Alias": "exampleAlias",
            "State": "Active"
        }
    ]
}

The following code example shows how to use list-resource-delegates.

Amazon CLI

To list the delegates for a resource

The following list-resource-delegates command retrieves the delegates associated with the specified resource.

aws workmail list-resource-delegates \
    --organization-id m-d281d0a2fd824be5b6cd3d3ce909fd27 \
    --resource-id r-68bf2d3b1c0244aab7264c24b9217443

Output:

{
    "Delegates": [
        {
            "Id": "S-1-1-11-1111111111-2222222222-3333333333-3333",
            "Type": "USER"
        }
    ]
}

The following code example shows how to use list-resources.

Amazon CLI

To retrieve a list of resources

The following list-resources command retrieves summaries of the resources for the specified organization.

aws workmail list-resources \
    --organization-id m-d281d0a2fd824be5b6cd3d3ce909fd27

Output:

{
    "Resources": [
        {
            "Id": "r-7afe0efbade843a58cdc10251fce992c",
            "Name": "exampleRoom1",
            "Type": "ROOM",
            "State": "ENABLED"
        }
    ]
}

  • For API details, see ListResources in Amazon CLI Command Reference.

The following code example shows how to use list-tags-for-resource.

Amazon CLI

To list the tags for a resource

The following list-tags-for-resource example lists the tags for the specified Amazon WorkMail organization.

aws workmail list-tags-for-resource \
    --resource-arn arn:aws:workmail:us-west-2:111122223333:organization/m-n1pq2345678r901st2u3vx45x6789yza

Output:

{
    "Tags": [
        {
            "Key": "priority",
            "Value": "1"
        }
    ]
}

For more information, see Tagging an Organization in the Amazon WorkMail Administrator Guide.

The following code example shows how to use list-users.

Amazon CLI

To retrieve a list of users

The following list-users command retrieves summaries of the users in the specified organization.

aws workmail list-users \
    --organization-id m-d281d0a2fd824be5b6cd3d3ce909fd27

Output:

{
    "Users": [
        {
            "Id": "S-1-1-11-1111111111-2222222222-3333333333-3333",
            "Email": "exampleUser1@site.awsapps.com",
            "Name": "exampleUser1",
            "State": "ENABLED",
            "UserRole": "USER",
            "EnabledDate": 1532459261.827
        },
        {
            "Id": "S-1-1-11-1122222222-2222233333-3333334444-4444",
            "Name": "exampleGuestUser",
            "State": "DISABLED",
            "UserRole": "SYSTEM_USER"
        }
    ]
}

  • For API details, see ListUsers in Amazon CLI Command Reference.

The following code example shows how to use put-access-control-rule.

Amazon CLI

To put a new access control rule

The following put-access-control-rule example denies the specified user access to the specified Amazon WorkMail organization.

aws workmail put-access-control-rule \
    --name "myRule" \
    --effect "DENY" \
    --description "my rule" \
    --user-ids "S-1-1-11-1111111111-2222222222-3333333333-3333" \
    --organization-id m-n1pq2345678r901st2u3vx45x6789yza

This command produces no output.

For more information, see Working with Access Control Rules in the Amazon WorkMail Administrator Guide.

The following code example shows how to use put-mailbox-permissions.

Amazon CLI

To set mailbox permissions

The following put-mailbox-permissions command sets full access permissions for the specified grantee (user or group). The entity represents the owner of the mailbox.

aws workmail put-mailbox-permissions \
    --organization-id m-d281d0a2fd824be5b6cd3d3ce909fd27 \
    --entity-id S-1-1-11-1111111111-2222222222-3333333333-3333 \
    --grantee-id S-1-1-11-1122222222-2222233333-3333334444-4444 \
    --permission-values FULL_ACCESS

This command produces no output.

The following code example shows how to use register-to-work-mail.

Amazon CLI

To register an existing or disabled entity

The following register-to-work-mail command enables the specified existing entity (user, group, or resource) to use Amazon WorkMail.

aws workmail register-to-work-mail \
    --organization-id m-d281d0a2fd824be5b6cd3d3ce909fd27 \
    --entity-id S-1-1-11-1122222222-2222233333-3333334444-4444 \
    --email exampleGroup1@site.awsapps.com

This command produces no output.

The following code example shows how to use reset-password.

Amazon CLI

To reset a user's password

The following reset-password command resets the password for the specified user.

aws workmail reset-password \
    --organization-id m-d281d0a2fd824be5b6cd3d3ce909fd27 \
    --user-id S-1-1-11-1111111111-2222222222-3333333333-3333 \
    --password examplePa$$w0rd

This command produces no output.

  • For API details, see ResetPassword in Amazon CLI Command Reference.

The following code example shows how to use tag-resource.

Amazon CLI

To apply a tag to a resource

The following tag-resource example applies a tag with key "priority" and value "1" to the specified Amazon WorkMail organization.

aws workmail tag-resource \
    --resource-arn arn:aws:workmail:us-west-2:111122223333:organization/m-n1pq2345678r901st2u3vx45x6789yza \
    --tags "Key=priority,Value=1"

This command produces no output.

For more information, see Tagging an Organization in the Amazon WorkMail Administrator Guide.

  • For API details, see TagResource in Amazon CLI Command Reference.

The following code example shows how to use untag-resource.

Amazon CLI

To untag a resource

The following untag-resource example removes the specified tag from the specified Amazon WorkMail organization.

aws workmail untag-resource \
    --resource-arn arn:aws:workmail:us-west-2:111122223333:organization/m-n1pq2345678r901st2u3vx45x6789yza \
    --tag-keys "priority"

This command produces no output.

For more information, see Tagging an Organization in the Amazon WorkMail Administrator Guide.

  • For API details, see UntagResource in Amazon CLI Command Reference.

The following code example shows how to use update-mailbox-quota.

Amazon CLI

To update a user's mailbox quota

The following update-mailbox-quota command changes the specified user's mailbox quota.

aws workmail update-mailbox-quota \
    --organization-id m-n1pq2345678r901st2u3vx45x6789yza \
    --user-id S-1-1-11-1111111111-2222222222-3333333333-3333 \
    --mailbox-quota 40000

This command produces no output.

For more information, see Managing User Accounts in the Amazon WorkMail Administrator Guide.

The following code example shows how to use update-primary-email-address.

Amazon CLI

To update a primary email address

The following update-primary-email-address command updates the primary email address of the specified entity (user, group, or resource).

aws workmail update-primary-email-address \
    --organization-id m-d281d0a2fd824be5b6cd3d3ce909fd27 \
    --entity-id S-1-1-11-1111111111-2222222222-3333333333-3333 \
    --email exampleUser2@site.awsapps.com

This command produces no output.

The following code example shows how to use update-resource.

Amazon CLI

To update a resource

The following update-resource command updates the name of the specified resource.

aws workmail update-resource \
    --organization-id m-d281d0a2fd824be5b6cd3d3ce909fd27 \
    --resource-id r-7afe0efbade843a58cdc10251fce992c \
    --name exampleRoom2

This command produces no output.

  • For API details, see UpdateResource in Amazon CLI Command Reference.