Amazon Simple Email Service Construct Library

This module is part of the AWS Cloud Development Kit project.

Email receiving

Create a receipt rule set with rules and actions (actions can be found in the aws-cdk-lib/aws-ses-actions package):

require 'aws-cdk-lib'


bucket = AWSCDK::S3::Bucket.new(self, "Bucket")
topic = AWSCDK::SNS::Topic.new(self, "Topic")

AWSCDK::SES::ReceiptRuleSet.new(self, "RuleSet", {
    rules: [
        {
            recipients: ["hello@aws.com"],
            actions: [
                AWSCDK::SESActions::AddHeader.new({
                    name: "X-Special-Header",
                    value: "aws",
                }),
                AWSCDK::SESActions::S3.new({
                    bucket: bucket,
                    object_key_prefix: "emails/",
                    topic: topic,
                }),
            ],
        },
        {
            recipients: ["aws.com"],
            actions: [
                AWSCDK::SESActions::SNS.new({
                    topic: topic,
                }),
            ],
        },
    ],
})

Alternatively, rules can be added to a rule set:

rule_set = AWSCDK::SES::ReceiptRuleSet.new(self, "RuleSet")

aws_rule = rule_set.add_rule("Aws", {
    recipients: ["aws.com"],
})

And actions to rules:

require 'aws-cdk-lib'

aws_rule = nil # AWSCDK::SES::ReceiptRule
topic = nil # AWSCDK::SNS::Topic

aws_rule.add_action(AWSCDK::SESActions::SNS.new({
    topic: topic,
}))

When using add_rule, the new rule is added after the last added rule unless after is specified.

Drop spams

A rule to drop spam can be added by setting drop_spam to true:

AWSCDK::SES::ReceiptRuleSet.new(self, "RuleSet", {
    drop_spam: true,
})

This will add a rule at the top of the rule set with a Lambda action that stops processing messages that have at least one spam indicator. See Lambda Function Examples.

Receipt filter

Create a receipt filter:

AWSCDK::SES::ReceiptFilter.new(self, "Filter", {
    ip: "1.2.3.4/16",
})

An allow list filter is also available:

AWSCDK::SES::AllowListReceiptFilter.new(self, "AllowList", {
    ips: [
        "10.0.0.0/16",
        "1.2.3.4/16",
    ],
})

This will first create a block all filter and then create allow filters for the listed ip addresses.

AWS Service Principal permissions

When adding an s3 action to a receipt rule, the CDK will automatically create a policy statement that allows the ses service principal to get write access to the bucket. This is done with the SourceAccount condition key, which is automatically added to the policy statement. Previously, the policy used the Referer condition key, which caused confused deputy problems when the bucket policy allowed access to the bucket for all principals. See more information in this github issue

Email sending

Dedicated IP pools

When you create a new Amazon SES account, your emails are sent from IP addresses that are shared with other Amazon SES users. For an additional monthly charge, you can lease dedicated IP addresses that are reserved for your exclusive use.

Use the DedicatedIpPool construct to create a pool of dedicated IP addresses. When specifying a name for your dedicated IP pool, ensure that it adheres to the following naming convention:

• The name must include only lowercase letters (a-z), numbers (0-9), underscores (_), and hyphens (-).
• The name must not exceed 64 characters in length.

AWSCDK::SES::DedicatedIPPool.new(self, "Pool", {
    dedicated_ip_pool_name: "mypool",
    scaling_mode: AWSCDK::SES::ScalingMode::STANDARD,
})

The pool can then be used in a configuration set. If the provided dedicatedIpPoolName does not follow the specified naming convention, an error will be thrown.

Configuration sets

Configuration sets are groups of rules that you can apply to your verified identities. A verified identity is a domain, subdomain, or email address you use to send email through Amazon SES. When you apply a configuration set to an email, all of the rules in that configuration set are applied to the email.

Use the ConfigurationSet construct to create a configuration set:

require 'aws-cdk-lib'

my_pool = nil # AWSCDK::SES::IDedicatedIPPool


AWSCDK::SES::ConfigurationSet.new(self, "ConfigurationSet", {
    tls_policy: AWSCDK::SES::ConfigurationSetTLSPolicy::REQUIRE,
    dedicated_ip_pool: my_pool,
    # Specify maximum delivery time
    # This configuration can be useful in such cases as time-sensitive emails (like those containing a one-time-password),
    # transactional emails, and email that you want to ensure isn't delivered during non-business hours.
    max_delivery_duration: AWSCDK::Duration.minutes(10),
})

