A Lambda function to redirect SES inbound emails to an external address as an attachment, relatively easy to configure, with no data lost in the message's header and fully standard compliant.
Any of these settings are configurable through Lambda environment variables:
- Handling more than one custom email address, leveraging an alias table to map internal → external addresses.
- Defining a default From / To email address (if not in the alias table).
- Customizing the redirect message.
- Sending errors' copy via email to an administrator.
Many privates or small businesses decide to buy a domain and to configure one or more custom email addresses. But because each one of them already have a personal email account somewhere else (Google, Yahoo, Hotmail, etc…) they don't want a full email box, but just a service that redirects the emails.
Thanks to AWS SES + S3 + Lambda, with a relative small effort to orchestrate these three services, this is doable in a professional/production way and barely for free!
I know that around the web there are already a lot of solutions to accomplish this. The problem is that, most of them, are just a "it works" solution. They don't really satisfy some requirements, like:
- being able to map more than one custom address to one or more external email
- respect the IETF and W3C email standard specifics
- define an administrator email address to handle any potential error
First of all, let's make it clear what the differences are between redirect and forward:
- Forward means sending a new email to one or more addresses, including the original message in the body indented. This means loosing almost any of the original header fields – especially FROM and TO – and altering the original body.
- Redirect means sending a new email to one or more addresses, altering – as little as possible – only the header part. The idea behind redirect is trying to save as much information as possible from the original message (possibly, leaving it untouched).
So, as you can imagine, doing a simply copy and paste of a message, overwriting just the FROM and TO fields, and sending it to a new address, means loosing lots of information within the header, like:
- FROM
- TO (this is the most dangerous!)
- Message ID
- DATE
- SPAM information
- Custom fields
- Message path through servers
What do IETF and W3C say? Basically, there are two official ways to solve it:
- The Good one — Using the "resent headers": that is, renaming the original TO and FROM headers in Resent-To and Resent-From, set the new FROM and TO headers, copy everything else, send the new message. Doing like this, some header changes and someone else is overwritten, but even if the data lost is little, there is still.
- The Best one — Attaching the original message to a new one: the original message is encapsulated to a new one, using the special
Content-type: message/rfc822. Doing like this the original message remains completely untouched.
The latter one is what this project is all about: implementing a service to redirect messages leaving them untouched, compliant to standards.
For more information about this topic, you can check these two links:
The moment I wrote this file, these are the actual costs per service:
- Lambda:
- 0$ for the first 1 Million requests and 400 000 GB/seconds, both per month.
- S3:
- 0.023$/GB (worst case).
- SES:
- Sending (from an EC2 instance or Lambda function):
- $0 for the first 62,000 emails sent per month.
- Receiving:
- $0 for the first 1,000 emails received per month.
- Sending (from an EC2 instance or Lambda function):
To sum up, the implementation to this redirect service is barely 100% free.
More information at these links:
The following instructions don't pretend to be an exhaustive step-by-step walk through, but only a general guide about how to install, configure and use this software.
For anything related to AWS services, domains or DNS entries, please refer to the official documentations.
- A proprietary domain with the rights to change DNS entries (using Route 53 is not mandatory).
- One or more external email addresses (Gmail, Yahoo, Hotmail, etc…).
- Node.js and npm installed in your local environment.
- An AWS account with these services already configured:
- S3 private bucket.
- SES outbound with domain and external emails verified (if you need more freedom, you have to send a request to Amazon to switch your account out from the sandbox mode. For most cases, sandbox mode is fine).
- Download and pack the function:
- Clone this repository:
git clone https://github.com/lcrea/aws-ses-email-redirect.git
- Install the dependencies (no dev required):
npm install --production
- Pack everything in a zip file:
zip -r9 aws-ses-email-redirect.zip .
- Clone this repository:
- Configure the Lambda function:
- Login to your AWS account
- Create a new Lambda function (ex.
aws-ses-email-redirect) in the same region where you already configured SES - Set as resources consumed by Lambda function:
- CloudWatch Logs (automatically created by AWS)
- S3: choose one object key (ex.
myfolder/mail) in your bucket (ex.my-bucket) and give it the permission to read and delete within it - SES (this will be automatically created in the next step)
- Set as runtime engine: Node.js (latest version)
- Upload your zip file
aws-ses-email-redirect.zip - Set as handler file:
lambda/app.handler - Next, configure the environment variables (see below 👇 )
- Configure SES inbound service:
- Login to your AWS account
- Create a new rule set in
SES>Email Receiving - Define how many email addresses (recipients) you need for your domain (ex.
[email protected]) - Create two actions in this order:
- S3: set the bucket (
my-bucket) and the object key prefix (myfolder/mail) above - Lamdba: select the lambda function (
aws-ses-email-redirect) andEventas invocation type (this will be the trigger).
- S3: set the bucket (
That's it!
If you have correctly set permissions for Lamdba function, S3 and configured the environment variables (see below 👇 ), your redirect service is already working 👏
Login to your AWS account and go to your Lambda function (aws-ses-email-redirect). Here you have to configure the following variables:
-
MANDATORY
DOMAIN: your proprietary domain (mydomain.com)BUCKET_NAME: this is your full S3 bucket + object key (my-bucket/myfolder/mail). You can think of it like the path where you are gonna save your emailsDEFAULT_EMAIL_FROM: this is the from address without the domain part to use in the redirected message (ex.no-reply). This address does not need to exist! It's just the from field the you're gonna see in the redirected email: it can be whatsoever.DEFAULT_EMAIL_TO: this is the address to which redirect messages if not found in the alias table or if you haven't configured it (ex.[email protected])REDIRECT_MESSAGE: a default message to include in the body of the redirected email
-
OPTIONAL
ALIASES: if you want to map more than one proprietary address to more than one external address, you need to specify an alias table as a JSON object like this:{"me": "[email protected]", "info": "[email protected]"}. Again, internal proprietary addresses are without the domain part.ERROR_EMAIL_TO: if you want to be notified by email of any possible errors in the redirect process, instead of checking them in the AWS CloudWatch logs, you can define an email address as an administrator.
The idea is strongly inspired by the Postfix alias map file. It's just a set (actually, a JSON Object) of inward addresses mapped to outward addresses, like this:
{
"me": "[email protected]",
"info": "[email protected]",
"job": "[email protected]",
}So, if the custom domain is "mydomain.com" whoever will send an email to [email protected] will be redirected to [email protected]; to [email protected] will be redirected to [email protected]; and so on. Also, thanks to the DEFAULT_EMAIL_FROM variable defined above, if an email is sent to an address not in the alias table, but defined in the SES inbound settings (like [email protected]), it will be redirect to that address that works as a catch all. That's the reason why the alias table is "optional": most people don't even need it.
Configure [email protected] in the SES inbound section. Then, inside the Lambda function, set:
DEFAULT_EMAIL_TO = [email protected]
No alias table is required.
[email protected] -> [email protected]
[email protected] -> [email protected]
[email protected] -> [email protected]
Configure [email protected], [email protected], [email protected] in the SES inbound section. Then, inside the Lambda function, set:
DEFAULT_EMAIL_TO = [email protected] // This works like a catchall
Again, no alias table is required.
[email protected] -> [email protected]
[email protected] -> [email protected]
[email protected] -> [email protected]
Configure [email protected], [email protected], [email protected] in the SES inbound section. Then, inside the Lambda function, set:
ALIASES = { "me": "[email protected]" }
DEFAULT_EMAIL_TO = [email protected] // This works like a catchall
- Node.js v10.6 — Main interpreter.
- Nodemailer — Module to structure the new emails.
- Jest — Test framework for internal code.
- Amazon SAM CLI — Local Lambda test environment.
Luca Crea — https://www.linkedin.com/in/lucacrea
This project is licensed under the MIT License. See the LICENSE.txt file for details.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent