# Monitoring SES events using Amazon EventBridge EventBridge is a serverless service that uses events to connect application components together, making it easier for you to build scalable event-driven applications. Event-driven architecture is a style of building loosely-coupled software systems that work together by emitting and responding to events. Events are JSON-formatted messages that typically represent a change in a resource or environment, or other management event. Certain SES features will generate and send events that you define when creating an event destination to the EventBridge default event bus. An event bus is a router that receives events and delivers them to zero or more destinations, or *targets*. Rules you associate with the event bus evaluate events as they arrive. Each rule checks whether an event matches the rule's pattern. If the event does match, EventBridge sends the event to the specified targets. SES sends events to EventBridge when a feature has a state change or status update. You can use EventBridge rules to route events to your defined targets. These events will be delivered on a best-effort basis, and they might be delivered out of order. **Topics** + [SES events](#supported-events) + [SES events schema reference](#eventbridge-events) + [Using EventBridge with SES events](#eventbridge-enable-event-notifications) + [Additional EventBridge resources](#eventbridge-additonal-resources) ## SES events The following events are generated by SES features and sent to the default event bus in EventBridge. For more information, including detail data for each event type, see [SES events schema reference](#eventbridge-events). **Virtual Deliverability Manager advisor events** | Event type | Description | | --- | --- | | Advisor Recommendation Status Open | An event generated whenever a new recommendation is opened in the Virtual Deliverability Manager advisor. | | Advisor Recommendation Status Resolved | An event generated whenever a recommendation is resolved in the Virtual Deliverability Manager advisor. | **SES email sending events** | Event type | Description | | --- | --- | | Email Bounced | A *hard bounce* that the recipient's mail server permanently rejected the email. (*Soft bounces* are only included when SES fails to deliver the email after retrying for a period of time.) | | Email Clicked | The recipient clicked one or more links in the email. | | Email Complaint Received | The email was successfully delivered to the recipient’s mail server, but the recipient marked it as spam. | | Email Delivered | SES successfully delivered the email to the recipient's mail server. | | Email Delivery Delayed | The email couldn't be delivered to the recipient’s mail server because a temporary issue occurred. Delivery delays can occur, for example, when the recipient's inbox is full, or when the receiving email server experiences a transient issue. | | Email Opened | The recipient received the message and opened it in their email client. | | Email Rejected | SES accepted the email, but determined that it contained a virus and didn’t attempt to deliver it to the recipient’s mail server. | | Email Rendering Failed | The email wasn't sent because of a template rendering issue. This event type can occur when template data is missing, or when there is a mismatch between template parameters and data. (This event type only occurs when you send email using the [https://docs.aws.amazon.com/ses/latest/APIReference/API_SendTemplatedEmail.html](https://docs.aws.amazon.com/ses/latest/APIReference/API_SendTemplatedEmail.html) or [https://docs.aws.amazon.com/ses/latest/APIReference/API_SendBulkTemplatedEmail.html](https://docs.aws.amazon.com/ses/latest/APIReference/API_SendBulkTemplatedEmail.html) API operations.) | | Email Sent | The send request was successful and SES will attempt to deliver the message to the recipient’s mail server. (If account-level or global suppression is being used, SES will still count it as a send, but delivery is suppressed.) | | Email Subscribed | The email was successfully delivered, but the recipient updated the subscription preferences by clicking `List-Unsubscribe` in the email header or the `Unsubscribe` link in the footer. | ## SES events schema reference All events from AWS services have a common set of fields containing metadata about the event, such as the AWS service that is the source of the event, the time the event was generated, the account and region in which the event took place, and others. For definitions of these general fields, see [Event structure reference](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-events-structure.html) in the *EventBridge User Guide*. In addition, each event has a `detail` field that contains data specific to that particular event. The reference below defines the detail fields for the various SES events. When using EventBridge to select and manage SES events, it's useful to keep the following in mind: + The `source` field for all events from SES is set to `aws.ses`. + The `detail-type` field specifies the event type. See the event type table in [SES events](#supported-events). + The `detail` field contains the data that is specific to that particular event. For some event types, such as those for Virtual Deliverability Manager, the detail field is a rather simplistic data string that is populated from a finite set of static values. Conversely, the detail field for email sending events is more complex as it can consist of many detail sub-fields which are a combination of both static and dynamic values such as the timestamp of when an email was sent, the recipient address, and many other email attributes. **Topics** + [Virtual Deliverability Manager advisor status schema](#schema-resource-status-event-vdm) + [SES email sending status schema](#schema-resource-status-event-email-sending) ### Virtual Deliverability Manager advisor status schema The following schema reference defines the fields specific to Virtual Deliverability Manager advisor status events. Definitions for the general fields that appear in all event schemas (such as `version`, `id`, `account`, and others) can be found in [Event structure reference](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-events-structure.html) in the *EventBridge User Guide*. The `source` and `detail-type` fields are included in the reference below because they contain SES-specific values for SES events. `source` Identifies the service that generated the event. For SES events, this value is `aws.ses`. `detail-type` Identifies the type of event. The values for this field are listed in the *Virtual Deliverability Manager advisor events* table in [SES events](#supported-events). `detail` A JSON object that contains information about the event. The service generating the event determines the content of this field. The values for this field can be: + `DKIM verification is not enabled.` + `DKIM verification has failed.` + `DKIM signing key length is below 2048 bits.` + `DMARC configuration was not found.` + `DMARC configuration could not be parsed.` + `DKIM record was not found.` + `DKIM record is not aligned.` + `MAIL FROM record is not aligned.` + `SPF record was not found.` + `SPF record for Amazon SES was not found.` + `SPF all qualifier is missing.` + `An SPF configuration issue was found.` + `BIMI record not found or configured without default selector.` + `BIMI has malformed TXT record.` **Example: Virtual Deliverability Manager advisor status event** The following is an example Virtual Deliverability Manager advisor status event for the event type `Advisor Recommendation Status Open`. The detail event value in this example is `SPF record was not found.`. ``` { "version": "0", "id": "abcd9999-ef33-0123-90ab-abcdef666666", "detail-type": "Advisor Recommendation Status Open", "source": "aws.ses", "account": "012345678901", "time": "2023-11-15T17:00:59Z", "region": "us-east-1", "resources": [ "arn:aws:ses:us-east-1:012345678901:identity/vdm.events-publishing.cajun.syster-games.example.com" ], "detail": { "version": "1.0.0", "data": "SPF record was not found." } } ``` ### SES email sending status schema The following schema reference defines the fields specific to SES email sending status events. Definitions for the general fields that appear in all event schemas (such as `version`, `id`, `account`, and others) can be found in [Event structure reference](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-events-structure.html) in the *EventBridge User Guide*. The `source` and `detail-type` fields are included in the reference below because they contain SES-specific values for SES events. `source` Identifies the service that generated the event. For SES events, this value is `aws.ses`. `detail-type` Identifies the type of event. The values for this field are listed in the *SES email sending events* table in [SES events](#supported-events). `detail` A JSON object that contains information about the event. The service generating the event determines the content of this field. All of the possible values for this field cannot be listed here because they are comprised of static and dynamic values that are generated by each unique email that is sent at any given moment. However, an example is provided to give you an idea of the type data that this field can contain. *Example detail data for all of the email sending event types can be found using the EventBridge Sandbox, see [Specify a sample event in EventBridge](#event-pattern-sandbox-sample).* An example of detail data generated for the SES email sending event `Email Rendering Failed`: ``` ..., "detail": { "eventType": "Rendering Failure", "mail": { "timestamp": "2018-01-22T18:43:06.197Z", "source": "sender@example.com", "sourceArn": "arn:aws:ses:us-east-1:123456789012:identity/sender@example.com", "sendingAccountId": "123456789012", "messageId": "EXAMPLE7c191be45-e9aedb9a-02f9-4d12-a87d-dd0099a07f8a-000000", "destination": ["recipient@example.com"], "headersTruncated": false, "tags": { "ses:configuration-set": ["ConfigSet"] } }, "failure": { "errorMessage": "Attribute 'attributeName' is not present in the rendering data.", "templateName": "MyTemplate" } } ``` **Example: Email sending status event** The following is an example of the full email sending status event for the event type `Email Rendering Failed`. The detail event value in this example is a combination of static and dynamic values based on the email sending event for a specific email. ``` { "version": "0", "id": "12a18625-3328-fafd-2809-a5e16004f112", "detail-type": "Email Rendering Failed", "source": "aws.ses", "account": "123456789012", "time": "2023-07-17T16:48:05Z", "region": "us-east-1", "resources": ["arn:aws:ses:us-east-1:123456789012:identity/example.com"], "detail": { "eventType": "Rendering Failure", "mail": { "timestamp": "2018-01-22T18:43:06.197Z", "source": "sender@example.com", "sourceArn": "arn:aws:ses:us-east-1:123456789012:identity/sender@example.com", "sendingAccountId": "123456789012", "messageId": "EXAMPLE7c191be45-e9aedb9a-02f9-4d12-a87d-dd0099a07f8a-000000", "destination": ["recipient@example.com"], "headersTruncated": false, "tags": { "ses:configuration-set": ["ConfigSet"] } }, "failure": { "errorMessage": "Attribute 'attributeName' is not present in the rendering data.", "templateName": "MyTemplate" } } } ``` ## Using EventBridge with SES events By default, SES sends events to the EventBridge default event bus. You can create rules on the default event bus to identify specific events for EventBridge to send to one or more specified targets. Each rule contains an *event pattern* that EventBridge uses to match events as they arrive on the event bus. If an event matches the event pattern for a given rule, EventBridge sends the event to the target specified in the rule. In EventBridge, defining an event pattern is typically part of the larger process of creating a new rule or editing an existing one. To learn how to create EventBridge rules, see [Creating Amazon EventBridge rules that react to events](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-create-rule.html) in the *EventBridge User Guide*. By using the Sandbox feature in EventBridge, you can quickly define an event pattern and use a sample event to confirm the pattern matches the desired events, without having to first create or edit a rule. For detailed instructions on using the Sandbox, see [Testing an event pattern using the EventBridge Sandbox](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-event-pattern-sandbox.html) in the *EventBridge User Guide*. ### Specify a SES sample event in the EventBridge Sandbox You can select sample events for SES events to use them in testing the event patterns you create. **To specify a SES sample event in the EventBridge Sandbox** 1. Open the Amazon EventBridge console at [https://console.aws.amazon.com/events/](https://console.aws.amazon.com/events/). 1. In the navigation pane, choose **Developer resources,** then select **Sandbox**, and on the **Sandbox** page choose the **Event pattern** tab. 1. For **Event source**, choose **AWS events or EventBridge partner events**. 1. In the **Sample event** section, for **Sample event type**, select **AWS events**. 1. For **Sample events**, scroll down to **SES** and then select the desired SES event. EventBridge displays a sample event, along with all of its detail data, for the event type. You can then use this event to test the event pattern you create in the **Event pattern** section, or use it as the basis for creating your own sample events for pattern testing covered in the following section. ### Creating and testing event patterns for SES events Once you've selected a sample event, as explained in the previous section, you can create an event pattern and use the sample event to make sure it is matching events as desired. **To create and test an event pattern that matches SES events in the EventBridge Sandbox** 1. Open the Amazon EventBridge console at [https://console.aws.amazon.com/events/](https://console.aws.amazon.com/events/). 1. In the navigation pane, choose **Developer resources,** then select **Sandbox**, and on the **Sandbox** page choose the **Event pattern** tab. 1. For **Event source**, choose **AWS events or EventBridge partner events**, and select the sample event you want to test as explained in the previous section. 1. Scroll down to **Creation method**, and choose **Use pattern form**. 1. In the **Event pattern** section, for **Event source** choose **AWS services**. 1. Under **AWS service**, select **SES**. 1. For **Event type**, select the SES event type you want to match. EventBridge displays the minimum event pattern, comprised of `source` and `detail-type` fields, that matches the selected SES event. In the two examples, the first event pattern matches against all `Advisor Recommendation Status Resolved` events, and in the second, all `Email Bounced` events: ``` { "source": ["aws.ses"], "detail-type": ["Advisor Recommendation Status Resolved"] } ``` ``` { "source": ["aws.ses"], "detail-type": ["Email Bounced"] } ``` 1. To make changes to the event pattern, select **Edit pattern** and make your changes in the JSON editor. You can also match on values in one or more detail data fields. This includes specifying multiple possible values for a field value. In the following example, the detail field was added to the generated minimum event pattern with the `data` field value specified as `DKIM record was not found` in order to find all Virtual Deliverability Manager advisor events with the same detail value: ``` { "source": ["aws.ses"], "detail-type": ["Advisor Recommendation Status Resolved"], "detail": { "data": ["DKIM record was not found."] } } ``` In this example, detail sub-fields were added to report on events generated by all the emails sent from *noreply@example.com* on *2024-08-05* that bounced. (Prefix matching is being used here as part of [Content filtering](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-event-patterns-content-based-filtering.html).): ``` { "source": ["aws.ses"], "detail-type": ["Email Bounced"], "detail": { "mail": { "timestamp": [{ "prefix": "2024-08-05" }], "source": ["noreply@example.com"] } } } ``` It's important that you read [Event patterns](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-event-patterns.html) in the *EventBridge User Guide*—it explains that the event pattern value you enter in the JSON editor must be surrounded by square brackets `[...]` because it's considered an array. This and more information on how to construct advanced event patterns is also provided. 1. To test if your event pattern matches against the sample event you specified in the **Sample event** pane above, select **Test pattern**. If it matches, a green banner at the bottom of the JSON editor will display, *"Sample event matched the event pattern"*. 1. To troubleshoot errors after selecting **Test pattern**: + If there are JSON related errors, the message will indicate the reason, such as, *"Event pattern is not valid. Reason: "data" must be an object or an array at line: 5, column: 14"*. To remedy this, enclose the value on line 5 with square brackets `[...]`. + If there's a discrepancy between the values in the *Sample event* and your *Event pattern*, the message will be, *"Sample event did not match the event pattern"*. This means that one or more values you want to test are different than the example values generated by the *Sample events* generator. To remedy this, proceed with the remaining steps. 1. To change the sample values in the *Sample event* in order to successfully test your *Event pattern*, in the **Sample event** pane, select **Copy** under the JSON editor. 1. Select the radio button next to **Enter my own** for **Sample event type** above the editor. 1. Paste the sample event into the JSON editor, and for any field you're using in your event pattern, replace that same field's value to match the value you specified in your event pattern. 1. Scroll back down to the Event pattern pane and select **Test pattern** again. If all values were entered correctly and match, a green banner at the bottom of the JSON editor will display, *"Sample event matched the event pattern"*. ## Additional EventBridge resources Refer to the following topics in the [https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-what-is.html](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-what-is.html) for more information on how to use EventBridge to process and manage events. + For detailed information on how event buses work, see [Amazon EventBridge event bus](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-event-bus.html). + For information on event structure, see [Events](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-events.html) + For information on constructing event patterns for EventBridge to use when matching events against rules, see [Event patterns](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-event-patterns.html) + For information on creating rules to specify which events EventBridge processes, see [Rules](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-rules.html) + For information on to specify what services or other destinations EventBridge sends matched events to, see [Targets](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-targets.html)