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):
import aws_cdk.aws_s3 as s3
import aws_cdk.aws_ses_actions as actions
bucket = s3.Bucket(self, "Bucket")
topic = sns.Topic(self, "Topic")
ses.ReceiptRuleSet(self, "RuleSet",
rules=[ses.ReceiptRuleOptions(
recipients=["hello@aws.com"],
actions=[
actions.AddHeader(
name="X-Special-Header",
value="aws"
),
actions.S3(
bucket=bucket,
object_key_prefix="emails/",
topic=topic
)
]
), ses.ReceiptRuleOptions(
recipients=["aws.com"],
actions=[
actions.Sns(
topic=topic
)
]
)
]
)
Alternatively, rules can be added to a rule set:
rule_set = ses.ReceiptRuleSet(self, "RuleSet")
aws_rule = rule_set.add_rule("Aws",
recipients=["aws.com"]
)
And actions to rules:
import aws_cdk.aws_ses_actions as actions
# aws_rule: ses.ReceiptRule
# topic: sns.Topic
aws_rule.add_action(actions.Sns(
topic=topic
))
When using addRule
, 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 dropSpam
to true
:
ses.ReceiptRuleSet(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:
ses.ReceiptFilter(self, "Filter",
ip="1.2.3.4/16"
)
An allow list filter is also available:
ses.AllowListReceiptFilter(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.
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.
ses.DedicatedIpPool(self, "Pool",
dedicated_ip_pool_name="mypool",
scaling_mode=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:
# my_pool: ses.IDedicatedIpPool
ses.ConfigurationSet(self, "ConfigurationSet",
custom_tracking_redirect_domain="track.cdk.dev",
suppression_reasons=ses.SuppressionReasons.COMPLAINTS_ONLY,
tls_policy=ses.ConfigurationSetTlsPolicy.REQUIRE,
dedicated_ip_pool=my_pool
)
Use addEventDestination()
to publish email sending events to Amazon SNS or Amazon CloudWatch:
# my_configuration_set: ses.ConfigurationSet
# my_topic: sns.Topic
my_configuration_set.add_event_destination("ToSns",
destination=ses.EventDestination.sns_topic(my_topic)
)
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: route53.IPublicHostedZone
identity = ses.EmailIdentity(self, "Identity",
identity=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: route53.IPublicHostedZone
ses.EmailIdentity(self, "Identity",
identity=ses.Identity.public_hosted_zone(my_hosted_zone),
dkim_identity=ses.DkimIdentity.byo_dkim(
private_key=SecretValue.secrets_manager("dkim-private-key"),
public_key="...base64-encoded-public-key...",
selector="selector"
)
)
When using publicHostedZone()
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 = ses.EmailIdentity(self, "Identity",
identity=ses.Identity.domain("cdk.dev")
)
for record in identity.dkim_records:
pass
Grants
To grant a specific action to a principal use the grant
method.
For sending emails, grantSendEmail
can be used instead:
import aws_cdk.aws_iam as iam
# user: iam.User
identity = ses.EmailIdentity(self, "Identity",
identity=ses.Identity.domain("cdk.dev")
)
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
ses.VdmAttributes(self, "Vdm")
If you want to override the VDM settings in the specified configuration set, use vdmOptions
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.
ses.ConfigurationSet(self, "ConfigurationSetWithVdmOptions",
vdm_options=ses.VdmOptions(
engagement_metrics=True,
optimized_shared_delivery=True
)
)