email_campaign 0.1.5 → 0.1.6

data/README.rdoc

@@ -2,11 +2,9 @@
 
 For mailings related to Rails apps, email_campaign is designed to be a more flexible, more integrated (yet well-abstracted) alternative to email campaign services like Campaign Monitor and MailChimp. Designed to use SendGrid for delivery, but this is easy changed.
 
-Does its best to prevent clients from sending too frequently and ruining your sender reputation, but no guarantees.
-
 =Roadmap
 
-0.x: Basic campaign authoring and delivery, using template created by developer as a standard Rails mailer layout.
+0.x: Basic campaign authoring, delivery and tracking.
 1.0: Robust enough for production use, will be able to deal with 90% of common failure modes on its own.
 1.2: Delivery stats and graphs.
 
@@ -14,6 +12,102 @@ Does its best to prevent clients from sending too frequently and ruining your se
 
 Still pre-1.0. If you have some time, write some code or tests, exercise existing functionality on non-critical apps, submit bug reports... otherwise stay away for now.
 
+=How to Use
+
+Add to Gemfile and install:
+
+  gem 'email_campaign'
+  
+  # required
+  gem 'delayed_job'
+  gem 'daemons'
+  
+  # pick a dj backend (we'll assume ActiveRecord, but there are others):
+  gem 'delayed_job_active_record
+  
+  # recommended but not required
+  gem 'sanitize_email'
+  gem 'inline-style'
+
+Run migrations:
+
+  rake email_campaign:install:migrations
+  rails generate delayed_job:active_record
+  rake db:migrate
+
+Create a mailer, be sure to use EmailCampaign::EmailHelper:
+
+  class Campaign < ActionMailer::Base
+    default from: 'me@mysite.com'
+    helper EmailCampaign::EmailHelper
+    layout 'campaign'
+    
+    def campaign2013a(recipient)
+      # @method, and @identifier are used by our EmailHelper for tracking
+      @method = __method__
+      @identifier = recipient.identifier
+      
+      # @subject is used so we can use the same template for email and web
+      @subject = 'First mailing with email_campaign'
+      mail(:to => recipient.to_s, :subject => @subject)
+    end
+  end
+
+Add some of these to your mailer layout and template:
+
+  <!-- web version link -->
+  <%- if @identifier -%>
+  <div id="top-notice">
+    Not seeing any images in this email? <a href="<%= email_web_version_url %>">View it online &raquo;</a>
+  </div>
+  <%- end -%>
+
+  <!-- trackable link -->
+  <%= email_link_url('http://www.mysite.com/') %>
+
+  <!-- unsubscribe link -->
+  <%- if @identifier -%>
+    <p>If you do not wish to receive these emails, you may <a href="<%= email_unsubscribe_url %>">unsubscribe now</a>.</p>
+  <%- end -%>
+
+  <!-- inserts invisible tracking image to track opens -->
+  <%= email_tracking_tag %>
+
+You'll need a controller to handle tracking, unsubscribe/resubscribe and web versions.
+
+  class EmailController < ApplicationController
+    # reuse the email layout (optional, but recommended)
+    layout 'campaign'
+    
+    # include the helper, just like we did in the mailer
+    helper EmailCampaign::EmailHelper
+    
+    # adds #open, #link, #unsubscribe/#resubscribe, #web_version
+    include EmailCampaign::Handler
+    
+    # must be named the same way as your mailer method
+    # Again, @method is used for tracking, and  @subject is used so we can use the same template for email and web.
+    # Here, we copy the subject directly from the mailer. Not pretty, but does avoid duplication.
+    def campaign2013a
+      @method = __method__
+      @subject = Campaign.send(__method__, EmailCampaign::Recipient.new).subject
+      render :template => '/campaign/campaign2013a'
+    end
+  end
+
+Add routes. In this case, the old-style default works well:
+
+  match 'email(/:action(/:id))' => 'email'
+
+Finally, create an initializer that sets base_url (since urls in emails need to include hostname and protocol) and optionally controller_name (to tell email_campaign about the controller you created above):
+
+  # Set base url that will be prepended to url paths in emails
+  EmailCampaign::Config.base_url = ENV['BaseURL'] || 'http://mysite.com'
+  
+  # (Optional, can be auto-detected) Specify the name of the controller that includes
+  # EmailCampaign::Handler as it would appear in url_for(:controller => '...')
+  EmailCampaign::Config.controller_name = 'email'
+
 =Getting Help
 
 Get paid support for EmailCampaign straight from the people who made it: {Bigger Bird Creative, Inc.}[https://www.biggerbird.com] Not required, of course. :-) Free support is up top (Issues).

data/app/helpers/email_campaign/email_helper.rb

@@ -3,7 +3,7 @@ module EmailCampaign
     
     def email_tracking_tag
       if @identifier
-        image_tag(EmailCampaign::Config.base_url + url_for(:controller => 'email', :action => 'open', :method => @method, :k => @identifier), :size => '1x1', :alt => '')
+        image_tag(EmailCampaign::Config.base_url + url_for(:controller => EmailCampaign::Config.controller_name, :action => 'open', :method => @method, :k => @identifier), :size => '1x1', :alt => '')
       else
         image_tag(EmailCampaign::Config.base_url + path_to_image('email_campaign/open-tracker.gif'), :size => '1x1', :alt => '')
       end
@@ -11,18 +11,18 @@ module EmailCampaign
     
     def email_link_url(url)
       if @identifier
-        EmailCampaign::Config.base_url + url_for(:controller => 'email', :action => 'link', :url => url, :k => @identifier)
+        EmailCampaign::Config.base_url + url_for(:controller => EmailCampaign::Config.controller_name, :action => 'link', :url => url, :k => @identifier)
       else
         url
       end
     end
     
     def email_unsubscribe_url
-      EmailCampaign::Config.base_url + url_for(:controller => 'email', :action => 'unsubscribe', :k => @identifier)
+      EmailCampaign::Config.base_url + url_for(:controller => EmailCampaign::Config.controller_name, :action => 'unsubscribe', :k => @identifier)
     end
     
     def email_web_version_url
-      EmailCampaign::Config.base_url + url_for(:controller => 'email', :action => 'web_version', :method => @method, :k => @identifier)
+      EmailCampaign::Config.base_url + url_for(:controller => EmailCampaign::Config.controller_name, :action => 'web_version', :method => @method, :k => @identifier)
     end
     
   end

data/lib/email_campaign/config.rb

@@ -0,0 +1,9 @@
+module EmailCampaign
+  class Config
+    
+    class << self
+      attr_accessor :base_url, :controller_name
+    end
+    
+  end
+end

data/lib/email_campaign/engine.rb

@@ -16,10 +16,4 @@ module EmailCampaign
     
   end
   
-  class Config
-    class << self
-      attr_accessor :base_url
-    end
-  end
-  
 end

data/lib/email_campaign/handler.rb

@@ -0,0 +1,60 @@
+module EmailCampaign
+  module Handler
+    
+    def self.included(base)
+      EmailCampaign::Config.controller_name = base.controller_name
+    end
+    
+    def open
+      EmailCampaign::Recipient.record_open(params[:k]) if params[:k]
+      
+      options = {}
+      options[:disposition] = 'inline'
+      path = File.join(Rails.root, 'public/assets/email_campaign/open-tracker.gif')
+      send_file path, options
+    end
+    
+    # deprecated, remove after 4/1/2013
+    def asset
+      EmailCampaign::Recipient.record_open(params[:k]) if params[:k]
+      
+      options = {}
+      options[:disposition] = [ 'jpg', 'jpeg', 'gif', 'png' ].include?(params[:format].downcase) ? 'inline' : 'attachment'
+      
+      path = File.join(Rails.root, 'app', 'assets', 'images', 'email', params[:method].to_s, params[:filename] + '.' + params[:format])
+      if !File.exists?(path)
+        path = File.join(Rails.root, 'app', 'assets', 'images', 'email', params[:filename] + '.' + params[:format])
+      end
+      render :text => 'Not Found', :status => 404 and return if !File.exists?(path)
+      
+      send_file path, options
+    end
+    
+    def link
+      EmailCampaign::Recipient.record_click(params[:k]) if params[:k]
+      redirect_to params[:url]
+    end
+    
+    def unsubscribe
+      if params[:k]
+        @success = EmailCampaign::Recipient.unsubscribe(params[:k])
+      else
+        render :text => "No subscriber identifier given, cannot continue."
+      end
+    end
+    
+    def resubscribe
+      if params[:k]
+        @success = EmailCampaign::Recipient.resubscribe(params[:k])
+      else
+        render :text => "No subscriber identifier given, cannot continue."
+      end
+    end
+    
+    def web_version
+      EmailCampaign::Recipient.record_click(params[:k]) if params[:k]
+      redirect_to :action => params[:id]
+    end
+    
+  end
+end

data/lib/email_campaign/version.rb

@@ -1,3 +1,3 @@
 module EmailCampaign
-  VERSION = "0.1.5"
+  VERSION = "0.1.6"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: email_campaign
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.1.6
   prerelease: 
 platform: ruby
 authors:
@@ -119,7 +119,9 @@ files:
 - db/migrate/201302281520_add_recipient_identifier.rb
 - email_campaign.gemspec
 - lib/email_campaign.rb
+- lib/email_campaign/config.rb
 - lib/email_campaign/engine.rb
+- lib/email_campaign/handler.rb
 - lib/email_campaign/version.rb
 - script/rails
 - test/dummy/README.rdoc