Exporting mailbox content

Use the StartMailboxExportJob API action in the Amazon WorkMail API Reference to export Amazon WorkMail mailbox content to an Amazon Simple Storage Service (Amazon S3) bucket. This action exports all email messages and calendar items from the specified mailbox to a .zip file in the Amazon S3 bucket, in MIME format. Other items, such as contacts and tasks, are not exported.

The time it takes for the mailbox export job to finish is dependent on the size and number of items in the mailbox. Because the mailbox export job takes place over a period of time, it does not represent a snapshot of the mailbox content at a single point in time. To see the status of an export job, use the DescribeMailboxExportJob or ListMailboxExportJobs API actions in the Amazon WorkMail API Reference.

When a mailbox export job is completed, the .zip file in the Amazon S3 bucket is encrypted using the symmetric AWS Key Management Service (AWS KMS) customer master key (CMK) that you provide. Because AWS KMS encryption is integrated with Amazon S3, the decrypted data is visible to the user who downloads it, as long as the user has access to the AWS KMS CMK.

Prerequisites

The following are prerequisites for exporting mailbox content:

IAM policy examples and role creation

The following example shows an IAM policy that grants permission to write to the Amazon S3 bucket and encrypt the sent files with the AWS KMS CMK. To use this example policy in the following Example: Exporting mailbox content procedure, save the policy as a JSON file with file name mailbox-export-policy.json.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:AbortMultipartUpload",
                "s3:PutObject",
                "s3:GetBucketPolicyStatus"
            ],
            "Resource": [
                "arn:aws:s3:::amzn-s3-demo-bucket",
                "arn:aws:s3:::amzn-s3-demo-bucket/*"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "kms:Decrypt",
                "kms:GenerateDataKey"
            ],
            "Resource": [
                "arn:aws:kms:us-east-1:111122223333:key/KEY-ID"
            ],
            "Condition": {
                "StringEquals": {
                    "kms:ViaService": "s3.us-east-1.amazonaws.com"
                },
                "StringLike": {
                    "kms:EncryptionContext:aws:s3:arn": "arn:aws:s3:::amzn-s3-demo-bucket/S3-PREFIX*"
                }
            }
        }
    ]
}

The following example shows an IAM trust policy that is attached to the IAM role you create. To use this example policy in the following Example: Exporting mailbox content procedure, save the policy as a JSON file with file name mailbox-export-trust-policy.json.

You don’t have to use the aws:SourceArn and aws:SourceAccount conditions at the same time. For example, you can remove aws:SourceArn from the policy if you need to use the same role to export messages from different Amazon WorkMail organizations under the same AWS account. For more information about condition keys, refer to the AWS global condition context keys in the AWS Identity and Access Management user guide.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "",
      "Effect": "Allow",
      "Principal": {
        "Service": "export.workmail.amazonaws.com"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": { 
          "aws:SourceAccount": "111122223333"
        },
        "ArnLike": {
          "aws:SourceArn": "arn:aws:workmail:us-east-1:111122223333:organization/m-a123b4c5de678fg9h0ij1k2lm234no56"
        }
      }
    }
  ]
}

You can use the AWS CLI to create the IAM role in your account by running the following commands.

aws iam create-role --role-name WorkmailMailboxExportRole --assume-role-policy-document file://mailbox-export-trust-policy.json --region us-east-1

aws iam put-role-policy --role-name WorkmailMailboxExportRole --policy-name MailboxExport --policy-document file://mailbox-export-policy.json

For more information about the AWS CLI, see the AWS Command Line Interface User Guide.

Example: Exporting mailbox content

After you create the IAM role and policies in the preceding section, complete the following steps to export your mailbox content. You must have your Amazon WorkMail organization ID and user ID (entity ID), which you can access in the Amazon WorkMail console or by using the Amazon WorkMail API.

When the mailbox export job state is COMPLETED, the exported mailbox items are available in a .zip file in the specified Amazon S3 bucket.

The following is an example of the output log from the exported mailbox:

{
  "totalNonExportableItems" : "13",
  "totalMessages" : "76",
  "sha384Hash" : "4de93a***96a1dd",
  "totalBytes" : "161892",
  "totalFolders" : "15",
  "startTime" : "168***380",
  "endTime" : "168***384"
}   
        

Considerations

The following considerations apply when exporting mailbox jobs for Amazon WorkMail: