Using An AWS CloudFormation Stack To Allow "-" Instead Of "+" In Gmail Email Addresses

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.


If you have a Gmail address of, then email messages sent to addresses of the form 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, you could send mail to or

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.


The approach presented here works with custom domains set up with Google Apps for Business. You can’t use it for individual, free “” 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 and, 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, 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 back to a plus as and relay the message back to Gmail for standard delivery to the user.


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:

Launch Stack

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:
ssh_key_name=$USER  # Your ssh keypair name here
stackname="example-$host-$(date +%Y%m%d-%H%M)"

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.,

  • 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:



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"


  • 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 InitializationScriptURL parameter.

  • 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.