mail_spy 0.0.5 → 0.0.6

data/README.rdoc

@@ -24,7 +24,7 @@ and AWS settings
 
 Then mount the engine in the routes.rb file
   Rails.application.routes.draw do
-    mount MailSpy::Engine => "/mail_spy"
+    mount MailSpy::Engine => "/mail"
   end
 
 == Usage
@@ -42,7 +42,6 @@ MailSpy.create_email(options)
 
 required options include:
 
- * :template_name
  * :campaign :top level grouping
  * :stream : mid level grouping
  * :component : bottom level grouping
@@ -54,6 +53,63 @@ required options include:
  * 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
 

data/app/assets/javascripts/mail_spy/application.js

@@ -12,4 +12,6 @@
 //
 //= require jquery
 //= require jquery_ujs
+//= require mail_spy/lib/underscore
+//= require mail_spy/lib/backbone
 //= require_tree .

data/app/assets/javascripts/mail_spy/sendgrid.js

@@ -0,0 +1,2 @@
+// Place all the behaviors and hooks related to the matching controller here.
+// All this logic will automatically be available in application.js.

data/app/assets/stylesheets/mail_spy/application.css

@@ -9,5 +9,4 @@
  * compiled file, but it's generally better to create a new file per style scope.
  *
  *= require_self
- *= require_tree .
 */

data/app/assets/stylesheets/mail_spy/sendgrid.css

@@ -0,0 +1,4 @@
+/*
+  Place all the styles related to the matching controller here.
+  They will automatically be included in application.css.
+*/

data/app/controllers/mail_spy/sendgrid_controller.rb

@@ -0,0 +1,26 @@
+module MailSpy
+  class SendgridController < ApplicationController
+
+    #Parses a notification from the sendgrid system
+    def notification
+      #Must be passed in via SendGrids SMTP API Headers
+      email_id = params['eid']
+      return head 400 if email_id.blank? || params[:event].blank?
+
+      #Send grid event name
+      event_action = "sendgrid-#{params[:event]}"
+
+      case event
+        when 'bounce', 'dropped'
+          MailSpy.track_action(email_id, event_action, {:reason => params[:reason]})
+        when 'click'
+          MailSpy.track_action(email_id, event_action, {:url => params[:url]})
+        when 'deferred', 'delivered', 'processed', 'open', 'spamreport', 'unsubscribe'
+          MailSpy.track_action(email_id, event_action)
+      end
+
+      head :ok
+    end
+
+  end
+end

data/app/controllers/mail_spy/tracking_controller.rb

@@ -33,20 +33,13 @@ module MailSpy
     def action
       email_id = params[:eid]
       action_type = params[:action_type]
-      details = params[:details]
+      count = params[:count] || 1
+      details = params[:details] || {}
 
       head :unprocessable_entity and return if email_id.blank? || action_type.blank?
       head :unprocessable_entity and return if details.present? && !details.kind_of?(Hash)
 
-      hash ={}
-      hash[:action_type] = action_type
-      hash[:count] = params[:count] if !params[:count].nil?
-      hash[:details] = details if details.present? && details.kind_of?(Hash)
-
-      # Save it up
-      email = MailSpy::Email.find(email_id)
-      email.actions.create!(hash)
-
+      MailSpy.track_action(email_id, action_type, details, count)
       head 200
     end
   end

data/app/helpers/mail_spy/email_helper.rb

@@ -21,15 +21,24 @@ module MailSpy
         tag_options = tag_options(html_options)
 
         # Inject our tracking url, and pass in the redirect_url
-        url = url_for(
+        hash = {
           :controller => "mail_spy/tracking",
           :action => :link,
           :url => url,
           :only_path => false,
           :host => MailSpy.tracker_host,
           :n => @_track_count,
-          :eid => @_email_id
-        )
+          :eid => @_email.id
+        }
+
+        # Add in the GA tokens if present
+        hash[:utm_source] = @_email.utm_source if @_email.utm_source.present?
+        hash[:utm_medium] = @_email.utm_medium if @_email.utm_medium.present?
+        hash[:utm_campaign] = @_email.utm_campaign if @_email.utm_campaign.present?
+        hash[:utm_term] = @_email.utm_term if @_email.utm_term.present?
+        hash[:utm_content] = @_email.utm_content if @_email.utm_content.present?
+
+        url = url_for(hash)
 
 
         href_attr = "href=\"#{ERB::Util.html_escape(url)}\"" unless href
@@ -43,7 +52,7 @@ module MailSpy
       url = url_for(
         :controller => "mail_spy/tracking",
         :action => :bug,
-        :eid => @_email_id,
+        :eid => @_email.id,
         :only_path => false,
         :host => MailSpy.tracker_host
       )

