Amazon WorkMail

2024/10/30 - Amazon WorkMail - 8 new 5 updated api methods

Changes  This release adds support for Multi-Factor Authentication (MFA) and Personal Access Tokens through integration with AWS IAM Identity Center.

DeleteIdentityProviderConfiguration (new) Link ¶

Disables the integration between IdC and WorkMail. Authentication will continue with the directory as it was before the IdC integration. You might have to reset your directory passwords and reconfigure your desktop and mobile email clients.

See also: AWS API Documentation

Request Syntax

client.delete_identity_provider_configuration(
    OrganizationId='string'
)
type OrganizationId

string

param OrganizationId

[REQUIRED]

The Organization ID.

rtype

dict

returns

Response Syntax

{}

Response Structure

  • (dict) --

GetPersonalAccessTokenMetadata (new) Link ¶

Requests details of a specific Personal Access Token within the WorkMail organization.

See also: AWS API Documentation

Request Syntax

client.get_personal_access_token_metadata(
    OrganizationId='string',
    PersonalAccessTokenId='string'
)
type OrganizationId

string

param OrganizationId

[REQUIRED]

The Organization ID.

type PersonalAccessTokenId

string

param PersonalAccessTokenId

[REQUIRED]

The Personal Access Token ID.

rtype

dict

returns

Response Syntax

{
    'PersonalAccessTokenId': 'string',
    'UserId': 'string',
    'Name': 'string',
    'DateCreated': datetime(2015, 1, 1),
    'DateLastUsed': datetime(2015, 1, 1),
    'ExpiresTime': datetime(2015, 1, 1),
    'Scopes': [
        'string',
    ]
}

Response Structure

  • (dict) --

    • PersonalAccessTokenId (string) --

      The Personal Access Token ID.

    • UserId (string) --

      The WorkMail User ID.

    • Name (string) --

      The Personal Access Token name.

    • DateCreated (datetime) --

      The date when the Personal Access Token ID was created.

    • DateLastUsed (datetime) --

      The date when the Personal Access Token ID was last used.

    • ExpiresTime (datetime) --

      The time when the Personal Access Token ID will expire.

    • Scopes (list) --

      Lists all the Personal Access Token permissions for a mailbox.

      • (string) --

PutIdentityProviderConfiguration (new) Link ¶

Enables integration between IAM Identity Center (IdC) and WorkMail to proxy authentication requests for mailbox users. You can connect your IdC directory or your external directory to WorkMail through IdC and manage access to WorkMail mailboxes in a single place. For enhanced protection, you could enable Multifactor Authentication (MFA) and Personal Access Tokens.

See also: AWS API Documentation

Request Syntax

client.put_identity_provider_configuration(
    OrganizationId='string',
    AuthenticationMode='IDENTITY_PROVIDER_ONLY'|'IDENTITY_PROVIDER_AND_DIRECTORY',
    IdentityCenterConfiguration={
        'InstanceArn': 'string',
        'ApplicationArn': 'string'
    },
    PersonalAccessTokenConfiguration={
        'Status': 'ACTIVE'|'INACTIVE',
        'LifetimeInDays': 123
    }
)
type OrganizationId

string

param OrganizationId

[REQUIRED]

The ID of the WorkMail Organization.

type AuthenticationMode

string

param AuthenticationMode

[REQUIRED]

The authentication mode used in WorkMail.

type IdentityCenterConfiguration

dict

param IdentityCenterConfiguration

[REQUIRED]

The details of the IAM Identity Center configuration.

  • InstanceArn (string) -- [REQUIRED]

    The Amazon Resource Name (ARN) of the of IAM Identity Center instance. Must be in the same AWS account and region as WorkMail organization.

  • ApplicationArn (string) -- [REQUIRED]

    The Amazon Resource Name (ARN) of IAMIdentity Center Application for WorkMail. Must be created by the WorkMail API, see CreateIdentityCenterApplication.

type PersonalAccessTokenConfiguration

dict

param PersonalAccessTokenConfiguration

