EmailFootprint

Sending and tracking emails using Amazon SES, SNS, SQS, Lambda and DynamoDB.

Installation

Add this line to your application's Gemfile:

gem 'email-footprint', git: 'https://github.com/subvertical/email-footprint.git'

And then execute:

$ bundle

Usage

First create a configuration file named email-footprint.yml.erb.

$ touch email-footprint.yml.erb

The configuration file requires the following keys:

aws_region:                  us-west-2
access_key_id:               <%= ENV['AWS_ACCESS_KEY_ID'] %>
secret_access_key:           <%= ENV['AWS_SECRET_ACCESS_KEY'] %>
ses_configuration_set:       ses-configuration-set-name-defined-in-aws
campaigns_table:             campaigns-dynamodb-table-name
emails_table:                emails-dynamodb-table-name
events_table:                events-dynamodb-table-name
events_campaigns_index_name: events-dynamodb-index-name

Now you can interact with the command line tool.

$ bundle exec email-footprint
Commands:
  email-footprint campaigns_query    # Query campaigns table
  email-footprint events_query       # Query events table
  email-footprint events_recipients  # Get recipients from events table
  email-footprint get_email          # Get email from emails table
  email-footprint help [COMMAND]     # Describe available commands or one specific command
  email-footprint send_emails        # Send emails
  email-footprint store_email        # Store email body

# Send emails — sends 10 emails
$ bundle exec email-footprint send_emails campaign-1 [email protected] [email protected]
I, [...]  INFO -- EmailFootprint: Email sent!
I, [...]  INFO -- EmailFootprint: Sending email to [email protected]
I, [...]  INFO -- EmailFootprint: Email sent!
I, [...]  INFO -- EmailFootprint: Sending email to [email protected]
I, [...]  INFO -- EmailFootprint: Email sent!
I, [...]  INFO -- EmailFootprint: Sending email to [email protected]
I, [...]  INFO -- EmailFootprint: Email sent!
I, [...]  INFO -- EmailFootprint: Sending email to [email protected]
I, [...]  INFO -- EmailFootprint: Email sent!
I, [...]  INFO -- EmailFootprint: Sending email to [email protected]
I, [...]  INFO -- EmailFootprint: Email sent!
I, [...]  INFO -- EmailFootprint: Sending email to [email protected]
I, [...]  INFO -- EmailFootprint: Email sent!
I, [...]  INFO -- EmailFootprint: Sending email to [email protected]
I, [...]  INFO -- EmailFootprint: Email sent!
I, [...]  INFO -- EmailFootprint: Sending email to [email protected]
I, [...]  INFO -- EmailFootprint: Email sent!
I, [...]  INFO -- EmailFootprint: Sending email to [email protected]
I, [...]  INFO -- EmailFootprint: Email sent!
I, [...]  INFO -- EmailFootprint: Sending email to [email protected]

# Query campaigns table - retrieve the summary
$ bundle exec email-footprint campaigns_query campaign-1
I, [...]  INFO -- EmailFootprint: CampaignId: campaign-1
I, [...]  INFO -- EmailFootprint: Open:       21
I, [...]  INFO -- EmailFootprint: Send:       10
I, [...]  INFO -- EmailFootprint: Click:      4
I, [...]  INFO -- EmailFootprint: Delivery:   10

# Query events table - retrieve all the data (just showing counts here)
$ bundle exec email-footprint events_query campaign-1
I, [...]  INFO -- EmailFootprint: Open: 21
I, [...]  INFO -- EmailFootprint: Delivery: 10
I, [...]  INFO -- EmailFootprint: Send: 10
I, [...]  INFO -- EmailFootprint: Click: 4

# Get recipients from events table
$ bundle exec email-footprint events_recipients campaign-1 Click
I, [...]  INFO -- EmailFootprint: ["[email protected]", "[email protected]", "[email protected]", "[email protected]"]

# Store email body
$ bundle exec email-footprint store_email campaign-1 [email protected] EmailBodyGoesHere
I, [...]  INFO -- EmailFootprint: Stored the email

# Get email from emails table
$ bundle exec email-footprint get_email campaign-1 [email protected]
I, [...]  INFO -- EmailFootprint: CampaignId: campaign-1
I, [...]  INFO -- EmailFootprint: Recipient: [email protected]
I, [...]  INFO -- EmailFootprint: Body: EmailBodyGoesHere

CloudFormation Deploy

aws cloudformation package --template-file cloudformation/cloudformation.yml \
--s3-bucket email-footprint-lambda --output-template-file output.yml && \
aws cloudformation deploy --template-file output.yml --stack-name email-footprint-build-v1 \
--capabilities CAPABILITY_IAM

Development

After checking out the repository, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/subvertical/email-footprint. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

Resources

• Amazon SES Open and Click Tracking

License

The gem is available as open source under the terms of the MIT License.