data/app/helpers/mail_spy/sendgrid_helper.rb

@@ -0,0 +1,4 @@
+module MailSpy
+  module SendgridHelper
+  end
+end

data/app/mailers/mail_spy/core_mailer.rb

@@ -4,34 +4,28 @@ module MailSpy
 
     def template(email)
       # Slight hack to provide information to helpers
-      @_email_id = email.id
+      @_email = email
       @template_values = email.template_values
+      esp = MailSpy.esps[email.email_service_provider]
       email_hash = {}
 
-
       # Evaluate the subject line as erb
       if email.subject.present?
         subject = ERB.new(email.subject).result(binding)
-        email_hash[:subject] =  subject
+        email_hash[:subject] = subject
       end
 
       # Set Headers
       std_email_keys = [:to, :cc, :bcc, :from, :message_id, :sender, :reply_to]
-      std_email_keys.each { |key| set_if_present(email_hash,email, key) }
-      headers.merge!(email.headers) if email.headers.present?
+      std_email_keys.each { |key| set_if_present(email_hash, email, key) }
+      email.headers.each {|key, value| headers[key] = value} if email.headers.present?
 
+      # Create the mail message
       mail_message = mail(email_hash) do |format|
         format.text { render :inline => email.text_erb }
         format.html { render :inline => email.html_erb }
       end
 