Use add_event_destination() to publish email sending events to Amazon SNS, Amazon CloudWatch, Amazon Data Firehose or Amazon EventBridge:

my_configuration_set = nil # AWSCDK::SES::ConfigurationSet
my_topic = nil # AWSCDK::SNS::Topic


my_configuration_set.add_event_destination("ToSns", {
    destination: AWSCDK::SES::EventDestination.sns_topic(my_topic),
})

Note: For EventBridge, you must specify the default EventBus:

require 'aws-cdk-lib'

my_configuration_set = nil # AWSCDK::SES::ConfigurationSet


bus = AWSCDK::Events::EventBus.from_event_bus_name(self, "EventBus", "default")

my_configuration_set.add_event_destination("ToEventBus", {
    destination: AWSCDK::SES::EventDestination.event_bus(bus),
})

For Firehose, if you don't specify IAM Role ARN for Amazon SES to send events. An IAM Role will be created automatically following https://docs.aws.amazon.com/ses/latest/dg/event-publishing-add-event-destination-firehose.html.

require 'aws-cdk-lib'

my_configuration_set = nil # AWSCDK::SES::ConfigurationSet
firehose_delivery_stream = nil # AWSCDK::KinesisFirehose::IDeliveryStream
iam_role = nil # AWSCDK::IAM::IRole


# Create IAM Role automatically
my_configuration_set.add_event_destination("ToFirehose", {
    destination: AWSCDK::SES::EventDestination.firehose_delivery_stream({
        delivery_stream: firehose_delivery_stream,
    }),
})

# Specify your IAM Role
my_configuration_set.add_event_destination("ToFirehose", {
    destination: AWSCDK::SES::EventDestination.firehose_delivery_stream({
        delivery_stream: firehose_delivery_stream,
        role: iam_role,
    }),
})

Tracking options

You can specify to use a custom redirect domain to handle open and click tracking for email sent with this configuration set by using custom_tracking_redirect_domain and custom_tracking_https_policy. Detail can be found in Custom tracking domain.

AWSCDK::SES::ConfigurationSet.new(self, "ConfigurationSet", {
    custom_tracking_redirect_domain: "track.cdk.dev",
    custom_tracking_https_policy: AWSCDK::SES::HttpsPolicy::REQUIRE,
})

Note: The custom tracking redirect domain must be verified in Amazon SES. To create verified identities, you can use the EmailIdentity construct.

Override account-level suppression list settings

You can customize account-level suppression list separately for different configuration sets by overriding it with configuration set-level suppression.

For details, see Using configuration set-level suppression to override your account-level suppression list.

By default, the configuration set uses your account-level suppression list settings.

You can disable account-level suppression list by specifying disable_suppression_list to true. Email sent with this configuration set will not use any suppression settings at all.

AWSCDK::SES::ConfigurationSet.new(self, "ConfigurationSet", {
    disable_suppression_list: true,
})

You can also override account level settings with configuration set-level suppression enabled. Email sent with this configuration set will only use the suppression conditions you enabled for it (bounces, complaints, or bounces and complaints) - regardless of what your account-level suppression list settings are, it will override them.

# Only bounces will be suppressed.
AWSCDK::SES::ConfigurationSet.new(self, "ConfigurationSet", {
    suppression_reasons: AWSCDK::SES::SuppressionReasons::BOUNCES_ONLY,
})

# Only complaints will be suppressed.
AWSCDK::SES::ConfigurationSet.new(self, "ConfigurationSet", {
    suppression_reasons: AWSCDK::SES::SuppressionReasons::COMPLAINTS_ONLY,
})

# Both bounces and complaints will be suppressed.
AWSCDK::SES::ConfigurationSet.new(self, "ConfigurationSet", {
    suppression_reasons: AWSCDK::SES::SuppressionReasons::BOUNCES_AND_COMPLAINTS,
})

Auto Validation threshold

Auto validation automatically reviews all outbound email addresses before sending and only delivers messages to recipients meeting your selected validation threshold. This protects sender reputation by preventing sends to invalid or risky addresses.

You can override the account-level Auto Validation settings at the configuration set level using auto_validation_threshold:

• MANAGED - Amazon SES automatically optimizes threshold based on sending patterns and reputation (recommended)
• HIGH - Only addresses with high delivery likelihood (maximum reputation protection)
• MEDIUM - Addresses with medium or high delivery likelihood (balances protection with reach)

