mail_spy 0.0.2 → 0.1.1

data/README.rdoc

@@ -12,57 +12,119 @@ 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 mailspy:initialize
+ rails g mail_spy:initializer
 
-Fill out the generated mailspy_mongoid.yml with the mongodb configuration settings
+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 => "/mailspy"
+    mount MailSpy::Engine => "/mail"
   end
 
+Finally run rake db:mongoid:create_indexes to get performant sends
+
 == Usage
 
-To start using the viral tool simply enable it by
+Mailspy is centered around email templates and instances of those templates
+(aka emails).
 
-Adding the Virality module to Application Controller
-  class ApplicationController < ActionController::Base
-    include Virality
-    before_filter :track_virality
+To create a template:
+add a template to your s3 directory, campaign/stream/component.(text|html).erb
 
-  end
 
-This will give you access to the following methods in lib/virality.rb these
-methods are the complete client interface for the tool.
+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
 
-You will want to get started by instrumenting you code with the record_* methods
-and using the message_for_conceit to populate your channel messages
+finally add
 
+  esp.options = {
+    :enable_sendgrid_event_tracking => true
+  }
 
+to your initializers/mail_spy.rb file
 
-== packaging into a application
+This will automatically add in the sendgrid smtp api headers and record all
+events you have setup using the sendgrid admin interface.
 
-If you don't have a private gem server you can package the gem into your
-application since its not open source...
+Reminder: If you are using open and click tracking using MailSpy adding them
+to sendgrid will be redundant and harmful.
 
-1) gem build viral.gemspec
-2) rvm 1.9.2@global gem install viral-0.7.3.gem
-3) gem unpack viral -v '0.7.3' --target vendor/gems/
-4) Add the gemspec file to the vendored unpacked gem.
-5) bundle install
+== 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 database.yml to the dummy app, rake db:create, and
+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 is property of Ooga Labs and not open source software
-
 This project rocks and uses MIT-LICENSE.