[REQUIRED]

The details of the Personal Access Token configuration.

  • Status (string) -- [REQUIRED]

    The status of the Personal Access Token allowed for the organization.

    • Active - Mailbox users can login to the web application and choose Settings to see the new Personal Access Tokens page to create and delete the Personal Access Tokens. Mailbox users can use the Personal Access Tokens to set up mailbox connection from desktop or mobile email clients.

    • Inactive - Personal Access Tokens are disabled for your organization. Mailbox users can’t create, list, or delete Personal Access Tokens and can’t use them to connect to their mailboxes from desktop or mobile email clients.

  • LifetimeInDays (integer) --

    The validity of the Personal Access Token status in days.

rtype

dict

returns

Response Syntax

{}

Response Structure

  • (dict) --

ListPersonalAccessTokens (new) Link ¶

Returns a summary of your Personal Access Tokens.

See also: AWS API Documentation

Request Syntax

client.list_personal_access_tokens(
    OrganizationId='string',
    UserId='string',
    NextToken='string',
    MaxResults=123
)
type OrganizationId

string

param OrganizationId

[REQUIRED]

The Organization ID.

type UserId

string

param UserId

The WorkMail User ID.

type NextToken

string

param NextToken

The token from the previous response to query the next page.

type MaxResults

integer

param MaxResults

The maximum amount of items that should be returned in a response.

rtype

dict

returns

Response Syntax

{
    'NextToken': 'string',
    'PersonalAccessTokenSummaries': [
        {
            'PersonalAccessTokenId': 'string',
            'UserId': 'string',
            'Name': 'string',
            'DateCreated': datetime(2015, 1, 1),
            'DateLastUsed': datetime(2015, 1, 1),
            'ExpiresTime': datetime(2015, 1, 1),
            'Scopes': [
                'string',
            ]
        },
    ]
}

Response Structure

  • (dict) --

    • NextToken (string) --

      The token from the previous response to query the next page.

    • PersonalAccessTokenSummaries (list) --

      Lists all the personal tokens in an organization or user, if user ID is provided.

      • (dict) --

        The summary of the Personal Access Token.

        • PersonalAccessTokenId (string) --

          The ID of the Personal Access Token.

        • UserId (string) --

          The user ID of the WorkMail user associated with the Personal Access Token.

        • Name (string) --

          The name of the Personal Access Token.

        • DateCreated (datetime) --

          The date when the Personal Access Token was created.

        • DateLastUsed (datetime) --

          The date when the Personal Access Token was last used.

        • ExpiresTime (datetime) --

          The date when the Personal Access Token will expire.

        • Scopes (list) --

          Lists all the Personal Access Token permissions for a mailbox.

          • (string) --

DeletePersonalAccessToken (new) Link ¶

Deletes the Personal Access Token from the provided WorkMail Organization.

See also: AWS API Documentation

Request Syntax

client.delete_personal_access_token(
    OrganizationId='string',
    PersonalAccessTokenId='string'
)
type OrganizationId

string

param OrganizationId

[REQUIRED]

The Organization ID.

type PersonalAccessTokenId

string

param PersonalAccessTokenId

[REQUIRED]

The Personal Access Token ID.

rtype

dict

returns

Response Syntax

{}

Response Structure

  • (dict) --

DeleteIdentityCenterApplication (new) Link ¶

Deletes the IAM Identity Center application from WorkMail. This action does not affect the authentication settings for any WorkMail organizations.

See also: AWS API Documentation

Request Syntax

client.delete_identity_center_application(
    ApplicationArn='string'
)
type ApplicationArn

string

param ApplicationArn

[REQUIRED]

The Amazon Resource Name (ARN) of the application.

rtype

dict

returns

Response Syntax

{}

Response Structure

  • (dict) --

DescribeIdentityProviderConfiguration (new) Link ¶

Returns detailed information on the current IdC setup for the WorkMail organization.

See also: AWS API Documentation

Request Syntax

