End of support notice: On March 31, 2027, AWS will end support for Amazon WorkMail. After March 31, 2027, you will no longer be able to access the Amazon WorkMail console or Amazon WorkMail resources. For more information, see [Amazon WorkMail end of support](https://docs.aws.amazon.com/workmail/latest/adminguide/workmail-end-of-support.html).
# Logging and monitoring in Amazon WorkMail
Monitoring and auditing your email and logs is important for maintaining the health of your Amazon WorkMail organization. Amazon WorkMail supports two types of monitoring:
+ **Event logging** – Monitoring the email sending activity for your organization helps protect your domain reputation. Monitoring can also help you track emails that are sent and received. For more information about how to enable email event logging, see [Enabling email event logging](tracking.md).
+ **Audit logging** – You can use audit logs to capture detailed information about your Amazon WorkMail organization usage such as monitor user’s access to mailboxes, audit for suspicious activity, and debug access control and availability provider configurations. For more information, see [Enabling audit logging](audit-logging.md).
AWS provides the following monitoring tools to watch Amazon WorkMail, report when something is wrong, and take automatic actions when appropriate:
+ *Amazon CloudWatch* monitors your AWS resources and the applications that you run on AWS in real time. For example, when you enable email event logging for Amazon WorkMail, CloudWatch can track emails sent and received for your organization. For more information about monitoring Amazon WorkMail with CloudWatch, see [Monitoring Amazon WorkMail with CloudWatch metrics](monitoring-workmail-cloudwatch.md). For more information about CloudWatch, see the [Amazon CloudWatch User Guide](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/).
+ *Amazon CloudWatch Logs* enables you to monitor, store, and access your email events and audit logs for Amazon WorkMail when email and audit logging is enabled in the Amazon WorkMail console. CloudWatch Logs can monitor information in the log files, and you can archive your log data in highly durable storage. For more information about tracking Amazon WorkMail messages using CloudWatch Logs, see [Enabling email event logging](tracking.md) and [Enabling audit logging](audit-logging.md). For more information about CloudWatch Logs, see the [Amazon CloudWatch Logs User Guide](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/).
+ *AWS CloudTrail* captures API calls and related events made by or on behalf of your AWS account, and delivers the log files to an Amazon S3 bucket that you specify. You can identify which users and accounts called AWS, the source IP address from which the calls were made, and when the calls occurred. For more information, see [Logging Amazon WorkMail API calls with AWS CloudTrail](logging-using-cloudtrail.md).
+ *Amazon S3* enables you to store and access your Amazon WorkMail events in a cost-effective way. Amazon S3 provides mechanisms for managing the [event data lifecycle](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html), enabling you to configure automatic deletion of old events, or configure automatic archival to [Amazon S3 Glacier](https://docs.aws.amazon.com/AmazonS3/latest/userguide/storage-class-intro.html#sc-glacier). Note, delivery Amazon S3 is only available for audit logging events. For more information about Amazon S3, see the [Amazon S3 User Guide](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Welcome.html).
+ *Amazon Data Firehose* enables you to stream your event data to other AWS services such as Amazon Simple Storage Service (Amazon S3), Amazon Redshift, Amazon OpenSearch Service, Amazon OpenSearch Serverless, Splunk, and any custom HTTP endpoint or HTTP endpoints owned by supported third-party service providers, including Datadog, Dynatrace, LogicMonitor, MongoDB, New Relic, Coralogix, and Elastic. Delivery to Firehose is only available for audit logging events. For more information about Firehose, see the [Amazon Data Firehose developer guide](https://docs.aws.amazon.com/firehose/latest/dev/what-is-this-service.html).
**Topics**
+ [Monitoring Amazon WorkMail with CloudWatch metrics](monitoring-workmail-cloudwatch.md)
+ [Monitoring Amazon WorkMail email event logs](cw-events.md)
+ [Monitoring Amazon WorkMail audit logs](monitoring-audit-logging.md)
+ [Using CloudWatch Insights with Amazon WorkMail](cw-insights.md)
+ [Logging Amazon WorkMail API calls with AWS CloudTrail](logging-using-cloudtrail.md)
+ [Enabling email event logging](tracking.md)
+ [Enabling audit logging](audit-logging.md)
# Monitoring Amazon WorkMail with CloudWatch metrics
You can monitor Amazon WorkMail using CloudWatch, which collects raw data and processes it into readable, near real-time metrics. The no charge metrics are stored for 15 months so that you can access historical information to see how your web application or service is performing. You can also set alarms that watch for certain thresholds, and send notifications or take actions when those thresholds are met. For more information, see the [Amazon CloudWatch User Guide](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/).
## CloudWatch metrics for Amazon WorkMail
Amazon WorkMail sends the following metrics and dimension information to CloudWatch.
The `AWS/WorkMail` namespace includes the following metrics.
| Metric | Description |
| --- | --- |
| `OrganizationEmailReceived` | The number of emails received by your Amazon WorkMail organization. If one email is addressed to 10 recipients in your organization, the `OrganizationEmailReceived` count is one. Units: Count |
| `MailboxEmailDelivered` | The number of emails delivered to individual mailboxes in your Amazon WorkMail organization. If one email is successfully delivered to 10 recipients in your organization, the `MailboxEmailDelivered` count is 10. Units: Count |
| `IncomingEmailBounced` | The number of incoming emails that bounced due to full mailboxes. This metric is counted for each intended recipient. For example, if one email is sent to 10 recipients in your organization, and two of the recipients have full mailboxes resulting in a bounce response, the `IncomingEmailBounced` count is two. Units: Count |
| `OutgoingEmailBounced` | The number of outgoing emails that couldn't be delivered. This metric is counted for each intended recipient. For example, if one email is sent to 10 recipients, and two emails could not be delivered, the `OutgoingEmailBounced` count is 2. Units: Count |
| `OutgoingEmailSent` | The number of emails successfully sent from your Amazon WorkMail organization. This metric is counted for each recipient of a successfully sent email. For example, if 1 email is sent to 10 recipients, and the email was successfully delivered to 8 of the recipients, the `OutgoingEmailSent` count is 8. Units: Count |
| `AuthenticationFailure` | This metric counts the number of authentication attempts. When authentication is successful, the count is 0 and when authentication is unsuccessful, the count is 1. Use the `Sum` statistic to monitor the amount of failed authentication attempts. Use the `Sample count` statistic to monitor the total number of authentication events. Use the `Average` statistic to monitor the ratio of failed and successful authentication events. Units: Count |
| `AccessDenied` | This metric counts the number of access control evaluations. When action is denied by access control, the count is 1 and when action is granted, the count is 0. Use the `Sum` statistic to monitor the volume of denied actions, the `Sample count` statistic to monitor the total number of attempted actions, and the `Average` statistic to monitor the ratio of allowed and denied actions. Units: Count |
| `ActionDenied` | This metric is counted when there's action on mailbox data. When action is denied, the count is 1 and if action is granted, the count is 0. Use the `Sum` statistic to monitor the volume of denied mailbox actions, the `Sample count` statistic to monitor the total number of attempted mailbox actions, and the `Average` statistic to monitor the ratio of allowed and denied actions. Units: Count |
| `AvailabilityProviderFailure` | This metric is counted for every *availability provider* request that Amazon WorkMail executes to retrieve calendar availability from an external source. For more information about Availability Providers, see the Amazon WorkMail Administrator Guide. |
# Monitoring Amazon WorkMail email event logs
When you turn on email event logging for your Amazon WorkMail organization, Amazon WorkMail logs email events with CloudWatch. For more information about turning on email event logging, see [Enabling email event logging](tracking.md).
The following tables describe the events that Amazon WorkMail logs with CloudWatch, when the events are transmitted, and what the event fields contain.
**`ORGANIZATION_EMAIL_RECEIVED`**
This event is logged when your Amazon WorkMail organization receives an email message.
| Field | Description |
| --- | --- |
| recipients | The intended recipients of the message. |
| sender | The email address of the user who sent the email message on behalf of another user. This field is set only when an email is sent on behalf of another user. |
| from | The **From** address, which is usually the email address of the user who sent the message. If the user sent the message as another user or on behalf of another user, this field returns the email address of the user on whose behalf the email was sent, not the email address of the actual sender. |
| subject | The email message subject. |
| messageId | The SMTP message ID. |
| spamVerdict | Indicates whether the message is marked as spam by Amazon SES. For more information, see [Contents of Notifications for Amazon SES Email Receiving](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/receiving-email-notifications-contents.html) in the *Amazon Simple Email Service Developer Guide*. |
| dkimVerdict | Indicates whether the DomainKeys Identified Mail (DKIM) check passed. For more information, see [Contents of Notifications for Amazon SES Email Receiving](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/receiving-email-notifications-contents.html) in the *Amazon Simple Email Service Developer Guide*. |
| dmarcVerdict | Indicates whether the Domain-based Message Authentication, Reporting and Conformance (DMARC) check passed. For more information, see [Contents of Notifications for Amazon SES Email Receiving](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/receiving-email-notifications-contents.html) in the *Amazon Simple Email Service Developer Guide*. |
| dmarcPolicy | Appears only when the dmarcVerdict field contains "FAIL". Indicates the action to take on the email when the DMARC check fails (NONE, QUARANTINE, or REJECT). This is set by the owner of the sending email domain. |
| spfVerdict | Indicates whether the Sender Policy Framework (SPF) checks passed. For more information, see [Contents of Notifications for Amazon SES Email Receiving](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/receiving-email-notifications-contents.html) in the *Amazon Simple Email Service Developer Guide*. |
| messageTimestamp | Indicates when the message is received. |
**`MAILBOX_EMAIL_DELIVERED`**
This event is logged when a message is delivered to a mailbox in your organization. This is logged once for each mailbox to which a message is delivered, so a single `ORGANIZATION_EMAIL_RECEIVED` event can result in multiple `MAILBOX_EMAIL_DELIVERED` events.
| Field | Description |
| --- | --- |
| recipient | The mailbox to which the message is delivered. |
| folder | The mailbox folder where the message is placed. |
**`RULE_APPLIED`**
This event is logged when an incoming or outgoing message starts an email flow rule.
| Field | Description |
| --- | --- |
| ruleName | The name of the rule. |
| ruleType | The type of rule applied (INBOUND\$1RULE, OUTBOUND\$1RULE, or MAILBOX\$1RULE). Inbound and outbound rules apply to your Amazon WorkMail organization. Mailbox rules apply only to specified mailboxes. For more information, see [Managing email flows](email-flows.md). |
| ruleActions | Actions taken based on the rule. Different recipients of the message might have different actions, such as a bounced email or a successfully delivered email. |
| targetFolder | Intended destination folder for a `Move` or `Copy` MAILBOX\$1RULE. |
| targetRecipient | Intended recipient of a `Forward` or `Redirect` MAILBOX\$1RULE. |
**`JOURNALING_INITIATED`**
This event is logged when Amazon WorkMail sends an email to the journaling address specified by your organization administrator. This is only transmitted if journaling is configured for your organization. For more information, see [Using email journaling with Amazon WorkMail](journaling_overview.md).
| Field | Description |
| --- | --- |
| journalingAddress | The email address to which the journaling message is sent. |
**`INCOMING_EMAIL_BOUNCED`**
This event is logged when an incoming message can't be delivered to a target recipient. Emails can bounce for a number of reasons, such as a full target mailbox. The system logs this event once for each recipient that results in a bounced email. For example, if an incoming message is addressed to three recipients and two of them have full mailboxes, two INCOMING\$1EMAIL\$1BOUNCED events are logged.
| Field | Description |
| --- | --- |
| bouncedRecipient | The intended recipient for which Amazon WorkMail bounced the message. |
**`OUTGOING_EMAIL_SUBMITTED`**
This event is logged when a user in your organization submits an email message for sending. This is logged before the message leaves Amazon WorkMail, so this event doesn't indicate whether the email is successfully delivered.
| Field | Description |
| --- | --- |
| recipients | The recipients of the message as specified by the sender. Includes all recipients on the To, CC, and BCC lines. |
| sender | The email address of the user who sent the email message on behalf of another user. This field is set only when an email is sent on behalf of another user. |
| from | The **From** address, which is usually the email address of the user who sent the message. If the user sent the message as another user or on behalf of another user, this field returns the email address of the user on whose behalf the email was sent, not the email address of the actual sender. |
| subject | The email message subject. |
**`OUTGOING_EMAIL_SENT`**
This event is logged when an outgoing email is successfully delivered to a target recipient. This is logged once for each successful recipient, so a single `OUTGOING_EMAIL_SUBMITTED` can result in multiple `OUTGOING_EMAIL_SENT` entries.
| Field | Description |
| --- | --- |
| recipient | The recipient of the successfully delivered email. |
| sender | The email address of the user who sent the email message on behalf of another user. This field is set only when an email is sent on behalf of another user. |
| from | The **From** address, which is usually the email address of the user who sent the message. If the user sent the message as another user or on behalf of another user, this field returns the email address of the user on whose behalf the email was sent, not the email address of the actual sender. |
| messageId | The SMTP message ID. |
**`OUTGOING_EMAIL_BOUNCED`**
This event is logged when an outgoing message can't be delivered to a target recipient. Emails can bounce for a number of reasons, such as a full target mailbox. The system logs a bounce for each recipient that results in a bounced email. For example, if an outgoing message is addressed to three recipients and two of them have full mailboxes, two `OUTGOING_EMAIL_BOUNCED` events are logged.
| Field | Description |
| --- | --- |
| bouncedRecipient | The intended recipient for which the destination mail server bounced the message. |
**`DMARC_POLICY_APPLIED`**
This event is logged when a DMARC policy is applied to an email sent to your organization.
| Field | Description |
| --- | --- |
| from | The From address, which is usually the email address of the user who sent the message. If the user sent the message as another user or on behalf of another user, this field returns the email address of the user on whose behalf the email was sent, not the email address of the actual sender. |
| recipients | The intended recipients of the message. |
| policy | The applied DMARC policy, indicating the action to take on the email when the DMARC check fails (NONE, QUARANTINE, or REJECT). This is the same as the dmarcPolicy field in the ORGANIZATION\$1EMAIL\$1RECEIVED event. |
# Monitoring Amazon WorkMail audit logs
You can use audit logs to monitor access to your Amazon WorkMail Organization’s mailboxes. Amazon WorkMail logs five types of audit events and these events can be published to CloudWatch Logs, Amazon S3, or Amazon Firehouse. You can use audit logs to monitor user interaction with your Organization’s mailboxes, authentication attempts, access control rule evaluation, and perform availability provider calls to external systems and monitor events with personal access tokens. For information about configuring audit logging, see [Enabling audit logging](audit-logging.md).
The following sections describe the audit events logged by Amazon WorkMail, when the events are transmitted, and information about the event fields.
## Mailbox access logs
Mailbox access events provide information about what action was taken (or attempted) on which mailbox object. A mailbox access event is generated for every operation that you attempt to run on an item or folder in a mailbox. These events are useful for auditing access to mailbox data.
| Field | Description |
| --- | --- |
| event\$1timestamp | When the event happened, in milliseconds since Unix epoch. |
| request\$1id | The ID that uniquely identifies the request. |
| organization\$1arn | The ARN of the & Amazon WorkMail Organization to which the authenticated user belongs. |
| user\$1id | The ID of the authenticated user. |
| impersonator\$1id | The ID of the impersonator. Present only if the impersonation feature was used for the request. |
| protocol | The protocol used. The protocol can be: `AutoDiscover`, `EWS`, `IMAP`, `WindowsOutlook`, `ActiveSync`, `SMTP`, `WebMail`, `IncomingEmail`, or `OutgoingEmail`. |
| source\$1ip | The source IP address of the request. |
| user\$1agent | The user agent that made the request. |
| action | The action taken on the object, which can be: `read`, `read_hierarchy`, `read_summary`, `read_attachment`, `read_permissions`, `create`, `update`, `update_permissions`, `update_read_state`, `delete`, `submit_email_for_sending`, `abort_sending_email`, `move`, `move_to`, `copy`, or `copy_to`. |
| owner\$1id | The ID of the user that owns the object being acted upon. |
| object\$1type | The object type, which can be: Folder, Message, or Attachment. |
| item\$1id | The ID that uniquely identifies the message that's the subject of the event or that contains the attachment that's the subject of the event. |
| folder\$1path | The path of the folder being acted upon or the path of the folder containing the item being acted upon. |
| folder\$1id | The ID that uniquely identifies the folder that's the subject of the event or contains the object that's the subject of the event. |
| attachment\$1path | The path of display names to the affected attachment. |
| action\$1allowed | Whether the action was allowed. Can be true or false. |
## Access control logs
Access control events are generated whenever an access control rule is evaluated. These logs are useful for auditing forbidden access, or debugging access control configurations.
| Field | Description |
| --- | --- |
| event\$1timestamp | When the event happened, in milliseconds since Unix epoch. |
| request\$1id | The ID that uniquely identifies the request. |
| organization\$1arn | The ARN of the WorkMail Organization to which the authenticated user belongs. |
| user\$1id | The ID of the authenticated user. |
| impersonator\$1id | The ID of the impersonator. Present only if the impersonation feature was used for the request. |
| protocol | The protocol used, which can be: `AutoDiscover`, `EWS`, `IMAP`, `WindowsOutlook`, `ActiveSync`, `SMTP`, `WebMail`, `IncomingEmail`, or `OutgoingEmail`. |
| source\$1ip | The source IP address of the request. |
| scope | The scope of the rule, which can be: `AccessControl`, `DeviceAccessControl`, or `ImpersonationAccessControl`. |
| rule\$1id | The ID of the matched access control rule. When there are no rules matched, *rule\$1id* is not available. |
| access\$1granted | Whether access was allowed. Can be true or false. |
## Authentication logs
Authentication events contain information about authentication attempts.
**Note**
Authentication events are not generated for authentication events through the Amazon WorkMail WebMail application.
| Field | Description |
| --- | --- |
| event\$1timestamp | When the event happened, in milliseconds since Unix epoch. |
| request\$1id | The ID that uniquely identifies the request. |
| organization\$1arn | The ARN of the WorkMail Organization to which the authenticated user belongs. |
| user\$1id | The ID of the authenticated user. |
| user | The username that the authentication was attempted with. |
| protocol | The protocol used, which can be: `AutoDiscover`, `EWS`, `IMAP`, `WindowsOutlook`, `ActiveSync`, `SMTP`, `WebMail`, `IncomingEmail`, or `OutgoingEmail`. |
| source\$1ip | The source IP address of the request. |
| user\$1agent | The user agent that made the request. |
| method | The auth method. Currently, only basic is supported. |
| auth\$1successful | Whether the auth attempt was successful. Can be true or false. |
| auth\$1failed\$1reason | The reason for auth failure. Present only if auth failed. |
| personal\$1access\$1token\$1id | The ID of the personal access token used for authentication. |
## Personal access token logs
A personal access token (PAT) event is generated for every attempt in creating or deleting a personal access token. Personal access token events provide information about whether users successfully create personal access tokens. The personal access token logs are useful for auditing end users creating and deleting their own PATs. User login with personal access tokens will generate events in the existing Authentication logs. For more information, see [Authentication logs ](https://docs.aws.amazon.com/workmail/latest/adminguide/monitoring-audit-logging.html#authentication-log).
| Field | Description |
| --- | --- |
| event\$1timestamp | When the event happened, in milliseconds since Unix epoch. |
| request\$1id | The ID that uniquely identifies the request. |
| organization\$1arn | The ARN of the WorkMail Organization to which the authenticated user belongs. |
| user\$1id | The ID of the authenticated user. |
| user | The username of the user who took this action. |
| protocol | The protocol used through the action took place, which can be: webapp |
| source\$1ip | The source IP address of the request. |
| user\$1agent | The user agent that made the request. |
| action | The action of the personal access token, which can be: create or delete. |
| name | The name of the personal access token. |
| expires\$1time | The date when the personal access token expires. |
| scopes | The scopes of the personal access token permissions on mailbox. |
## Availability provider logs
Availability provider events are generated for every availability request Amazon WorkMail does on your behalf to your configured availability provider. These events are useful for debugging your availability provider configuration.
| Field | Description |
| --- | --- |
| event\$1timestamp | When the event happened, in milliseconds since Unix epoch. |
| request\$1id | The ID that uniquely identifies the request. |
| organization\$1arn | The ARN of the WorkMail Organization to which the authenticated user belongs. |
| user\$1id | The ID of the authenticated user. |
| type | The type of availability provider being invoked, which can be: `EWS` or `LAMBDA`. |
| domain | The domain for which availability is obtained. |
| function\$1arn | The ARN of the invoked Lambda, if type is LAMBDA. Otherwise, this field is not present. |
| ews\$1endpoint | The EWS endpoint is type is EWS. Otherwise, this field is not present. |
| error\$1message | The message describing the cause of the failure. If the request was successful, this field is not present. |
| availability\$1event\$1successful | Whether the availability request was served successfully. |
# Using CloudWatch Insights with Amazon WorkMail
If you turned on email event logging in the Amazon WorkMail console or enabled audit logs delivery to CloudWatch Logs, you can use Amazon CloudWatch Logs Insights to query your event logs. For more information about turning on email event logging, see [Enabling email event logging](tracking.md). For more information about CloudWatch Logs Insights, see [Analyze log data with CloudWatch Logs Insights](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/AnalyzingLogData.html) in the *Amazon CloudWatch Logs User Guide*.
The following examples demonstrate how to query CloudWatch Logs for common email events. You run these queries in the CloudWatch console. For instructions about how to run these queries, see [Tutorial: Run and modify a sample query](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_AnalyzeLogData_RunSampleQuery.html) in the *Amazon CloudWatch Logs User Guide*.
**Example See why User B did not receive an email sent by User A.**
The following code example demonstrates how to query for an outgoing email sent by User A to User B, sorted by timestamp.
```
fields @timestamp, traceId
| sort @timestamp asc
| filter (event.from like /(?i)userA@example.com/
and event.eventName = "OUTGOING_EMAIL_SUBMITTED"
and event.recipients.0 like /(?i)userB@example.com/)
```
This returns the sent message and trace ID. Use the trace ID in the following code example to query the event logs for the sent message.
```
fields @timestamp, event.eventName
| sort @timestamp asc
| filter traceId = "$TRACEID"
```
This returns the email message ID and the email events. `OUTGOING_EMAIL_SENT` indicates that the email was sent. `OUTGOING_EMAIL_BOUNCED` indicates that the email bounced. To see whether the email was received, query using the message ID in the following code example.
```
fields @timestamp, event.eventName
| sort @timestamp asc
| filter event.messageId like "$MESSAGEID"
```
This should also return the received message, because it has the same message ID. Use the trace ID in the following code example to query for delivery.
```
fields @timestamp, event.eventName
| sort @timestamp asc
| filter traceId = "$TRACEID"
```
This returns the delivery action and any applicable rule actions.
**Example See all mail received from a user or domain**
The following code example demonstrates how to query for all mail received from a specified user.
```
fields @timestamp, event.eventName
| sort @timestamp asc
| filter (event.from like /(?i)user@example.com/ and event.eventName = "ORGANIZATION_EMAIL_RECEIVED")
```
The following code example demonstrates how to query for all mail received from a specified domain.
```
fields @timestamp, event.eventName
| sort @timestamp asc
| filter (event.from like "example.com" and event.eventName = "ORGANIZATION_EMAIL_RECEIVED")
```
**Example See who sent bounced emails**
The following code example demonstrates how to query for outgoing emails that bounced, and also returns the reasons for bouncing.
```
fields @timestamp, event.destination, event.reason
| sort @timestamp desc
| filter event.eventName = "OUTGOING_EMAIL_BOUNCED"
```
The following code example demonstrates how to query for incoming emails that bounced. It also returns the bounced recipients' email addresses and the reasons for bouncing.
```
fields @timestamp, event.bouncedRecipient.emailAddress, event.bouncedRecipient.reason, event.bouncedRecipient.status
| sort @timestamp desc
| filter event.eventName = "INCOMING_EMAIL_BOUNCED"
```
**Example See which domains are sending spam**
The following code example demonstrates how to query for recipients in your organization that are receiving spam.
```
stats count(*) as c by event.recipients.0
| filter (event.eventName = "ORGANIZATION_EMAIL_RECEIVED" and event.spamVerdict = "FAIL")
| sort c desc
```
The following code example demonstrates how to query for the sender of the spam emails.
```
fields @timestamp, event.recipients.0, event.sender, event.from
| sort @timestamp asc
| filter (event.spamVerdict = "FAIL")
```
**Example See why an email was sent to a recipient's spam folder**
The following code example demonstrates how to query for emails identified as spam, filtered by subject.
```
fields @timestamp, event.recipients.0, event.spamVerdict, event.spfVerdict, event.dkimVerdict, event.dmarcVerdict
| sort @timestamp asc
| filter event.subject like /(?i)$SUBJECT/ and event.eventName = "ORGANIZATION_EMAIL_RECEIVED"
```
You can also query by the email trace ID to see all events for the email.
**Example See emails that match email flow rules**
The following code example demonstrates how to query for emails that matched outbound email flow rules.
```
fields @timestamp, event.ruleName, event.ruleActions.0.action
| sort @timestamp desc
| filter event.ruleType = "OUTBOUND_RULE"
```
The following code example demonstrates how to query for emails that matched inbound email flow rules.
```
fields @timestamp, event.ruleName, event.ruleActions.0.action, event.ruleActions.0.recipients.0
| sort @timestamp desc
| filter event.ruleType = "INBOUND_RULE"
```
**Example See how many emails are received or sent by your organization**
The following code example demonstrates how to query for the number of emails received by each recipient in your organization.
```
stats count(*) as c by event.recipient
| filter event.eventName = "MAILBOX_EMAIL_DELIVERED"
| sort c desc
```
The following code example demonstrates how to query for the number of emails sent by each sender in your organization.
```
stats count(*) as c by event.from
| filter event.eventName = "OUTGOING_EMAIL_SUBMITTED"
| sort c desc
```
# Logging Amazon WorkMail API calls with AWS CloudTrail
Amazon WorkMail is integrated with AWS CloudTrail, a service that provides a record of actions taken by a user, role, or an AWS service in Amazon WorkMail. CloudTrail captures all API calls for Amazon WorkMail as events, including calls from the Amazon WorkMail console and from code calls to the Amazon WorkMail APIs. If you create a trail, you can enable continuous delivery of CloudTrail events to an Amazon S3 bucket, including events for Amazon WorkMail. If you don't configure a trail, you can still view the most recent events in the CloudTrail console in **Event history**. Using the information collected by CloudTrail, you can determine the request that was made to Amazon WorkMail, the IP address from which the request was made, who made the request, when it was made, and additional details.
To learn more about CloudTrail, see the [AWS CloudTrail User Guide](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/).
## Amazon WorkMail information in CloudTrail
CloudTrail is enabled on your AWS account when you create the account. When activity occurs in Amazon WorkMail, that activity is recorded in a CloudTrail event along with other AWS service events in **Event history**. You can view, search, and download recent events in your AWS account. For more information, see [Viewing events with CloudTrail event history](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/view-cloudtrail-events.html).
For an ongoing record of events in your AWS account, including events for Amazon WorkMail, you must create a trail. A trail enables CloudTrail to deliver log files to an Amazon S3 bucket. By default, when you create a trail in the console, the trail applies to all AWS Regions. The trail logs events from all Regions in the AWS partition and delivers the log files to the Amazon S3 bucket that you specify. Additionally, you can configure other AWS services to further analyze and act upon the event data collected in CloudTrail logs. For more information, see:
+ [Overview for creating a trail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-create-and-update-a-trail.html)
+ [CloudTrail supported services and integrations](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-aws-service-specific-topics.html#cloudtrail-aws-service-specific-topics-integrations)
+ [Configuring Amazon SNS notifications for CloudTrail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/getting_notifications_top_level.html)
+ [Receiving CloudTrail log files from multiple Regions](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/receive-cloudtrail-log-files-from-multiple-regions.html) and [Receiving CloudTrail log files from multiple accounts](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-receive-logs-from-multiple-accounts.html)
All Amazon WorkMail actions are logged by CloudTrail and are documented in the [Amazon WorkMail API Reference](https://docs.aws.amazon.com/workmail/latest/APIReference/Welcome.html). For example, calls to the `CreateUser`, `CreateAlias`, and `GetRawMessageContent` API operations generate entries in the CloudTrail log files.
Every event or log entry contains information about who generated the request. The identity information helps you determine the following:
+ Whether the request was made with root or IAM user credentials.
+ Whether the request was made with temporary security credentials for a role or federated user.
+ Whether the request was made by another AWS service.
For more information, see the [CloudTrail userIdentity element](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-event-reference-user-identity.html).
## Understanding Amazon WorkMail log file entries
A trail is a configuration that enables delivery of events as log files to an Amazon S3 bucket that you specify. CloudTrail log files contain one or more log entries. An event represents a single request from any source and includes information about the requested action, the date and time of the action, request parameters, and so on. CloudTrail log files aren't an ordered stack trace of the public API calls, so they don't appear in any specific order.
The following example shows a CloudTrail log entry that demonstrates the `CreateUser` action from the Amazon WorkMail API.
```
{
"eventVersion": "1.05",
"userIdentity": {
"type": "IAMUser",
"principalId": "AIDACKCEVSQ6C2EXAMPLE",
"arn": "arn:aws:iam::111111111111:user/WMSDK",
"accountId": "111111111111",
"accessKeyId": "AKIAIOSFODNN7EXAMPLE"
"userName": "WMSDK"
},
"eventTime": "2017-12-12T17:49:59Z",
"eventSource": "workmail.amazonaws.com",
"eventName": "CreateUser",
"awsRegion": "us-west-2",
"sourceIPAddress": "203.0.113.12",
"userAgent": "aws-sdk-java/1.11.205 Mac_OS_X/10.11.6 Java_HotSpot(TM)_64-Bit_Server_VM/25.151-b12 java/1.8.0_151",
"requestParameters": {
"name": "janedoe",
"displayName": "Jane Doe",
"organizationId": "m-5b1c980000EXAMPLE"
},
"responseElements": {
"userId": "a3a9176d-EXAMPLE"
},
"requestID": "dec81e4a-EXAMPLE",
"eventID": "9f2f09c5-EXAMPLE",
"eventType": "AwsApiCall",
"recipientAccountId": "111111111111"
}
```
The following example shows a CloudTrail log entry that demonstrates the `CreateAlias` action from the Amazon WorkMail API.
```
{
"eventVersion": "1.05",
"userIdentity": {
"type": "IAMUser",
"principalId": "AIDACKCEVSQ6C2EXAMPLE",
"arn": "arn:aws:iam::111111111111:user/WMSDK",
"accountId": "111111111111",
"accessKeyId": "AKIAIOSFODNN7EXAMPLE",
"userName": "WMSDK"
},
"eventTime": "2017-12-12T18:13:44Z",
"eventSource": "workmail.amazonaws.com",
"eventName": "CreateAlias",
"awsRegion": "us-west-2",
"sourceIPAddress": "203.0.113.12",
"userAgent": "aws-sdk-java/1.11.205 Mac_OS_X/10.11.6 Java_HotSpot(TM)_64-Bit_Server_VM/25.151-b12 java/1.8.0_151",
"requestParameters": {
"alias": "aliasjamesdoe@testofconsole.awsapps.com",
"organizationId": "m-5b1c980000EXAMPLE"
"entityId": "a3a9176d-EXAMPLE"
},
"responseElements": null,
"requestID": "dec81e4a-EXAMPLE",
"eventID": "9f2f09c5-EXAMPLE",
"eventType": "AwsApiCall",
"recipientAccountId": "111111111111"
}
```
The following example shows a CloudTrail log entry that demonstrates the `GetRawMessageContent` action from the Amazon WorkMail Message Flow API.
```
{
"eventVersion": "1.05",
"userIdentity": {
"type": "IAMUser",
"principalId": "AIDACKCEVSQ6C2EXAMPLE",
"arn": "arn:aws:iam::111111111111:user/WMSDK",
"accountId": "111111111111",
"accessKeyId": "AKIAIOSFODNN7EXAMPLE",
"userName": "WMSDK"
},
"eventTime": "2017-12-12T18:13:44Z",
"eventSource": "workmailMessageFlow.amazonaws.com",
"eventName": "GetRawMessageContent",
"awsRegion": "us-west-2",
"sourceIPAddress": "203.0.113.12",
"userAgent": "aws-sdk-java/1.11.205 Mac_OS_X/10.11.6 Java_HotSpot(TM)_64-Bit_Server_VM/25.151-b12 java/1.8.0_151",
"requestParameters": {
"messageId": "123A4A5A-67B8-90C1-D23E-45FG67H890J1"
},
"responseElements": null,
"requestID": "dec81e4a-EXAMPLE",
"eventID": "9f2f09c5-EXAMPLE",
"readOnly": true,
"eventType": "AwsApiCall",
"recipientAccountId": "111111111111"
}
```
# Enabling email event logging
You enable email event logging in the Amazon WorkMail console in order to track email messages for your organization. Email event logging uses an AWS Identity and Access Management service-linked role (SLR) to grant permissions to publish the email event logs to Amazon CloudWatch. For more information about IAM service-linked roles, see [Using service-linked roles for Amazon WorkMail](using-service-linked-roles.md).
In the CloudWatch event logs, you can use CloudWatch search tools and metrics to track messages and troubleshoot email issues. For more information about the event logs that Amazon WorkMail sends to CloudWatch, see [Monitoring Amazon WorkMail email event logs](cw-events.md). For more information about CloudWatch Logs, see the [Amazon CloudWatch Logs User Guide](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/).
**Topics**
+ [Turning on email event logging](#enable-tracking)
+ [Creating a custom log group and IAM role for email event logging](#custom-tracking-role)
+ [Turning off email event logging](#turn-off-tracking)
+ [Cross-service confused deputy prevention](#cross-service-confused-deputy-prevention)
## Turning on email event logging
The following occurs when you turn on email event logging using the default settings, Amazon WorkMail:
+ Creates an AWS Identity and Access Management service-linked role – `AmazonWorkMailEvents`.
+ Creates a CloudWatch log group – `/aws/workmail/emailevents/organization-alias`.
+ Sets CloudWatch log retention to 30 days.
**To turn on email event logging**
1. Open the Amazon WorkMail console at [https://console.aws.amazon.com/workmail/](https://console.aws.amazon.com/workmail/).
If necessary, change the AWS Region. In the bar at the top of the console window, open the **Select a Region** list and choose a Region. For more information, see [Regions and endpoints](http://docs.aws.amazon.com/general/latest/gr/index.html?rande.html) in the *Amazon Web Services General Reference*.
1. In the navigation pane, choose **Organizations**, then choose the name of your organization.
1. In the navigation pane, choose **Logging settings**.
1. Choose the **Email flow log settings** tab.
1. In the **Email flow log settings** section, choose **Edit**.
1. Move the **Enable mail events** slider to the **on** position.
1. Do one of the following:
+ (Recommended) Choose **Use default settings**.
+ (Optional) Clear the **Use default settings**, and select a **Destination Log Group** and **IAM Role** from the lists that appear.
**Note**
Choose this option only if you have already created a log group and custom IAM role using the AWS CLI. For more information, see [Creating a custom log group and IAM role for email event logging](#custom-tracking-role).
1. Select **I authorize Amazon WorkMail to publish logs in my account using this configuration**.
1. Choose **Save**.
## Creating a custom log group and IAM role for email event logging
We recommend using the default settings when enabling email event logging for Amazon WorkMail. If you require a custom monitoring configuration, you can use the AWS CLI to create a dedicated log group and custom IAM role for email event logging.
**To create a custom log group and IAM role for email event logging**
1. Use the following AWS CLI command to create a log group in the same AWS Region as your Amazon WorkMail organization. For more information, see [create-log-group](https://docs.aws.amazon.com/cli/latest/reference/logs/create-log-group.html) in the *AWS CLI Command Reference*.
```
aws –-region us-east-1 logs create-log-group --log-group-name workmail-monitoring
```
1. Create a file containing the following policy:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "events.workmail.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
------
1. Use the following AWS CLI command to create an IAM role and attach this file as the role policy document. For more information, see [create-role](https://docs.aws.amazon.com/cli/latest/reference/iam/create-role.html) in the *AWS CLI Command Reference*.
```
aws iam create-role --role-name workmail-monitoring-role --assume-role-policy-document file://trustpolicyforworkmail.json
```
**Note**
If you're a `WorkMailFullAccess` managed policy user, you must include the term `workmail` in the role name. This managed policy only allows you to configure email event logging using roles with `workmail` in the name. For more information, see [Granting a user permissions to pass a role to an AWS service](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_passrole.html) in the *IAM User Guide*.
1. Create a file containing the policy for the IAM role that you created in the previous step. At minimum, the policy must grant permissions to the role to create log streams and put log events into the log group that you created in step 1.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"logs:CreateLogStream",
"logs:PutLogEvents"
],
"Resource": "arn:aws:logs:us-east-1:111122223333:log-group:example-log-group*"
}
]
}
```
------
1. Use the following AWS CLI command to attach the policy file to the IAM role. For more information, see [put-role-policy](https://docs.aws.amazon.com/cli/latest/reference/iam/put-role-policy.html) in the *AWS CLI Command Reference*.
```
aws iam put-role-policy --role-name workmail-monitoring-role --policy-name workmail-permissions --policy-document file://rolepolicy.json
```
## Turning off email event logging
Turn off email event logging from the Amazon WorkMail console. If you no longer need to use email event logging, we recommend that you delete the related CloudWatch log group and service-linked role as well. For more information, see [Deleting a service-linked role for Amazon WorkMail](using-service-linked-roles.md#delete-slr).
**To turn off email event logging**
1. Open the Amazon WorkMail console at [https://console.aws.amazon.com/workmail/](https://console.aws.amazon.com/workmail/).
If necessary, change the AWS Region. In the bar at the top of the console window, open the **Select a Region** list and choose a Region. For more information, see [Regions and endpoints](http://docs.aws.amazon.com/general/latest/gr/index.html?rande.html) in the *Amazon Web Services General Reference*.
1. In the navigation pane, choose **Organizations**, then choose the name of your organization.
1. In the navigation pane, choose **Monitoring**.
1. In the **Log settings** section, choose **Edit**.
1. Move the **Enable mail events** slider to the off position.
1. Choose **Save**.
## Cross-service confused deputy prevention
The confused deputy problem is a security issue where an entity that doesn't have permission to perform an action can coerce a more-privileged entity to perform the action. In AWS, cross-service impersonation can result in the confused deputy problem. Cross-service impersonation can occur when one service (the *calling service*) calls another service (the *called service*).
The calling service can be manipulated to use its permissions to act on another customer’s resources it wouldn’t otherwise have permission to access.
To prevent this, AWS provides tools that help you protect your data for all services with service principals that have been given access to resources in your account.
We recommend using the [https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourcearn](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourcearn) and [https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourceaccount](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourceaccount) global condition context keys in resource policies to limit the permissions that CloudWatch Logs and Amazon S3 give to the services that are generating logs. If you use both global condition context keys, the values must use the same account ID when used in the same policy statement.
The values of `aws:SourceArn` must be the ARNs of the delivery sources that are generating logs.
The most effective way to protect against the confused deputy problem is to use the `aws:SourceArn` global condition context key with the full ARN of the resource. If you don't know the full ARN of the resource or if you're specifying multiple resources, use the `aws:SourceArn` global context condition key with wildcards (`*`) for the unknown portions of the ARN.
# Enabling audit logging
You can use audit logs to capture detailed information about your Amazon WorkMail organization usage. The audit logs can be used to monitor user’s access to mailboxes, audit for suspicious activity, and debug access control and availability provider configurations.
**Note**
The *AmazonWorkMailFullAccess* managed policy does not include all the required permissions to manage log deliveries. If you are using this policy to manage WorkMail, make sure the principal (for example, the assumed role) used to configure log deliveries also has all the required permissions.
Amazon WorkMail supports three delivery destinations for audit logs: CloudWatch Logs, Amazon S3, and Amazon Data Firehose. For more information, see [Logging that requires additional permissions [V2]](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/AWS-logs-and-resource-policy.html) in the *[Amazon CloudWatch Logs User Guide](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/)*.
In addition to the permissions listed under [Logging that requires additional permissions [V2]](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/AWS-logs-and-resource-policy.html), Amazon WorkMail requires an additional permission to configure log delivery: `workmail:AllowVendedLogDeliveryForResource`.
A working log delivery consists of three elements:
+ *DeliverySource*, a logical object that represents the resource or resources that send the logs. For Amazon WorkMail, it's the Amazon WorkMail Organization.
+ A *DeliveryDestination*, which is a logical object that represents the actual delivery destination.
+ A *Delivery*, which connects a delivery source to delivery destination.
To configure log delivery between Amazon WorkMail and a destination, you can do the following:
+ Create a delivery source with [PutDeliverySource](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutDeliverySource.html).
+ Create a delivery destination with [PutDeliveryDestination](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutDeliveryDestination.html).
+ If you're delivering logs cross-account, you must use [PutDeliveryDestinationPolicy](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutDeliveryDestinationPolicy.html) in the destination account to assign an IAM policy to the destination. This policy authorizes creating a delivery from the delivery source in account A to the delivery destination in account B.
+ Create a delivery by pairing exactly one delivery source and one delivery destination by using [CreateDelivery](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_CreateDelivery.html).
The following sections provide the details of the permissions that you must have when you're signed in to set up log delivery to each type of destination. These permissions can be granted to an IAM role that you're signed in with.
**Important**
It's your responsibility to remove log delivery resources after deleting the log-generating resource.
To remove log delivery resources after deleting the log-generating resource, follow these steps.
1. Delete the *Delivery* by using the [DeleteDelivery](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_DeleteDelivery.html) operation.
1. Delete the *DeliverySource* by using the [DeleteDeliverySource](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_DeleteDeliverySource.html) operation.
1. If the *DeliveryDestination* associated with the *DeliverySource* that you just deleted is used only for this specific *DeliverySource*, then you can remove it by using the [DeleteDeliveryDestinations](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_DescribeDeliveryDestinations.html) operation.
## Configuring audit logging using the Amazon WorkMail console
You can configure audit logging in the Amazon WorkMail console:
1. Open the Amazon WorkMail console at [https://console.aws.amazon.com/workmail/](https://console.aws.amazon.com/workmail/).
If necessary, change the AWS Region. In the bar at the top of the console window, open the **Select a Region** list and select a Region. For more information, see [Regions and endpoints](http://docs.aws.amazon.com/general/latest/gr/index.html?rande.html) in the *Amazon Web Services General Reference*.
1. In the navigation pane, choose **Organizations**, then choose the name of your organization.
1. Choose **Logging settings**.
1. Choose the **Audit log settings** tab.
1. Configure deliveries for the required log type using the appropriate widget.
1. Choose **Save**.
## Logs sent to CloudWatch Logs
**User permissions**
To enable sending logs to CloudWatch Logs, you must be signed in with the following permissions.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "ReadWriteAccessForLogDeliveryActions",
"Effect": "Allow",
"Action": [
"logs:GetDelivery",
"logs:GetDeliverySource",
"logs:PutDeliveryDestination",
"logs:GetDeliveryDestinationPolicy",
"logs:DeleteDeliverySource",
"logs:PutDeliveryDestinationPolicy",
"logs:CreateDelivery",
"logs:GetDeliveryDestination",
"logs:PutDeliverySource",
"logs:DeleteDeliveryDestination",
"logs:DeleteDeliveryDestinationPolicy",
"logs:DeleteDelivery"
],
"Resource": [
"arn:aws:logs:us-east-1:111122223333:delivery:*",
"arn:aws:logs:us-east-1:111122223333:delivery-source:*",
"arn:aws:logs:us-east-1:111122223333:delivery-destination:*"
]
},
{
"Sid": "ListAccessForLogDeliveryActions",
"Effect": "Allow",
"Action": [
"logs:DescribeDeliveryDestinations",
"logs:DescribeDeliverySources",
"logs:DescribeDeliveries",
"logs:DescribeLogGroups"
],
"Resource": "*"
},
{
"Sid": "AllowUpdatesToResourcePolicyCWL",
"Effect": "Allow",
"Action": [
"logs:PutResourcePolicy",
"logs:DescribeResourcePolicies",
"logs:DescribeLogGroups"
],
"Resource": [
"arn:aws:logs:us-east-1:111122223333:*"
]
},
{
"Sid": "AllowLogDeliveryForWorkMail",
"Effect": "Allow",
"Action": [
"workmail:AllowVendedLogDeliveryForResource"
],
"Resource": [
"arn:aws:workmail:us-east-1:111122223333:organization/organization-id"
]
}
]
}
```
------
**Log group resource policy**
The log group where the logs are being sent must have a resource policy that includes certain permissions. If the log group currently does not have a resource policy, and the user setting up the logging has the `logs:PutResourcePolicy`, `logs:DescribeResourcePolicies`, and `logs:DescribeLogGroups` permissions for the log group, then AWS automatically creates the following policy for it when you begin sending the logs to CloudWatch Logs.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AWSLogDeliveryWrite20150319",
"Effect": "Allow",
"Principal": {
"Service": [
"delivery.logs.amazonaws.com"
]
},
"Action": [
"logs:CreateLogStream",
"logs:PutLogEvents"
],
"Resource": [
"arn:aws:logs:us-east-1:111122223333:log-group:my-log-group:log-stream:*"
],
"Condition": {
"StringEquals": {
"aws:SourceAccount": [
"111122223333"
]
},
"ArnLike": {
"aws:SourceArn": [
"arn:aws:logs:us-east-1:111122223333:*"
]
}
}
}
]
}
```
------
**Log group resource policy size limit considerations**
These services must list each log group that they're sending logs to in the resource policy. CloudWatch Logs resource policies are limited to 5,120 characters. A service that sends logs to a large number of log groups might run into this limit.
To mitigate this, CloudWatch Logs monitors the size of resource policies used by the service that's sending logs. When it detects that a policy approaches the size limit of 5,120 characters, CloudWatch Logs automatically enables `/aws/vendedlogs/*` in the resource policy for that service. You can then start using log groups with names that start with `/aws/vendedlogs/` as the destinations for logs from these services.
## Logs sent to Amazon S3
**User permissions**
To enable sending logs to Amazon S3, you must be signed in with the following permissions.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "ReadWriteAccessForLogDeliveryActions",
"Effect": "Allow",
"Action": [
"logs:GetDelivery",
"logs:GetDeliverySource",
"logs:PutDeliveryDestination",
"logs:GetDeliveryDestinationPolicy",
"logs:DeleteDeliverySource",
"logs:PutDeliveryDestinationPolicy",
"logs:CreateDelivery",
"logs:GetDeliveryDestination",
"logs:PutDeliverySource",
"logs:DeleteDeliveryDestination",
"logs:DeleteDeliveryDestinationPolicy",
"logs:DeleteDelivery"
],
"Resource": [
"arn:aws:logs:us-east-1:111122223333:delivery:*",
"arn:aws:logs:us-east-1:111122223333:delivery-source:*",
"arn:aws:logs:us-east-1:111122223333:delivery-destination:*"
]
},
{
"Sid": "ListAccessForLogDeliveryActions",
"Effect": "Allow",
"Action": [
"logs:DescribeDeliveryDestinations",
"logs:DescribeDeliverySources",
"logs:DescribeDeliveries",
"logs:DescribeLogGroups"
],
"Resource": "*"
},
{
"Sid": "AllowUpdatesToResourcePolicyS3",
"Effect": "Allow",
"Action": [
"s3:PutBucketPolicy",
"s3:GetBucketPolicy"
],
"Resource": "arn:aws:s3:::bucket-name"
},
{
"Sid": "AllowLogDeliveryForWorkMail",
"Effect": "Allow",
"Action": [
"workmail:AllowVendedLogDeliveryForResource"
],
"Resource": [
"arn:aws:workmail:us-east-1:111122223333:organization/organization-id"
]
}
]
}
```
------
The S3 bucket where the logs are being sent must have a resource policy that includes certain permissions. If the bucket currently doesn't have a resource policy and the user setting up the logging has the `S3:GetBucketPolicy` and `S3:PutBucketPolicy` permissions for the bucket, then AWS automatically creates the following policy for it when you begin sending the logs to Amazon S3.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Id": "AWSLogDeliveryWrite20150319",
"Statement": [
{
"Sid": "AWSLogDeliveryAclCheck",
"Effect": "Allow",
"Principal": {
"Service": "delivery.logs.amazonaws.com"
},
"Action": "s3:GetBucketAcl",
"Resource": "arn:aws:s3:::my-bucket",
"Condition": {
"StringEquals": {
"aws:SourceAccount": [
"123456789012"
]
},
"ArnLike": {
"aws:SourceArn": [
"arn:aws:logs:us-east-1:111122223333:delivery-source:*"
]
}
}
},
{
"Sid": "AWSLogDeliveryWrite",
"Effect": "Allow",
"Principal": {
"Service": "delivery.logs.amazonaws.com"
},
"Action": "s3:PutObject",
"Resource": "arn:aws:s3:::my-bucket/AWSLogs/111122223333/*",
"Condition": {
"StringEquals": {
"s3:x-amz-acl": "bucket-owner-full-control",
"aws:SourceAccount": [
"123456789012"
]
},
"ArnLike": {
"aws:SourceArn": [
"arn:aws:logs:us-east-1:111122223333:delivery-source:*"
]
}
}
}
]
}
```
------
In the previous policy, for `aws:SourceAccount`, specify the list of account IDs for which logs are being delivered to this bucket. For `aws:SourceArn`, specify the list of ARNs of the resource that generates the logs, in the form `arn:aws:logs:source-region:source-account-id:*`.
If the bucket has a resource policy, but that policy doesn't contain the statement shown in the previous policy, and the user setting up the logging has the `S3:GetBucketPolicy` and `S3:PutBucketPolicy` permissions for the bucket, that statement is appended to the bucket's resource policy.
**Note**
In some cases, you might see `AccessDenied` errors in AWS CloudTrail if the `s3:ListBucket` permission hasn't been granted to `delivery.logs.amazonaws.com`. To avoid these errors in your CloudTrail logs, you must grant the `s3:ListBucket` permission to `delivery.logs.amazonaws.com`. You must also include the `Condition` parameters shown with the `s3:GetBucketAcl` permission set in the preceding bucket policy. To streamline this, instead of creating a new `Statement`, you can directly update the `AWSLogDeliveryAclCheck` to be `“Action”: [“s3:GetBucketAcl”, “s3:ListBucket”]`.
### Amazon S3 bucket server-side encryption
You can protect the data in your Amazon S3 bucket by enabling either server-side encryption with Amazon S3-managed keys (SSE-S3) or server-side encryption with an AWS KMS key stored in AWS Key Management Service (SSE-KMS). For more information, see [ Protecting data using server-side encryption](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html).
If you choose SSE-S3, no additional configuration is required. Amazon S3 handles the encryption key.
**Warning**
If you choose SSE-KMS, you must use a customer managed key, because using an AWS managed key isn't supported for this scenario. If you set up encryption using an AWS managed key, the logs will be delivered in an unreadable format.
When you use a customer managed AWS KMS key, you can specify the Amazon Resource Name (ARN) of the customer managed key when you enable bucket encryption. Add the following to the key policy for your customer managed key (not to the bucket policy for your S3 bucket), so that the log delivery account can write to your S3 bucket.
If you choose SSE-KMS, you must use a customer managed key, because using an AWS managed key isn't supported for this scenario. When you use a customer managed AWS KMS key, you can specify the Amazon Resource Name (ARN) of the customer managed key when you enable bucket encryption. Add the following to the key policy for your customer managed key (not to the bucket policy for your S3 bucket), so that the log delivery account can write to your S3 bucket.
```
{
"Sid":"Allow Logs Delivery to use the key",
"Effect":"Allow",
"Principal":{
"Service":[
"delivery.logs.amazonaws.com"
]
},
"Action":[
"kms:Encrypt",
"kms:Decrypt",
"kms:ReEncrypt*",
"kms:GenerateDataKey*",
"kms:DescribeKey"
],
"Resource":"*",
"Condition":{
"StringEquals":{
"aws:SourceAccount":[
"account-id"
]
},
"ArnLike":{
"aws:SourceArn":[
"arn:aws:logs:region:account-id:delivery-source:*"
]
}
}
}
```
For `aws:SourceAccount`, specify the list of account IDs for which logs are being delivered to this bucket. For `aws:SourceArn`, specify the list of ARNs of the resource that generates the logs, in the form `arn:aws:logs:source-region:source-account-id:*`.
## Logs sent to Firehose
**User permissions**
To enable sending logs to Firehose, you must be signed in with the following permissions.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "ReadWriteAccessForLogDeliveryActions",
"Effect": "Allow",
"Action": [
"logs:GetDelivery",
"logs:GetDeliverySource",
"logs:PutDeliveryDestination",
"logs:GetDeliveryDestinationPolicy",
"logs:DeleteDeliverySource",
"logs:PutDeliveryDestinationPolicy",
"logs:CreateDelivery",
"logs:GetDeliveryDestination",
"logs:PutDeliverySource",
"logs:DeleteDeliveryDestination",
"logs:DeleteDeliveryDestinationPolicy",
"logs:DeleteDelivery"
],
"Resource": [
"arn:aws:logs:us-east-1:111122223333:delivery:*",
"arn:aws:logs:us-east-1:111122223333:delivery-source:*",
"arn:aws:logs:us-east-1:111122223333:delivery-destination:*"
]
},
{
"Sid": "ListAccessForLogDeliveryActions",
"Effect": "Allow",
"Action": [
"logs:DescribeDeliveryDestinations",
"logs:DescribeDeliverySources",
"logs:DescribeDeliveries",
"logs:DescribeLogGroups"
],
"Resource": "*"
},
{
"Sid": "AllowUpdatesToResourcePolicyFH",
"Effect": "Allow",
"Action": [
"firehose:TagDeliveryStream"
],
"Resource": [
"arn:aws:firehose:us-east-1:111122223333:deliverystream/*"
]
},
{
"Sid": "CreateServiceLinkedRole",
"Effect": "Allow",
"Action": [
"iam:CreateServiceLinkedRole"
],
"Resource": "arn:aws:iam::111122223333:role/aws-service-role/delivery.logs.amazonaws.com/AWSServiceRoleForLogDelivery"
},
{
"Sid": "AllowLogDeliveryForWorkMail",
"Effect": "Allow",
"Action": [
"workmail:AllowVendedLogDeliveryForResource"
],
"Resource": [
"arn:aws:workmail:us-east-1:111122223333:organization/organization-id"
]
}
]
}
```
------
**IAM roles used for resource permissions**
Because Firehose doesn't use resource policies, AWS uses IAM roles when setting up these logs to be sent to Firehose. AWS creates a service-linked role named **AWSServiceRoleForLogDelivery**. This service-linked role includes the following permissions.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": [
"firehose:PutRecord",
"firehose:PutRecordBatch",
"firehose:ListTagsForDeliveryStream"
],
"Resource": "arn:aws:firehose:us-east-1:111122223333:deliverystream/workmail-*",
"Condition": {
"StringEquals": {
"aws:ResourceTag/LogDeliveryEnabled": "true"
}
},
"Effect": "Allow"
}
]
}
```
------
This service-linked role grants permission for all Firehose delivery streams that have the `LogDeliveryEnabled` tag set to `true`. AWS gives this tag to the destination delivery stream when you set up the logging.
This service-linked role also has a trust policy that allows the `delivery.logs.amazonaws.com` service principal to assume the needed service-linked role. That trust policy is as follows:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "delivery.logs.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
------
## Console-specific permissions
In addition to the permissions listed in the previous sections, if you're setting up log delivery using the console instead of the APIs, you also need the following permissions:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AllowLogDeliveryActions",
"Effect": "Allow",
"Action": [
"firehose:DescribeDeliveryStream",
"s3:ListBucket",
"s3:GetBucketLocation"
],
"Resource": [
"arn:aws:logs:us-east-1:111122223333:log-group:*",
"arn:aws:firehose:us-east-1:111122223333:deliverystream/*",
"arn:aws:s3:::*"
]
},
{
"Sid": "ListAccessForDeliveryDestinations",
"Effect": "Allow",
"Action": [
"logs:DescribeLogGroups",
"firehose:ListDeliveryStreams",
"s3:ListAllMyBuckets"
],
"Resource": "*"
}
]
}
```
------