2024/10/30 - Amazon WorkMail - 8 new5 updated api methods
Changes This release adds support for Multi-Factor Authentication (MFA) and Personal Access Tokens through integration with AWS IAM Identity Center.
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'
)
string
[REQUIRED]
The Organization ID.
string
[REQUIRED]
The Personal Access Token ID.
dict
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) --
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
)
string
[REQUIRED]
The Organization ID.
string
The WorkMail User ID.
string
The token from the previous response to query the next page.
integer
The maximum amount of items that should be returned in a response.
dict
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) --
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'
)
string
[REQUIRED]
The Organization ID.
dict
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.
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'
)
string
[REQUIRED]
The name of the IAM Identity Center application.
string
[REQUIRED]
The Amazon Resource Name (ARN) of the instance.
string
The idempotency token associated with the request.
This field is autopopulated if not provided.
dict
Response Syntax
{
'ApplicationArn': 'string'
}
Response Structure
(dict) --
ApplicationArn (string) --
The Amazon Resource Name (ARN) of the application.
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
}
)
string
[REQUIRED]
The ID of the WorkMail Organization.
string
[REQUIRED]
The authentication mode used in WorkMail.
dict
[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.
dict
[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.
dict
Response Syntax
{}
Response Structure
(dict) --
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'
)
string
[REQUIRED]
The Organization ID.
dict
Response Syntax
{}
Response Structure
(dict) --
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'
)
string
[REQUIRED]
The Amazon Resource Name (ARN) of the application.
dict
Response Syntax
{}
Response Structure
(dict) --
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'
)
string
[REQUIRED]
The Organization ID.
string
[REQUIRED]
The Personal Access Token ID.
dict
Response Syntax
{}
Response Structure
(dict) --
{'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'
)
string
[REQUIRED]
The identifier of the organization for which the user is created.
string
[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.
string
[REQUIRED]
The display name for the new user.
string
The password for the new user.
string
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.
string
The first name of the new user.
string
The last name of the new user.
boolean
If this parameter is enabled, the user will be hidden from the address book.
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.
dict
Response Syntax
{
'UserId': 'string'
}
Response Structure
(dict) --
UserId (string) --
The identifier for the new user.
{'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
)
string
The idempotency token associated with the request.
This field is autopopulated if not provided.
string
[REQUIRED]
The organization ID.
boolean
[REQUIRED]
If true, deletes the AWS Directory Service directory associated with the organization.
boolean
Deletes a WorkMail organization even if the organization has enabled users.
boolean
Deletes IAM Identity Center application for WorkMail. This action does not affect authentication settings for any organization.
dict
Response Syntax
{
'OrganizationId': 'string',
'State': 'string'
}
Response Structure
(dict) --
OrganizationId (string) --
The organization ID.
State (string) --
The state of the organization.
{'IdentityProviderIdentityStoreId': 'string',
'IdentityProviderUserId': 'string'}
Provides information regarding the user.
See also: AWS API Documentation
Request Syntax
client.describe_user(
OrganizationId='string',
UserId='string'
)
string
[REQUIRED]
The identifier for the organization under which the user exists.
string
[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
dict
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.
{'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'
}
)
string
[REQUIRED]
The identifier for the organization under which the users exist.
string
The token to use to retrieve the next page of results. The first call does not contain any tokens.
integer
The maximum number of results to return in a single call.
dict
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.
dict
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.
{'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'
)
string
[REQUIRED]
The identifier for the organization under which the user exists.
string
[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
string
Updates the user role.
You cannot pass SYSTEM_USER or RESOURCE.
string
Updates the display name of the user.
string
Updates the user's first name.
string
Updates the user's last name.
boolean
If enabled, the user is hidden from the global address list.
string
Updates the user's initials.
string
Updates the user's contact details.
string
Updates the user's street address.
string
Updates the user's job title.
string
Updates the user's city.
string
Updates the user's company.
string
Updates the user's zip code.
string
Updates the user's department.
string
Updates the user's country.
string
Updates the user's office.
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.
dict
Response Syntax
{}
Response Structure
(dict) --