client.describe_identity_provider_configuration(
    OrganizationId='string'
)
type OrganizationId

string

param OrganizationId

[REQUIRED]

The Organization ID.

rtype

dict

returns

Response Syntax

{
    'AuthenticationMode': 'IDENTITY_PROVIDER_ONLY'|'IDENTITY_PROVIDER_AND_DIRECTORY',
    'IdentityCenterConfiguration': {
        'InstanceArn': 'string',
        'ApplicationArn': 'string'
    },
    'PersonalAccessTokenConfiguration': {
        'Status': 'ACTIVE'|'INACTIVE',
        'LifetimeInDays': 123
    }
}

Response Structure

  • (dict) --

    • AuthenticationMode (string) --

      The authentication mode used in WorkMail.

    • IdentityCenterConfiguration (dict) --

      The details of the IAM Identity Center configuration.

      • InstanceArn (string) --

        The Amazon Resource Name (ARN) of the of IAM Identity Center instance. Must be in the same AWS account and region as WorkMail organization.

      • ApplicationArn (string) --

        The Amazon Resource Name (ARN) of IAMIdentity Center Application for WorkMail. Must be created by the WorkMail API, see CreateIdentityCenterApplication.

    • PersonalAccessTokenConfiguration (dict) --

      The details of the Personal Access Token configuration.

      • Status (string) --

        The status of the Personal Access Token allowed for the organization.

        • Active - Mailbox users can login to the web application and choose Settings to see the new Personal Access Tokens page to create and delete the Personal Access Tokens. Mailbox users can use the Personal Access Tokens to set up mailbox connection from desktop or mobile email clients.

        • Inactive - Personal Access Tokens are disabled for your organization. Mailbox users can’t create, list, or delete Personal Access Tokens and can’t use them to connect to their mailboxes from desktop or mobile email clients.

      • LifetimeInDays (integer) --

        The validity of the Personal Access Token status in days.

CreateIdentityCenterApplication (new) Link ¶

Creates the WorkMail application in IAM Identity Center that can be used later in the WorkMail - IdC integration. For more information, see PutIdentityProviderConfiguration. This action does not affect the authentication settings for any WorkMail organizations.

See also: AWS API Documentation

Request Syntax

client.create_identity_center_application(
    Name='string',
    InstanceArn='string',
    ClientToken='string'
)
type Name

string

param Name

[REQUIRED]

The name of the IAM Identity Center application.

type InstanceArn

string

param InstanceArn

[REQUIRED]

The Amazon Resource Name (ARN) of the instance.

type ClientToken

string

param ClientToken

The idempotency token associated with the request.

This field is autopopulated if not provided.

rtype

dict

returns

Response Syntax

{
    'ApplicationArn': 'string'
}

Response Structure

  • (dict) --

    • ApplicationArn (string) --

      The Amazon Resource Name (ARN) of the application.

CreateUser (updated) Link ¶
Changes (request)
{'IdentityProviderUserId': 'string'}

Creates a user who can be used in WorkMail by calling the RegisterToWorkMail operation.

See also: AWS API Documentation

Request Syntax

client.create_user(
    OrganizationId='string',
    Name='string',
    DisplayName='string',
    Password='string',
    Role='USER'|'RESOURCE'|'SYSTEM_USER'|'REMOTE_USER',
    FirstName='string',
    LastName='string',
    HiddenFromGlobalAddressList=True|False,
    IdentityProviderUserId='string'
)
type OrganizationId

string

param OrganizationId

[REQUIRED]

The identifier of the organization for which the user is created.

type Name

string

param Name

[REQUIRED]

The name for the new user. WorkMail directory user names have a maximum length of 64. All others have a maximum length of 20.

type DisplayName

string

param DisplayName

[REQUIRED]

The display name for the new user.

type Password

string

param Password

The password for the new user.

type Role

string

param Role

The role of the new user.

You cannot pass SYSTEM_USER or RESOURCE role in a single request. When a user role is not selected, the default role of USER is selected.

type FirstName

string

param FirstName

The first name of the new user.

