Mailspy

ESP agnostic sending and tracking platform for email campaigns

Requirements

Mongodb > 1.8

Setup

Add gem “mailspy” to your Gemfile

gem "mailspy"

If you haven’t already create a mongoid.yml file for the mongodb connection

rails generate mongoid:config

If you are going to be sending on one machine make sure to scale up the pool
from the default of 1 to 10+ to get good performance. Timeouts are also a good idea

Create the mongoid configuration for the mongo db

rails g mail_spy:initializer

Fill out the generated mailspy.rb with your esp settings (file has example) and AWS settings

Then mount the engine in the routes.rb file

Rails.application.routes.draw do
  mount MailSpy::Engine => "/mail"
end

Finally run rake db:mongoid:create_indexes to get performant sends

Usage

Mailspy is centered around email templates and instances of those templates (aka emails).

To create a template: add a template to your s3 directory, campaign/stream/component.(text|html).erb

To create a instance:

MailSpy.create_email(options)

required options include:

* :campaign :top level grouping
* :stream : mid level grouping
* :component : bottom level grouping
* :schedule_at
* :subject
* :template_values
* :from
* :reply_to
* one of [:to, :cc, :bcc]

Sendgrid

MailSpy has bindings baked in for sendgrid event notification.

To enable simply configure sendgrid to send post notifications (no batch support yet) to YOUR_HOST/mount_path/sendgrid/notification

The mount path is usually ‘mail’ but is configurable in your routes file

finally add

esp.options = {
  :enable_sendgrid_event_tracking => true
}

to your initializers/mail_spy.rb file

This will automatically add in the sendgrid smtp api headers and record all events you have setup using the sendgrid admin interface.

Reminder: If you are using open and click tracking using MailSpy adding them to sendgrid will be redundant and harmful.

Google Analytics

MailSpy has automatic bindings for google analytics.

MailSpy requires that all emails form into the campaign, stream, component structure which lends itself nicely to a direct mapping in google analytics.

utm_source => MailSpy - #tracker_host utm_medium => email utm_campaign => campaign utm_term => stream utm_content => component

To enable automatic bindings with all links generated by ‘track_link’ and helper simply add

esp.options = {
  :enable_auto_google_analytics => true
}

to your initializers/mail_spy.rb file

if you prefer to assign GA settings manually you can do that directly as a option to MailSpy.create_email

the keys are:

* utm_source
* utm_medium
* utm_campaign
* utm_term
* utm_content

Again only links built with track_link will benefit from the GA tokens

Testing

You will need to add your own mongoid.yml to the dummy app, rake db:create, and rake db:migrate and rake db:test:prepare to get the dummy app setup.

Then you can simply run rake from the plugins test directory

TODO explain the test_email_credentials.yml file in /test

License

This project rocks and uses MIT-LICENSE.