= 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

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