organizations

Creates, updates, deletes, gets or lists an organizations resource.

Overview

Name	organizations
Type	Resource
Id	aws.workmail.organizations

Fields

The following fields are returned by SELECT queries:

describe_organization

Name	Datatype	Description
arn	string	The Amazon Resource Name (ARN) of the organization. (pattern: <code>arn:aws:workmail:[a-z0-9-]*:[a-z0-9-]+:[A-Za-z0-9][A-Za-z0-9:_/+=,@.-]{0,1023}</code>)
alias	string	The alias for an organization. (pattern: <code>^(?!d-)([\da-zA-Z]+)([-][\da-zA-Z]+)*</code>)
completed_date	string (date-time)	The date at which the organization became usable in the WorkMail context, in UNIX epoch time format.
default_mail_domain	string	The default mail domain associated with the organization.
directory_id	string	The identifier for the directory associated with an WorkMail organization.
directory_type	string	The type of directory associated with the WorkMail organization.
error_message	string	(Optional) The error message indicating if unexpected behavior was encountered with regards to the organization.
interoperability_enabled	boolean	Indicates if interoperability is enabled for this organization.
migration_admin	string	The user ID of the migration admin if migration is enabled for the organization.
organization_id	string	The identifier of an organization. (pattern: <code>^m-[0-9a-f]{32}$</code>)
state	string	The state of an organization.

list_organizations

Name	Datatype	Description
alias	string	The alias associated with the organization. (pattern: <code>^(?!d-)([\da-zA-Z]+)([-][\da-zA-Z]+)*</code>)
default_mail_domain	string	The default email domain associated with the organization. (pattern: <code>[a-zA-Z0-9.-]+</code>)
error_message	string	The error message associated with the organization. It is only present if unexpected behavior has occurred with regards to the organization. It provides insight or solutions regarding unexpected behavior.
organization_id	string	The identifier associated with the organization. (pattern: <code>^m-[0-9a-f]{32}$</code>)
state	string	The state associated with the organization.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
describe_organization	select	region		Provides more information regarding a given organization based on its identifier.
list_organizations	select	region		Returns summaries of the customer's organizations.
register_to_work_mail	insert	region, OrganizationId, EntityId, Email		Registers an existing and disabled user, group, or resource for WorkMail use by associating a mailbox and calendaring capabilities. It performs no change if the user, group, or resource is enabled and fails if the user, group, or resource is deleted. This operation results in the accumulation of costs. For more information, see Pricing. The equivalent console functionality for this operation is Enable. Users can either be created by calling the CreateUser API operation or they can be synchronized from your directory. For more information, see DeregisterFromWorkMail.
create_alias	insert	region, OrganizationId, EntityId		Adds an alias to the set of a given member (user or group) of WorkMail.
create_organization	insert	region		Creates a new WorkMail organization. Optionally, you can choose to associate an existing AWS Directory Service directory with your organization. If an AWS Directory Service directory ID is specified, the organization alias must match the directory alias. If you choose not to associate an existing directory with your organization, then we create a new WorkMail directory for you. For more information, see Adding an organization in the WorkMail Administrator Guide. You can associate multiple email domains with an organization, then choose your default email domain from the WorkMail console. You can also associate a domain that is managed in an Amazon Route 53 public hosted zone. For more information, see Adding a domain and Choosing the default domain in the WorkMail Administrator Guide. Optionally, you can use a customer managed key from AWS Key Management Service (AWS KMS) to encrypt email for your organization. If you don't associate an AWS KMS key, WorkMail creates a default, AWS managed key for you.
update_mailbox_quota	update	region, OrganizationId, UserId, MailboxQuota		Updates a user's current mailbox quota for a specified organization and user.
update_primary_email_address	update	region, OrganizationId, EntityId, Email		Updates the primary email for a user, group, or resource. The current email is moved into the list of aliases (or swapped between an existing alias and the current primary email), and the email provided in the input is promoted as the primary.
put_retention_policy	replace	region, OrganizationId, Name, FolderConfigurations		Puts a retention policy to the specified organization.
delete_alias	delete	region		Remove one or more specified aliases from a set of aliases for a given user.
delete_organization	delete	region		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.
delete_retention_policy	delete	region		Deletes the specified retention policy from the specified organization.
cancel_mailbox_export_job	exec	region, ClientToken, JobId, OrganizationId		Cancels a mailbox export job. If the mailbox export job is near completion, it might not be possible to cancel it.
deregister_from_work_mail	exec	region, OrganizationId, EntityId		Mark a user, group, or resource as no longer used in WorkMail. This action disassociates the mailbox and schedules it for clean-up. WorkMail keeps mailboxes for 30 days before they are permanently removed. The functionality in the console is Disable.
reset_password	exec	region, OrganizationId, UserId, Password		Allows the administrator to reset the password for a user.
start_mailbox_export_job	exec	region, ClientToken, OrganizationId, EntityId, RoleArn, KmsKeyArn, S3BucketName, S3Prefix		Starts a mailbox export job to export MIME-format email messages and calendar items from the specified mailbox to the specified Amazon Simple Storage Service (Amazon S3) bucket. For more information, see Exporting mailbox content in the WorkMail Administrator Guide.
test_availability_configuration	exec	region, OrganizationId		Performs a test on an availability provider to ensure that access is allowed. For EWS, it verifies the provided credentials can be used to successfully log in. For Lambda, it verifies that the Lambda function can be invoked and that the resource access policy was configured to deny anonymous access. An anonymous invocation is one done without providing either a SourceArn or SourceAccount header. The request must contain either one provider definition (EwsProvider or LambdaProvider) or the DomainName parameter. If the DomainName parameter is provided, the configuration stored under the DomainName will be tested.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
region	string	AWS region (default: us-east-1)