type LastName

string

param LastName

The last name of the new user.

type HiddenFromGlobalAddressList

boolean

param HiddenFromGlobalAddressList

If this parameter is enabled, the user will be hidden from the address book.

type IdentityProviderUserId

string

param IdentityProviderUserId

User ID from the IAM Identity Center. If this parameter is empty it will be updated automatically when the user logs in for the first time to the mailbox associated with WorkMail.

rtype

dict

returns

Response Syntax

{
    'UserId': 'string'
}

Response Structure

  • (dict) --

    • UserId (string) --

      The identifier for the new user.

DeleteOrganization (updated) Link ¶
Changes (request)
{'DeleteIdentityCenterApplication': 'boolean'}

Deletes an WorkMail organization and all underlying AWS resources managed by WorkMail as part of the organization. You can choose whether to delete the associated directory. For more information, see Removing an organization in the WorkMail Administrator Guide .

See also: AWS API Documentation

Request Syntax

client.delete_organization(
    ClientToken='string',
    OrganizationId='string',
    DeleteDirectory=True|False,
    ForceDelete=True|False,
    DeleteIdentityCenterApplication=True|False
)
type ClientToken

string

param ClientToken

The idempotency token associated with the request.

This field is autopopulated if not provided.

type OrganizationId

string

param OrganizationId

[REQUIRED]

The organization ID.

type DeleteDirectory

boolean

param DeleteDirectory

[REQUIRED]

If true, deletes the AWS Directory Service directory associated with the organization.

type ForceDelete

boolean

param ForceDelete

Deletes a WorkMail organization even if the organization has enabled users.

type DeleteIdentityCenterApplication

boolean

param DeleteIdentityCenterApplication

Deletes IAM Identity Center application for WorkMail. This action does not affect authentication settings for any organization.

rtype

dict

returns

Response Syntax

{
    'OrganizationId': 'string',
    'State': 'string'
}

Response Structure

  • (dict) --

    • OrganizationId (string) --

      The organization ID.

    • State (string) --

      The state of the organization.

DescribeUser (updated) Link ¶
Changes (response)
{'IdentityProviderIdentityStoreId': 'string',
 'IdentityProviderUserId': 'string'}

Provides information regarding the user.

See also: AWS API Documentation

Request Syntax

client.describe_user(
    OrganizationId='string',
    UserId='string'
)
type OrganizationId

string

param OrganizationId

[REQUIRED]

The identifier for the organization under which the user exists.

type UserId

string

param UserId

[REQUIRED]

The identifier for the user to be described.

The identifier can be the UserId , Username , or email . The following identity formats are available:

  • User ID: 12345678-1234-1234-1234-123456789012 or S-1-1-12-1234567890-123456789-123456789-1234

  • Email address: user@domain.tld

  • User name: user

rtype

dict

returns

Response Syntax

{
    'UserId': 'string',
    'Name': 'string',
    'Email': 'string',
    'DisplayName': 'string',
    'State': 'ENABLED'|'DISABLED'|'DELETED',
    'UserRole': 'USER'|'RESOURCE'|'SYSTEM_USER'|'REMOTE_USER',
    'EnabledDate': datetime(2015, 1, 1),
    'DisabledDate': datetime(2015, 1, 1),
    'MailboxProvisionedDate': datetime(2015, 1, 1),
    'MailboxDeprovisionedDate': datetime(2015, 1, 1),
    'FirstName': 'string',
    'LastName': 'string',
    'HiddenFromGlobalAddressList': True|False,
    'Initials': 'string',
    'Telephone': 'string',
    'Street': 'string',
    'JobTitle': 'string',
    'City': 'string',
    'Company': 'string',
    'ZipCode': 'string',
    'Department': 'string',
    'Country': 'string',
    'Office': 'string',
    'IdentityProviderUserId': 'string',
    'IdentityProviderIdentityStoreId': 'string'
}