-      # Email Service provider setup
-      # TODO Only support smtp at the moment
-      raise "No Email service providers installed" unless MailSpy.esps.present?
-      esp = MailSpy.esps[email.email_service_provider]
-      esp_key = MailSpy.esps.keys[rand(MailSpy.esps.keys.count)]
-      esp = MailSpy.esps[esp_key] if esp.blank?
-
       mail_message.delivery_method.settings.merge!(
         {
           :address => esp.address,

data/app/models/mail_spy/email.rb

@@ -13,14 +13,15 @@ module MailSpy
     field :subject
     field :sender #Sets envelope from (aka sender header)
     field :reply_to
-    field :headers
+    field :headers, :type => Hash, :default => {}
     field :message_id #Sets the unique id for each email
 
     # Email content
-    field :template_values, :type => Hash
+    field :template_values, :type => Hash, :default => {}
 
     # Support for tracking which esp ran the email
     field :email_service_provider, :type => String
+    validates_presence_of :email_service_provider
 
     # References back to a user in another db
     field :user_id, :type => Integer
@@ -34,10 +35,24 @@ module MailSpy
     field :schedule_at, :type => DateTime
     field :sent, :type => Boolean, :default => false
     index :schedule_at
+    index :sent
+
+    # Error reporting
+    field :failed, :type => Boolean, :default => false
+    field :error_message, :type => String
+    field :error_backtrace, :type => Array
+    index :failed
 
     # Record keeping of what happened
     embeds_many :actions, :class_name => "MailSpy::Action"
 
+    # Google Analytics tracking
+    field :utm_source, :type => String
+    field :utm_medium, :type => String
+    field :utm_campaign, :type => String
+    field :utm_term, :type => String
+    field :utm_content, :type => String
+
 
     def template_values
       self.read_attribute(:template_values).try(:with_indifferent_access)
@@ -45,11 +60,11 @@ module MailSpy
 
     # Great for debugging emails
     def parsed_html_content
-      return MailSpy::CoreMailer.template(self).text_part.body.to_s
+      return MailSpy::CoreMailer.template(self).html_part.body.to_s
     end
 
     def parsed_text_content
-      return MailSpy::CoreMailer.template(self).html_part.body.to_s
+      return MailSpy::CoreMailer.template(self).text_part.body.to_s
     end
 
     def html_erb

data/app/views/mail_spy/reports/campaigns.html.erb

@@ -0,0 +1,48 @@
+<% @campaigns = [{
+                  :name=>"Valentine's Day",
+                  :last_sent => Date.today(),
+                  :sent=>5320
+                 },{
+                  :name=>"Mother's Day"
+                 }] %>
+<%= debug @campaigns %>
+<%# ------------------------------------- Backbone Templates %>
+<script type="text/javascript">
+
+  Campaign = Backbone.Model.extend({
+        initialize: function(){
+            alert("Welcome to this world");
+        }
+    });
+	CampaignView = Backbone.View.extend({
+		initialize: function(){
+			this.render();
+		},
+		render: function(){
+			// Compile the template using underscore
+			var template = _.template( $("#campaign_template").html(), {} );
+			// Load the compiled HTML into the Backbone "el"
+			this.el.html( template );
+		}
+	});
+
+	var search_view = new SearchView({ el: $("#search_container") });
+</script>
+<%# ------------------------------------- Backbone Templates %>
+<script type="text/template" id="campaign_template">
+    <div class="Campaign">
+      <h2><%= c[:name] %></h2>
+    </div>
+</script>
+<%# ------------------------------------- Start actual view %>
+
+<h1>All Campaigns</h1>
+
+<div class="CampaignReport">
+  <%# For each campaign %>
+  <% @campaigns.each do |c| %>
+  <div class="CampaignSummary">
+    <h2><%= c[:name] %></h2>
+  </div>
+  <% end %>
+</div>

data/config/routes.rb

@@ -4,4 +4,10 @@ MailSpy::Engine.routes.draw do
   match "b", :controller => :tracking, :action => :bug
   match "a", :controller => :tracking, :action => :action
 
+  match "reports", :controller => :reports, :action => :campaigns
+  match "email", :controller => :reports, :action => :email
+
+  # Sendgrid notification api
+  post "sendgrid/notification", :controller => :sendgrid, :action => :notification
+  
 end

data/lib/generators/mail_spy/templates/mail_spy.rb

@@ -28,6 +28,7 @@ end
 #  :password,
 #  :domain,
 #  :enable_starttls_auto
+#  :options (esp specific options)
 
 MailSpy.add_email_service_provider do |esp|
   esp.name = "sendgrid"
@@ -38,4 +39,8 @@ MailSpy.add_email_service_provider do |esp|
   esp.password = ENV['SENDGRID_PASSWORD']
   esp.authentication = :plain
   esp.enable_starttls_auto = true
+  esp.options = {
+    :enable_sendgrid_event_tracking => true,
+    :enable_auto_google_analytics => true
+  }
 end

data/lib/mail_spy/manager.rb

@@ -23,15 +23,45 @@ module MailSpy
       has_sender = options.keys.select { |option| to_options.include? option.intern }.present?
       raise "Email instance has no sender (to,cc,bcc were all blank)" unless has_sender
 
-
-      # Make sure that
-      (required_options + to_options).each do |option|
+      # Make sure that all options passed map to a accessor so we don't errantly
+      # think we are passing something correctly and really its getting silently
+      # ignored
+      options.keys.each do |option|
         unless MailSpy::Email.method_defined? "#{option}=".intern
           raise "MailSpy::Email doesn't have #{option} as a setter '"
         end
       end
 
+      # Ensure that a esp (forced or random) exists for the email
+      forced_esp = options[:email_service_provider]
+      if forced_esp.present?
+        raise "No esp configured with name: #{forced_esp}" if MailSpy.esps[forced_esp].blank?
+      else
+        raise "No esps configured" if MailSpy.esps.blank?
+        esp_key = MailSpy.esps.keys[rand(MailSpy.esps.keys.count)]
+        options[:email_service_provider] = esp_key
+      end
+
+      # Google Analytics aupport for automatic population of utm_tokens
+      esp = MailSpy.esps[options[:email_service_provider]]
+      if esp.options[:enable_auto_google_analytics].present?
+        options[:utm_source] ||= 'mailspy'
+        options[:utm_medium] ||= 'email'
+        options[:utm_campaign] ||= options[:campaign]
+        options[:utm_term] ||= options[:stream]
+        options[:utm_content] ||= options[:component]
+      end
+
+      #Create the email
       email = MailSpy::Email.create!(options)
+
+      #Enable sendgrid specific enhancements
+      if esp.options[:enable_sendgrid_event_tracking].present?
+        header = MailSpy::Sendgrid::SmtpApiHeader.new
+        header.setUniqueArgs({:eid => email.id})
+        email.headers = {'X-SMTPAPI' => header.asJSON}.merge(email.headers)
+      end
+
       email.save!
       email
     end
@@ -52,17 +82,24 @@ module MailSpy
         pony_hash[pony_key] = value if value.present?
       end
 
-      while (true)
-        mails = MailSpy::Email.
+      while true
+        emails = MailSpy::Email.
           limit(step).offset(offset).
-          where(:schedule_at.lte => DateTime.now, :sent => false).all
+          where(:schedule_at.lte => DateTime.now, :sent => false, :failed => false).all
         break if mails.blank?
-        mails.each do |email|
-          mail = MailSpy::CoreMailer.template(email)
-          #TODO might be nice to flush mail out in debug mode
-          mail.deliver
-          email.update_attribute(:sent, true)
-          sent += 1
+        emails.each do |email|
+          begin
+            mail = MailSpy::CoreMailer.template(email)
+            #TODO might be nice to flush mail out in debug mode
+            mail.deliver
+            email.update_attribute(:sent, true)
+            sent += 1
+          rescue Exception => e
+            email.failed = true
+            email.error_message = e.message
+            email.error_backtrace = e.backtrace
+            email.save!
+          end
         end
         offset += step
       end
@@ -72,10 +109,25 @@ module MailSpy
 
 
     # ------------------------------------------- TRACKING
-    #
-
-    def track_other_action
-
+    # MailSpy will automatically track opens and clicks if the tracking bugs
+    # and track_link helpers are used. This action allows tracking of
+    # arbitrary actions. Please be careful to standardize on action names
+    # email_id: The id from the MailSpy::Email record
+    # action_type: String denoting the action that occured
+    # details: Hash of any details of that action (again strive for standards)
+    # count: how many of this action occurred (defaults to 1)
+    def track_action(email_id, action_type, details={}, count=1)
+      raise "track_action missing email_id" if email_id.blank?
+      raise "track_Action missing action_type" if action_type.blank?
+
+      hash ={}
+      hash[:action_type] = action_type
+      hash[:count] = count
+      hash[:details] = details if details.present? && details.kind_of?(Hash)
+
+      # Save it up
+      email = MailSpy::Email.find(email_id)
+      email.actions.create!(hash)
     end
 
   end

data/lib/mail_spy/sendgrid/smtp_api_header.rb

@@ -0,0 +1,68 @@
+# Version 1.0
+# Last Updated 6/22/2009
+# Header support for send grids smtp api
+#
+#
+require 'json'
+
+module MailSpy
+  module Sendgrid
+    class SmtpApiHeader
+
+      def initialize()
+        @data = {}
+      end
+
+      def addTo(to)
+        @data['to'] ||= []
+        @data['to'] += to.kind_of?(Array) ? to : [to]
+      end
+
+      def addSubVal(var, val)
+        if not @data['sub']
+          @data['sub'] = {}
+        end
+        if val.instance_of?(Array)
+          @data['sub'][var] = val
+        else
+          @data['sub'][var] = [val]
+        end
+      end
+
+      def setUniqueArgs(val)
+        if val.instance_of?(Hash)
+          @data['unique_args'] = val
+        end
+      end
+
+      def setCategory(cat)
+        @data['category'] = cat
+      end
+
+      def addFilterSetting(fltr, setting, val)
+        if not @data['filters']
+          @data['filters'] = {}
+        end
+        if not @data['filters'][fltr]
+          @data['filters'][fltr] = {}
+        end
+        if not @data['filters'][fltr]['settings']
+          @data['filters'][fltr]['settings'] = {}
+        end
+        @data['filters'][fltr]['settings'][setting] = val
+      end
+
+      def asJSON()
+        json = JSON.generate @data
+        return json.gsub(/(["\]}])([,:])(["\[{])/, '\\1\\2 \\3')
+      end
+
+      def as_string()
+        json = asJSON()
+        str = 'X-SMTPAPI: %s' % json.gsub(/(.{1,72})( +|$\n?)|(.{1,72})/, "\\1\\3\n")
+        return str
+      end
+
+    end
+  end
+end

data/lib/mail_spy/version.rb

@@ -1,3 +1,3 @@
 module MailSpy
-  VERSION = "0.0.5"
+  VERSION = "0.0.6"
 end

data/lib/mail_spy.rb

@@ -1,5 +1,6 @@
 require 'pp' #For debugging
 require 'aws-sdk'
+require 'mail_spy/sendgrid/smtp_api_header'
 require "mongoid"
 require "mail_spy/engine"
 require "mail_spy/manager"
@@ -11,7 +12,7 @@ module MailSpy
   # Allows the client to configure and add esps to MailSpy
   MailSpyESP = Struct.new(
     :address, :port, :authentication, :user_name, :password, :domain,
-    :enable_starttls_auto, :name
+    :enable_starttls_auto, :name, :options
   )
   @@esps = {}
 
@@ -30,7 +31,9 @@ module MailSpy
   #TODO eventually have this be a view with a interface
   def self.add_email_service_provider(&block)
     esp = MailSpyESP.new
+    esp.options = {} # Important! provides default options list for internals
     block.call(esp)
+    esp.options.to_options!
     @@esps[esp.name] = esp
   end
 

data/test/dummy/config/initializers/mail_spy.rb

@@ -35,4 +35,8 @@ MailSpy.add_email_service_provider do |esp|
   esp.password = "qb6qnim0"
   esp.authentication = :plain
   esp.enable_starttls_auto = true
+  esp.options = {
+    :enable_sendgrid_event_tracking => true,
+    :enable_auto_google_analytics => true
+  }
 end

data/test/dummy/config/routes.rb

@@ -1,3 +1,3 @@
 Rails.application.routes.draw do
-  mount MailSpy::Engine => "/mail_spy"
+  mount MailSpy::Engine => "/mail"
 end