SELECT examples

describe_organization

Provides more information regarding a given organization based on its identifier.

SELECT
arn,
alias,
completed_date,
default_mail_domain,
directory_id,
directory_type,
error_message,
interoperability_enabled,
migration_admin,
organization_id,
state
FROM aws.workmail.organizations
WHERE region = '{{ region }}' -- required
;

list_organizations

Returns summaries of the customer's organizations.

SELECT
alias,
default_mail_domain,
error_message,
organization_id,
state
FROM aws.workmail.organizations
WHERE region = '{{ region }}' -- required
;

INSERT examples

register_to_work_mail

Registers an existing and disabled user, group, or resource for WorkMail use by associating a mailbox and calendaring capabilities. It performs no change if the user, group, or resource is enabled and fails if the user, group, or resource is deleted. This operation results in the accumulation of costs. For more information, see Pricing. The equivalent console functionality for this operation is Enable. Users can either be created by calling the CreateUser API operation or they can be synchronized from your directory. For more information, see DeregisterFromWorkMail.

INSERT INTO aws.workmail.organizations (
OrganizationId,
EntityId,
Email,
region
)
SELECT 
'{{ OrganizationId }}' /* required */,
'{{ EntityId }}' /* required */,
'{{ Email }}' /* required */,
'{{ region }}'
;

create_alias

Adds an alias to the set of a given member (user or group) of WorkMail.

INSERT INTO aws.workmail.organizations (
OrganizationId,
EntityId,
Alias,
region
)
SELECT 
'{{ OrganizationId }}' /* required */,
'{{ EntityId }}' /* required */,
'{{ Alias }}',
'{{ region }}'
;

create_organization

Creates a new WorkMail organization. Optionally, you can choose to associate an existing AWS Directory Service directory with your organization. If an AWS Directory Service directory ID is specified, the organization alias must match the directory alias. If you choose not to associate an existing directory with your organization, then we create a new WorkMail directory for you. For more information, see Adding an organization in the WorkMail Administrator Guide. You can associate multiple email domains with an organization, then choose your default email domain from the WorkMail console. You can also associate a domain that is managed in an Amazon Route 53 public hosted zone. For more information, see Adding a domain and Choosing the default domain in the WorkMail Administrator Guide. Optionally, you can use a customer managed key from AWS Key Management Service (AWS KMS) to encrypt email for your organization. If you don't associate an AWS KMS key, WorkMail creates a default, AWS managed key for you.

INSERT INTO aws.workmail.organizations (
DirectoryId,
Alias,
ClientToken,
Domains,
KmsKeyArn,
EnableInteroperability,
region
)
SELECT 
'{{ DirectoryId }}',
'{{ Alias }}',
'{{ ClientToken }}',
'{{ Domains }}',
'{{ KmsKeyArn }}',
{{ EnableInteroperability }},
'{{ region }}'
RETURNING
organization_id
;

Manifest

# Description fields are for documentation purposes
- name: organizations
props:
  - name: region
    value: "{{ region }}"
    description: Required parameter for the organizations resource.
  - name: OrganizationId
    value: "{{ OrganizationId }}"
    description: |
      The organization under which the member (user or group) exists.
  - name: EntityId
    value: "{{ EntityId }}"
    description: |
      The member (user or group) to which this alias is added.
  - name: Email
    value: "{{ Email }}"
    description: |
      The email for the user, group, or resource to be updated.
  - name: Alias
    value: "{{ Alias }}"
    description: |
      The organization alias.
  - name: DirectoryId
    value: "{{ DirectoryId }}"
    description: |
      The AWS Directory Service directory ID.
  - name: ClientToken
    value: "{{ ClientToken }}"
    description: |
      The idempotency token associated with the request.
  - name: Domains
    description: |
      The email domains to associate with the organization.
    value:
      - DomainName: "{{ DomainName }}"
        HostedZoneId: "{{ HostedZoneId }}"
  - name: KmsKeyArn
    value: "{{ KmsKeyArn }}"
    description: |
      The Amazon Resource Name (ARN) of a customer managed key from AWS KMS.
  - name: EnableInteroperability
    value: {{ EnableInteroperability }}
    description: |
      When true, allows organization interoperability between WorkMail and Microsoft Exchange. If true, you must include a AD Connector directory ID in the request.

