A Simple AWS SES Terraform Module For Application Email Services

Motivation

I needed to enable an application hosted in AWS to send email. I wanted to also add the capability to receive email sent to any address on the applications domain and store it for processing. I published the resulting terraform module to the terraform registry here. Here is a direct link to the GitHub repository.

Module Details

This module creates an SES verified identity and sets up the various Route 53 records for SES integration. This works under the assumption that the email you want to send email from is registered in Route 53 as a hosted zone.

Optionally if configured to do so you can also receive email by setting the enable_incoming_email variable to true. This will create an S3 bucket to receive the email in. There are many other options than storing in S3, but for my purposes it fit my needs at this time.

This module adds SPF, DKIM and DMARC. All of those are modern email security technologies that I may write about in the future. I have written about DKIM before here.

Partial Email / SES Primer

There are a few terms related to email and specifically AWS SES that are useful to understand if you are unfamiliar with them:

Email Terms

• DKIM
  • Domain Keys Identified Mail (DKIM) defined by RFC-6376 is a algorithm for signing parts of an email message with a private key and having the public key in DNS so that the contents of the message signed by the signer have not been altered. For more detail on DKIM and how it is verified give this a read.
• Mail From Address
  • When sending an email there are two from addresses.
    • The from address which is what you see as the sender in your email application
    • The Mail From address which is where the email originated from. For AWS SES this will by default be a AWS SES sub domain. You can customize this to be a sub domain of your email domain, but that requires setting up SPF so that your email is not flagged as spoof email.
• SPF
  • Sender Policy Framework (SPF) defined by RFC-7208 is a mechanism to prevent email spoofing when your Mail From domain differs from your sending domain you must set up a DNS TXT record on the Mail From domain specifying the actual origin of the email, in this case AWS SES.
• DMARC
  • Domain-based Message Authentication, Reporting and Conformance (DMARC) defined by RFC-7489 is a standard for reporting issues with SPF and/or DKIM. This also allows you to tell other email providers receiving email from your domain how to react when email fails validation. You can tell the email provider to
    • ignore the issue
    • quarantine the message (typically sending to a span folder)
    • reject the message which will cause the message to not be delivered

AWS SES Terms

• Verified Identity
  • This is just referring to the requirements of AWS SES around needing to verify your ownership of an email address or domain before using it to send email.
• Configuration Set
  • This is a mechanism in AWS SES that allows you to set rules for your verified identities. This can apply rules around sending and receiving email. In the context of this module we are using the receiving rules to forward email over to an S3 bucket.

A Quick note about AWS SES Sandbox

AWS accounts start with SES Sandbox access which restricts your ability to send emails via SES. You can request production access which will list these restrictions, but be aware that you will needs to make the request for production SES access to send email without the sandbox restrictions. Requesting SES Production access can be done via the AWS Console or the AWS CLI.

You can test that this works via the AWS CLI. This example assume your mail domain is example.com. You will need to change that email domain to your actual email domain ;-)

aws ses send-email --from test_sender@exmaple.com --to user@exmaple.com --text "This is a test message" --subject "This is the subject"

The example in the terraform repository also has an example of a role that can be assumed to send email via SES that restricts the sender domain.

Future Plans

This is a simple module and it suits the needs for what I needed when I wrote it. There is some potential to enhance the module to add other receive handlers than the S3 bucket like a Lambda or SNS topic message. If someone opens a PR or I ever have a need those enhancements can get added.