Response Structure

  • (dict) --

    • UserId (string) --

      The identifier for the described user.

    • Name (string) --

      The name for the user.

    • Email (string) --

      The email of the user.

    • DisplayName (string) --

      The display name of the user.

    • State (string) --

      The state of a user: enabled (registered to WorkMail) or disabled (deregistered or never registered to WorkMail).

    • UserRole (string) --

      In certain cases, other entities are modeled as users. If interoperability is enabled, resources are imported into WorkMail as users. Because different WorkMail organizations rely on different directory types, administrators can distinguish between an unregistered user (account is disabled and has a user role) and the directory administrators. The values are USER, RESOURCE, SYSTEM_USER, and REMOTE_USER.

    • EnabledDate (datetime) --

      The date and time at which the user was enabled for WorkMailusage, in UNIX epoch time format.

    • DisabledDate (datetime) --

      The date and time at which the user was disabled for WorkMail usage, in UNIX epoch time format.

    • MailboxProvisionedDate (datetime) --

      The date when the mailbox was created for the user.

    • MailboxDeprovisionedDate (datetime) --

      The date when the mailbox was removed for the user.

    • FirstName (string) --

      First name of the user.

    • LastName (string) --

      Last name of the user.

    • HiddenFromGlobalAddressList (boolean) --

      If enabled, the user is hidden from the global address list.

    • Initials (string) --

      Initials of the user.

    • Telephone (string) --

      User's contact number.

    • Street (string) --

      Street where the user is located.

    • JobTitle (string) --

      Job title of the user.

    • City (string) --

      City where the user is located.

    • Company (string) --

      Company of the user.

    • ZipCode (string) --

      Zip code of the user.

    • Department (string) --

      Department of the user.

    • Country (string) --

      Country where the user is located.

    • Office (string) --

      Office where the user is located.

    • IdentityProviderUserId (string) --

      User ID from the IAM Identity Center. If this parameter is empty it will be updated automatically when the user logs in for the first time to the mailbox associated with WorkMail.

    • IdentityProviderIdentityStoreId (string) --

      Identity Store ID from the IAM Identity Center. If this parameter is empty it will be updated automatically when the user logs in for the first time to the mailbox associated with WorkMail.

ListUsers (updated) Link ¶
Changes (request, response)
Request
{'Filters': {'IdentityProviderUserIdPrefix': 'string'}}
Response
{'Users': {'IdentityProviderIdentityStoreId': 'string',
           'IdentityProviderUserId': 'string'}}

Returns summaries of the organization's users.

See also: AWS API Documentation

Request Syntax

client.list_users(
    OrganizationId='string',
    NextToken='string',
    MaxResults=123,
    Filters={
        'UsernamePrefix': 'string',
        'DisplayNamePrefix': 'string',
        'PrimaryEmailPrefix': 'string',
        'State': 'ENABLED'|'DISABLED'|'DELETED',
        'IdentityProviderUserIdPrefix': 'string'
    }
)
type OrganizationId

string

param OrganizationId

[REQUIRED]

The identifier for the organization under which the users exist.

type NextToken

string

param NextToken

The token to use to retrieve the next page of results. The first call does not contain any tokens.

type MaxResults

integer

param MaxResults

The maximum number of results to return in a single call.

type Filters

dict

param Filters

Limit the user search results based on the filter criteria. You can only use one filter per request.

  • UsernamePrefix (string) --

    Filters only users with the provided username prefix.

  • DisplayNamePrefix (string) --

    Filters only users with the provided display name prefix.

  • PrimaryEmailPrefix (string) --

    Filters only users with the provided email prefix.

  • State (string) --

    Filters only users with the provided state.

  • IdentityProviderUserIdPrefix (string) --

    Filters only users with the ID from the IAM Identity Center.

rtype

dict

returns

Response Syntax

