Launch a CloudFormation template to set up a stack of AWS resources to fill a simple need: Supporting Gmail addresses with “-” instead of “+” separating the user name from the arbitrary tag strings.
The CloudFormation stack launched by the template consists of:
- ELB (Elastic Load Balancer)
- Auto Scaling Group
- EC2 instance(s) running Postfix on Ubuntu set up by a user-data script
- Security Group allowing ELB to connect to the instances
- CloudWatch CPU high/low alarms
- Auto Scaling scale up/down policies.
- SNS (Simple Notification Service) topic for notification of Auto Scaling events
- Route53 Record Set
This basic stack structure can be used as a solution for a large number of different needs, but in this example it is set up as an SMTP email relay that filters and translates email addresses for Google Apps for Business customers.
Because it uses Auto Scaling, ELB, and Route53, it is scalable and able to recover from various types of failures.
If you’re in a rush to see code, you can look at the CloudFormation template and the initialization script run from the user-data script.
Now, let’s look a bit more in depth at the problem this is solving and how to set up the solution.
Background
If you have a Gmail address of user@example.com, then email messages
sent to addresses of the form user+ANYTHING@example.com will also be
delivered to you. You can use any email address string after the plus
sign.
Google describes this feature in a blog post:
Append a plus ("+") sign and any combination of words or numbers after your email address. For example, if your name was
hikingfan@gmail.com, you could send mail tohikingfan+friends@gmail.comorhikingfan+mailinglists@gmail.com
This is is useful for tracking where you have entered your email address and findingout which services allow it to be used for spam. If an email variation starts getting abused, you can automatically filter it out in Gmail.
The Problem
Unfortunately, many web sites do not allow an email address with a “+” when registering and will reject any attempts to use this. I don’t know if they are trying to prevent people from using unique tracking addresses or if they just don’t know the specification for a valid email address, but the end result is the same.
If we could just use a dash (-) instead of a plus, we could enter unique tracking email addresses in each site registration.
Another example for why plus can be bad: My son added “+psat” to his email address when filling out the written PSAT so he could track who they sold his email address to (apparently every college out there). The data entry person typed a “t” instead of a “+”, so colleges started sending emails to the wrong address.
Prerequisites
The approach presented here works with custom domains set up with Google Apps for Business. You can’t use it for individual, free “@gmail.com” addresses without some additional work and a separate domain name registration.
As currently written, the CloudFormation stack requires that you already have your domain DNS handled by Route53, as the template will insert a new DNS entry for the email relay. This functionality could be removed from the template if you don’t use Route53.
The Solution
This CloudFormation template sets up a stack that will translate email addresses when Gmail forwards messages for unknown users (with dashes in the address).
After this is set up, email delivered to Gmail for the standard and
plus domain email addresses, say user@example.com and
user+ANYTHING@example.com, will still be processed exactly as they
were before. This stack does not interfere with that operation.
When email is addressed to the new dash form, like
user-ANYTHING@example.com, Gmail will not be able to find the user,
and will forward this to the email relay set up by the CloudFormation
template.
The email relay will translate the dash in user-ANYTHING@example.com
back to a plus as user+ANYTHING@example.com and relay the message
back to Gmail for standard delivery to the user.
Architecture
The Route53 DNS name is set to point at the ELB. The Load Balancer is listening on the SMTP (email) port and forwards connections to the instance(s) in the Auto Scaling group.
The Auto Scaling group make sure that there is at least 1 (or the min you specify) instance running and will replace failed instances. It also monitors the CPU usage on the instances and scales up (and down) more instances as specified.
When an instance is started by the Auto Scaling group, it runs the user-data script which installs and configures Postfix to accept email for users at the configured domain. The Postfix configuration then replaces the dash with a plus and submits the message back to the standard MX servers for the domain (e.g., Gmail).
When a scaling event happens, the SNS topic is notified which triggers an email to the address provided to the template. Other addresses and listeners can be subscribed to and unsubscribed from the SNS topic.
You get to pick the instance type, min, and max when you run the template, so that you can meet your company’s volume and cost needs.
Now, let’s look at how to set it all up.
Step 1: Launch CloudFormation Stack
You can run the CloudFormation template with the AWS console or with the command line. To run it through the AWS Console in the us-east-1 region, simply click this button:
Fill out the template parameters and launch the stack. Once it’s running, follow the Google Apps Setup below.
If you have installed the AWS command line tools, then you can launch the stack in us-west-2 using commands like:
dnsdomain=example.com
dnshost=email-relay-dash-to-plus
ssh_key_name=$USER # Your ssh keypair name here
notification_email=${DEBEMAIL:-${EMAIL:?Please_Set}}
instance_type=t1.micro
min_instances=1
max_instances=2
stackname="example-$host-$(date +%Y%m%d-%H%M)"
region=us-west-2
wget http://run.alestic.com.s3.amazonaws.com/cloudformation/email-relay-dash-to-plus.template
cfn-create-stack \
--region $region \
--stack-name "$stackname" \
--template-file email-relay-dash-to-plus.template \
--parameters "InstanceType=$instance_type;OperatorEmail=$notification_email;SshKeyName=$ssh_key_name;DnsDomain=$dnsdomain;DnsHostName=$dnshost;MinInstances=$min_instances;MaxInstances=$max_instances"
Once it’s running, follow the Google Apps Setup below.
Step 2: Configure Google Apps
Once the stack is running, configure Google Apps to forward unrecognized email addresses to the email relay:
-
Log in to administer your domain in Google Apps
-
Select “Google Apps”
-
Select “Gmail”
-
Select “Advanced”
-
Scroll down to “Email Routing”
-
Select “Add Another Destination”
-
In the “Destination:” field, add the hostname.domainname of your email relay access (e.g.,
email-relay-dash-to-plus.example.com) -
Leave this option selected: (X) “Unknown mailbox accounts only”
Note: If Gmail forwards an unknown email address without a dash, the relay will simply reject it as unknown. This should not cause problems unless you need other unknown email address processing.
Step 3: Test
Make sure you can send email to allow of the following forms and have it delivered to the same user:
user@example.comuser+ANYTHING@example.comuser-ANYTHING@example.com
Cleanup
If you are just testing this out, don’t forget to delete the CloudFormation stack using the AWS console, or on the command line with:
cfn-delete-stack --region $region --force --stack-name "$stackname"
Notes
-
Though I am using this setup for a low-volume domain under Google Apps for Business, it may not work for every domain with high volume or other odd configurations. Please review the code and test to make sure it does what you need.
-
This CloudFormation stack tells AutoScaling to initialize each instance with a script that is downloaded from the GitHub repository for this project. You can remove your dependency on that repository (which may change as the software is improved) by copying the script to your own location (e.g., S3) and providing that URL in the CloudFormation template’s
InitializationScriptURLparameter. -
The Auto Scaling policies have not ben tested extensively. You may need to adjust them for scaling under real world load.
I’d be extremely curious to know if anybody actually runs one of these CloudFormation stacks and gets it to work–or where you had trouble. I’d also like to know your level of interest in CloudFormation and how much experience you’ve had with it. Would further CloudFormation articles be useful? At what level (beginner, intermediate, expert)?
Update 2012-07-22: @pmocek on Twitter points out that “-” is called a hyphen or a minus, not a dash.