Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Autogenerate query parameters to links in emails to track click throughs
Ruby
branch: master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
lib
.document
.gitignore
Gemfile
LICENSE.txt
README.rdoc
Rakefile
mail_jack.gemspec

README.rdoc

MailJack

This module will append query parameters of your choosing to every link in the mailers you specify so that you can track click throughs. The parameters are dynamically evaluated at mail send time with the Proc of your choosing. Cool, huh.

Usage:

# config/initializers/mail_tracker.rb
MailJack.config do |config|

  # specify what mailer classes you want to add tracking to
  config.mailers = [:user_notifier]

  # specify the regex that should be used filter hrefs
  # (this is useful so you don't add tracking params to 3rd party urls off your site)
  config.href_filter = /myapplication.com/

  # MOST IMPORTANT PART
  # Specify what attributes you want to track and the Proc that figures them out
  # The attributes can be any name.  The value must be an object that responds to #call
  config.trackable do |track|
    track.campaign = lambda{|mailer| mailer.action_name}
    track.campaign_group = lambda{|mailer| mailer.class.name}
    track.foobarbizbat = lambda{|mailer| Time.now}
  end

  # You can enable Base64 encoding of all the parameters like so:
  config.encode_to = :your_param_name_that_will_hold_the_encoded_string
end

Under the Covers

  • You specify what mailer classes you want to track, and any other options

  • You specify the attributes that will be tracked the Proc that should be used to figure out the value

  • Mail::Message class has the trackable keys added as attr_accessors

  • ActionMailer::Base#mail method is decorated via alias_method_chain for each mailer class specified

  • MailJack registers a Mail::Interceptor to intercept all outgoing mail

  • When ActionMailer::Base#mail is called, the undecorated method is called first, then MailJack

  • fetches the values of the attributes specified by calling the Proc specified and passing in the mailer

  • instance, so You can figure out what value should be returned

  • Those values are then assigned to the Mail::Message class via the accessors we added in step 3

  • The mail is sent and is subsequently intercepted by MailJack::Interceptor which then reads the values passed along into the Mail::Message, creates a query string, and finds all relevant href's and appends the tracking parameters

What's up with this name?

Like LoJack...get it?  No? ok, well, naming things is probably the most difficult aspect of software engineering and so the idea is that you are tracking your emails, hence MailJack.  Maybe MailTrack would've been better, but that's not very creative now is it?

Copyright

Copyright © 2013 Peter Philips. See LICENSE.txt for further details.

Something went wrong with that request. Please try again.