{
    'Users': [
        {
            'Id': 'string',
            'Email': 'string',
            'Name': 'string',
            'DisplayName': 'string',
            'State': 'ENABLED'|'DISABLED'|'DELETED',
            'UserRole': 'USER'|'RESOURCE'|'SYSTEM_USER'|'REMOTE_USER',
            'EnabledDate': datetime(2015, 1, 1),
            'DisabledDate': datetime(2015, 1, 1),
            'IdentityProviderUserId': 'string',
            'IdentityProviderIdentityStoreId': 'string'
        },
    ],
    'NextToken': 'string'
}

Response Structure

  • (dict) --

    • Users (list) --

      The overview of users for an organization.

      • (dict) --

        The representation of an WorkMail user.

        • Id (string) --

          The identifier of the user.

        • Email (string) --

          The email of the user.

        • Name (string) --

          The name of the user.

        • DisplayName (string) --

          The display name of the user.

        • State (string) --

          The state of the user, which can be ENABLED, DISABLED, or DELETED.

        • UserRole (string) --

          The role of the user.

        • EnabledDate (datetime) --

          The date indicating when the user was enabled for WorkMail use.

        • DisabledDate (datetime) --

          The date indicating when the user was disabled from WorkMail use.

        • IdentityProviderUserId (string) --

          User ID from the IAM Identity Center. If this parameter is empty it will be updated automatically when the user logs in for the first time to the mailbox associated with WorkMail.

        • IdentityProviderIdentityStoreId (string) --

          Identity store ID from the IAM Identity Center. If this parameter is empty it will be updated automatically when the user logs in for the first time to the mailbox associated with WorkMail.

    • NextToken (string) --

      The token to use to retrieve the next page of results. This value is null when there are no more results to return.

UpdateUser (updated) Link ¶
Changes (request)
{'IdentityProviderUserId': 'string'}

Updates data for the user. To have the latest information, it must be preceded by a DescribeUser call. The dataset in the request should be the one expected when performing another DescribeUser call.

See also: AWS API Documentation

Request Syntax

client.update_user(
    OrganizationId='string',
    UserId='string',
    Role='USER'|'RESOURCE'|'SYSTEM_USER'|'REMOTE_USER',
    DisplayName='string',
    FirstName='string',
    LastName='string',
    HiddenFromGlobalAddressList=True|False,
    Initials='string',
    Telephone='string',
    Street='string',
    JobTitle='string',
    City='string',
    Company='string',
    ZipCode='string',
    Department='string',
    Country='string',
    Office='string',
    IdentityProviderUserId='string'
)
type OrganizationId

string

param OrganizationId

[REQUIRED]

The identifier for the organization under which the user exists.

type UserId

string

param UserId

[REQUIRED]

The identifier for the user to be updated.

The identifier can be the UserId , Username , or email . The following identity formats are available:

  • User ID: 12345678-1234-1234-1234-123456789012 or S-1-1-12-1234567890-123456789-123456789-1234

  • Email address: user@domain.tld

  • User name: user

type Role

string

param Role

Updates the user role.

You cannot pass SYSTEM_USER or RESOURCE .

type DisplayName

string

param DisplayName

Updates the display name of the user.

type FirstName

string

param FirstName

Updates the user's first name.

type LastName

string

param LastName

Updates the user's last name.

type HiddenFromGlobalAddressList

boolean

param HiddenFromGlobalAddressList

If enabled, the user is hidden from the global address list.

type Initials

string

param Initials

Updates the user's initials.

type Telephone

string

param Telephone

Updates the user's contact details.

type Street

string

param Street

Updates the user's street address.

type JobTitle

string

param JobTitle

Updates the user's job title.

type City

string

param City

Updates the user's city.

type Company

string

param Company

Updates the user's company.

type ZipCode

string

param ZipCode

Updates the user's zip code.

type Department

string

param Department

Updates the user's department.

type Country

string

param Country

Updates the user's country.

type Office

string

param Office

Updates the user's office.

type IdentityProviderUserId

string

param IdentityProviderUserId

User ID from the IAM Identity Center. If this parameter is empty it will be updated automatically when the user logs in for the first time to the mailbox associated with WorkMail.

rtype

dict

returns

Response Syntax

{}

Response Structure

  • (dict) --