For more details, see Auto Validation.

AWSCDK::SES::ConfigurationSet.new(self, "ConfigurationSet", {
    auto_validation_threshold: AWSCDK::SES::AutoValidationThreshold::HIGH,
})

Use disable_auto_validation to turn the feature on or off for this configuration set, regardless of the account-level setting:

# Explicitly disable Auto Validation for this configuration set.
AWSCDK::SES::ConfigurationSet.new(self, "NoAutoValidation", {
    disable_auto_validation: true,
})

Email identity

In Amazon SES, a verified identity is a domain or email address that you use to send or receive email. Before you can send an email using Amazon SES, you must create and verify each identity that you're going to use as a From, Source, Sender, or Return-Path address. Verifying an identity with Amazon SES confirms that you own it and helps prevent unauthorized use.

To verify an identity for a hosted zone, you create an EmailIdentity:

my_hosted_zone = nil # AWSCDK::Route53::IPublicHostedZone


identity = AWSCDK::SES::EmailIdentity.new(self, "Identity", {
    identity: AWSCDK::SES::Identity.public_hosted_zone(my_hosted_zone),
    mail_from_domain: "mail.cdk.dev",
})

By default, Easy DKIM with a 2048-bit DKIM key is used.

You can instead configure DKIM authentication by using your own public-private key pair. This process is known as Bring Your Own DKIM (BYODKIM):

my_hosted_zone = nil # AWSCDK::Route53::IPublicHostedZone


AWSCDK::SES::EmailIdentity.new(self, "Identity", {
    identity: AWSCDK::SES::Identity.public_hosted_zone(my_hosted_zone),
    dkim_identity: AWSCDK::SES::DkimIdentity.byo_dkim({
        private_key: AWSCDK::SecretValue.secrets_manager("dkim-private-key"),
        public_key: "...base64-encoded-public-key...",
        selector: "selector",
    }),
})

When using public_hosted_zone() for the identity, all necessary Amazon Route 53 records are created automatically:

• CNAME records for Easy DKIM
• TXT record for BYOD DKIM
• MX and TXT records for the custom MAIL FROM

When working with domain(), records must be created manually:

identity = AWSCDK::SES::EmailIdentity.new(self, "Identity", {
    identity: AWSCDK::SES::Identity.domain("cdk.dev"),
})

identity.dkim_records.each do |record|
end

Grants

To grant a specific action to a principal use the grant method. For sending emails, grant_send_email can be used instead:

require 'aws-cdk-lib'
user = nil # AWSCDK::IAM::User


identity = AWSCDK::SES::EmailIdentity.new(self, "Identity", {
    identity: AWSCDK::SES::Identity.domain("cdk.dev"),
})

identity.grant_send_email(user)

You can also reference an existing email identity using its ARN and grant permissions to it:

require 'aws-cdk-lib'
user = nil # AWSCDK::IAM::User


# Imports an existing email identity using its ARN.
# This is one way to reference an existing identity; another option is using its name via fromEmailIdentityName.
imported_identity = AWSCDK::SES::EmailIdentity.from_email_identity_arn(self, "ImportedIdentity", "arn:aws:ses:us-east-1:123456789012:identity/example.com")

# Grant send email permission to the imported identity
imported_identity.grant_send_email(user)

Virtual Deliverability Manager (VDM)

Virtual Deliverability Manager is an Amazon SES feature that helps you enhance email deliverability, like increasing inbox deliverability and email conversions, by providing insights into your sending and delivery data, and giving advice on how to fix the issues that are negatively affecting your delivery success rate and reputation.

Use the VdmAttributes construct to configure the Virtual Deliverability Manager for your account:

# Enables engagement tracking and optimized shared delivery by default
AWSCDK::SES::VdmAttributes.new(self, "Vdm")

If you want to override the VDM settings in the specified configuration set, use vdm_options in the ConfigurationSet construct.

Note: The configuration set level settings need to be used together with the account level settings. (To set the account level settings using CDK, use the VdmAttributes Construct.) If you enable only the configuration set level settings, VDM will not be enabled until the account level settings are configured. For more information, see Virtual Deliverability Manager settings.

AWSCDK::SES::ConfigurationSet.new(self, "ConfigurationSetWithVdmOptions", {
    vdm_options: {
        engagement_metrics: true,
        optimized_shared_delivery: true,
    },
})