UPDATE examples

update_mailbox_quota

Updates a user's current mailbox quota for a specified organization and user.

UPDATE aws.workmail.organizations
SET 
OrganizationId = '{{ OrganizationId }}',
UserId = '{{ UserId }}',
MailboxQuota = {{ MailboxQuota }}
WHERE 
region = '{{ region }}' --required
AND OrganizationId = '{{ OrganizationId }}' --required
AND UserId = '{{ UserId }}' --required
AND MailboxQuota = '{{ MailboxQuota }}' --required;

update_primary_email_address

Updates the primary email for a user, group, or resource. The current email is moved into the list of aliases (or swapped between an existing alias and the current primary email), and the email provided in the input is promoted as the primary.

UPDATE aws.workmail.organizations
SET 
OrganizationId = '{{ OrganizationId }}',
EntityId = '{{ EntityId }}',
Email = '{{ Email }}'
WHERE 
region = '{{ region }}' --required
AND OrganizationId = '{{ OrganizationId }}' --required
AND EntityId = '{{ EntityId }}' --required
AND Email = '{{ Email }}' --required;

REPLACE examples

put_retention_policy

Puts a retention policy to the specified organization.

REPLACE aws.workmail.organizations
SET 
OrganizationId = '{{ OrganizationId }}',
Id = '{{ Id }}',
Name = '{{ Name }}',
Description = '{{ Description }}',
FolderConfigurations = '{{ FolderConfigurations }}'
WHERE 
region = '{{ region }}' --required
AND OrganizationId = '{{ OrganizationId }}' --required
AND Name = '{{ Name }}' --required
AND FolderConfigurations = '{{ FolderConfigurations }}' --required;

DELETE examples

delete_alias

Remove one or more specified aliases from a set of aliases for a given user.

DELETE FROM aws.workmail.organizations
WHERE region = '{{ region }}' --required
;

delete_organization

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.

DELETE FROM aws.workmail.organizations
WHERE region = '{{ region }}' --required
;

delete_retention_policy

Deletes the specified retention policy from the specified organization.

DELETE FROM aws.workmail.organizations
WHERE region = '{{ region }}' --required
;

Lifecycle Methods

cancel_mailbox_export_job

Cancels a mailbox export job. If the mailbox export job is near completion, it might not be possible to cancel it.

EXEC aws.workmail.organizations.cancel_mailbox_export_job 
@region='{{ region }}' --required 
@@json=
'{
"ClientToken": "{{ ClientToken }}", 
"JobId": "{{ JobId }}", 
"OrganizationId": "{{ OrganizationId }}"
}'
;

deregister_from_work_mail

Mark a user, group, or resource as no longer used in WorkMail. This action disassociates the mailbox and schedules it for clean-up. WorkMail keeps mailboxes for 30 days before they are permanently removed. The functionality in the console is Disable.

EXEC aws.workmail.organizations.deregister_from_work_mail 
@region='{{ region }}' --required 
@@json=
'{
"OrganizationId": "{{ OrganizationId }}", 
"EntityId": "{{ EntityId }}"
}'
;

reset_password

Allows the administrator to reset the password for a user.

EXEC aws.workmail.organizations.reset_password 
@region='{{ region }}' --required 
@@json=
'{
"OrganizationId": "{{ OrganizationId }}", 
"UserId": "{{ UserId }}", 
"Password": "{{ Password }}"
}'
;

start_mailbox_export_job

Starts a mailbox export job to export MIME-format email messages and calendar items from the specified mailbox to the specified Amazon Simple Storage Service (Amazon S3) bucket. For more information, see Exporting mailbox content in the WorkMail Administrator Guide.

EXEC aws.workmail.organizations.start_mailbox_export_job 
@region='{{ region }}' --required 
@@json=
'{
"ClientToken": "{{ ClientToken }}", 
"OrganizationId": "{{ OrganizationId }}", 
"EntityId": "{{ EntityId }}", 
"Description": "{{ Description }}", 
"RoleArn": "{{ RoleArn }}", 
"KmsKeyArn": "{{ KmsKeyArn }}", 
"S3BucketName": "{{ S3BucketName }}", 
"S3Prefix": "{{ S3Prefix }}"
}'
;

test_availability_configuration

Performs a test on an availability provider to ensure that access is allowed. For EWS, it verifies the provided credentials can be used to successfully log in. For Lambda, it verifies that the Lambda function can be invoked and that the resource access policy was configured to deny anonymous access. An anonymous invocation is one done without providing either a SourceArn or SourceAccount header. The request must contain either one provider definition (EwsProvider or LambdaProvider) or the DomainName parameter. If the DomainName parameter is provided, the configuration stored under the DomainName will be tested.

EXEC aws.workmail.organizations.test_availability_configuration 
@region='{{ region }}' --required 
@@json=
'{
"OrganizationId": "{{ OrganizationId }}", 
"DomainName": "{{ DomainName }}", 
"EwsProvider": "{{ EwsProvider }}", 
"LambdaProvider": "{{ LambdaProvider }}"
}'
;