sendgrid 1.0.1 → 1.1.0

data/README.md

@@ -57,12 +57,14 @@ Here is an example of what typical usage may look like:
       include SendGrid
       sendgrid_category :use_subject_lines
       sendgrid_enable   :ganalytics, :opentrack
-  
+      sendgrid_unique_args :key1 => "value1", :key2 => "value2"
+
       def welcome_message(user)
         sendgrid_category "Welcome"
+        sendgrid_unique_args :key2 => "newvalue2", :key3 => "value3"
         mail :to => user.email, :subject => "Welcome #{user.name} :-)"
       end
-  
+
       def goodbye_message(user)
         sendgrid_disable :ganalytics
         mail :to => user.email, :subject => "Fare thee well :-("
@@ -80,6 +82,7 @@ Here are a list of supported options for sendgrid\_enable and sendgrid\_disable:
 * :opentrack
 * :clicktrack
 * :ganalytics
+  * Call sendgrid\_ganalytics\_options(:utm_source => 'welcome_email', :utm_medium => 'email', :utm_campaign => 'promo', :utm_term => 'intro+text', :utm_content => 'header_link') to set custom Google Analytics variables.
 * :gravatar
 * :subscriptiontrack
   * Call sendgrid\_subscriptiontrack\_text(:html => 'Unsubscribe <% Here %>', :plain => 'Unsubscribe Here: <% %>') to set a custom format for html/plain or both.
@@ -88,15 +91,19 @@ Here are a list of supported options for sendgrid\_enable and sendgrid\_disable:
   * Call sendgrid\_footer\_text(:html => 'My HTML footer rocks!', :plain => 'My plain text footer is so-so.') to set custom footer text for html, plain or both.
 * :spamcheck
   * Call sendgrid\_spamcheck\_maxscore(4.5) to set a custom SpamAssassin threshold at which SendGrid drops emails (default value is 5.0).
-  
+
 For further explanation see [SendGrid's wiki page on filters.](http://wiki.sendgrid.com/doku.php?id=filters)
 
+Custom parameters can be set using the sendgrid_unique_args methods.  Any key/value pairs defined thusly will
+be included as parameters in SendGrid post backs.  These are especially useful in cases where the recipient's
+email address is not unique or when multiple applications/environments are using the same SendGrid account.
+
 
 Delivering to multiple recipients
 ---------------------------------
 
 There is a per-mailer-method setting that can be used to deliver campaigns to multiple (many) recipients in a single delivery/SMTP call.
-It is quite easy to build a robust mass-delivery system utilizing this feature, and it is quite difficult to deliver a large email campaign quickly without this feature. 
+It is quite easy to build a robust mass-delivery system utilizing this feature, and it is quite difficult to deliver a large email campaign quickly without this feature.
 Note: While it may be worth asking yourself, a SendGrid engineer told me it's best to keep the number of recipients to <= 1,000 per delivery.
 
 

data/Rakefile

@@ -10,7 +10,7 @@ begin
                          SendGrid is an email deliverability API that is affordable and has lots of bells and whistles.}
     gem.email = "stephenrb@gmail.com"
     gem.homepage = "http://github.com/stephenb/sendgrid"
-    gem.authors = ["Stephen Blankenship"]
+    gem.authors = ["Stephen Blankenship", "Marc Tremblay", "Bob Burbach"]
     gem.add_dependency "json"
     # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
   end

data/VERSION

@@ -1 +1 @@
-1.0.1
+1.1.0

data/lib/sendgrid.rb

@@ -12,28 +12,37 @@ module SendGrid
     :spamcheck,
     :bypass_list_management
   ]
-  
+
+  VALID_GANALYTICS_OPTIONS = [
+    :utm_source,
+    :utm_medium,
+    :utm_campaign,
+    :utm_term,
+    :utm_content
+  ]
+
   def self.included(base)
     base.class_eval do
       class << self
         attr_accessor :default_sg_category, :default_sg_options, :default_subscriptiontrack_text,
-                      :default_footer_text, :default_spamcheck_score
+                      :default_footer_text, :default_spamcheck_score, :default_sg_unique_args
       end
-      attr_accessor :sg_category, :sg_options, :sg_disabled_options, :sg_recipients, :sg_substitutions, :subscriptiontrack_text, :footer_text, :spamcheck_score
+      attr_accessor :sg_category, :sg_options, :sg_disabled_options, :sg_recipients, :sg_substitutions,
+                    :subscriptiontrack_text, :footer_text, :spamcheck_score, :sg_unique_args
     end
-    
-    # NOTE: This commented-out approach may be a "safer" option for Rails 3, but it 
+
+    # NOTE: This commented-out approach may be a "safer" option for Rails 3, but it
     # would cause the headers to get set during delivery, and not when the message is initialized.
     # If base supports register_interceptor (i.e., Rails 3 ActionMailer), use it...
     # if base.respond_to?(:register_interceptor)
     #   base.register_interceptor(SendgridInterceptor)
     # end
-    
+
     base.extend(ClassMethods)
   end
-  
+
   module ClassMethods
-    
+
     # Sets a default category for all emails.
     # :use_subject_lines has special behavior that uses the subject-line of
     # each outgoing email for the SendGrid category. This special behavior
@@ -42,7 +51,7 @@ module SendGrid
     def sendgrid_category(category)
       self.default_sg_category = category
     end
-    
+
     # Enables a default option for all emails.
     # See documentation for details.
     #
@@ -58,19 +67,19 @@ module SendGrid
       self.default_sg_options = Array.new unless self.default_sg_options
       options.each { |option| self.default_sg_options << option if VALID_OPTIONS.include?(option) }
     end
-    
+
     # Sets the default text for subscription tracking (must be enabled).
-    # There are two options: 
-    # 1. Add an unsubscribe link at the bottom of the email 
+    # There are two options:
+    # 1. Add an unsubscribe link at the bottom of the email
     #   {:html => "Unsubscribe <% here %>", :plain => "Unsubscribe here: <% %>"}
     # 2. Replace given text with the unsubscribe link
     #   {:replace => "<unsubscribe_link>" }
     def sendgrid_subscriptiontrack_text(texts)
       self.default_subscriptiontrack_text = texts
     end
-    
+
     # Sets the default footer text (must be enabled).
-    # Should be a hash containing the html/plain text versions: 
+    # Should be a hash containing the html/plain text versions:
     #   {:html => "html version", :plain => "plan text version"}
     def sendgrid_footer_text(texts)
       self.default_footer_text = texts
@@ -80,6 +89,11 @@ module SendGrid
     def sendgrid_spamcheck_maxscore(score)
       self.default_spamcheck_score = score
     end
+
+    # Sets the default unique arguments to send
+    def sendgrid_unique_args(unique_args = {})
+      self.default_sg_unique_args = unique_args
+    end
   end
 
   # Call within mailer method to override the default value.
@@ -87,12 +101,17 @@ module SendGrid
     @sg_category = category
   end
 
+  # Call within mailer method to add/override unique arguments in the defaults
+  def sendgrid_unique_args(unique_args = {})
+    @sg_unique_args = unique_args
+  end
+
   # Call within mailer method to add an option not in the defaults.
   def sendgrid_enable(*options)
     @sg_options = Array.new unless @sg_options
     options.each { |option| @sg_options << option if VALID_OPTIONS.include?(option) }
   end
-  
+
   # Call within mailer method to remove one of the defaults.
   def sendgrid_disable(*options)
     @sg_disabled_options = Array.new unless @sg_disabled_options
@@ -104,7 +123,7 @@ module SendGrid
     @sg_recipients = Array.new unless @sg_recipients
     @sg_recipients = emails
   end
-  
+
   # Call within mailer method to add an array of substitions
   # NOTE: you must ensure that the length of the substitions equals the
   #       length of the sendgrid_recipients.
@@ -128,6 +147,13 @@ module SendGrid
     @spamcheck_score = score
   end
 
+  # Call within mailer method to set custom google analytics options
+  # http://sendgrid.com/documentation/appsGoogleAnalytics
+  def sendgrid_ganalytics_options(options)
+    @ganalytics_options = []
+    options.each { |option| @ganalytics_options << option if VALID_GANALYTICS_OPTIONS.include?(option[0].to_sym) }
+  end
+
   # Call within mailer method to set unique args for this email.
   def sendgrid_unique_args(args)
     @sg_unique_args = args
@@ -154,7 +180,7 @@ module SendGrid
   else
 
     # Sets the custom X-SMTPAPI header after creating the email but before delivery
-    # NOTE: This override is used for Rails 2 ActionMailer classes. 
+    # NOTE: This override is used for Rails 2 ActionMailer classes.
     def create!(method_name, *parameters)
       super
       if @sg_substitutions && !@sg_substitutions.empty?
@@ -174,6 +200,14 @@ module SendGrid
   def sendgrid_json_headers(mail)
     header_opts = {}
 
+    # set the unique arguments
+    if @sg_unique_args || self.class.default_sg_unique_args
+      unique_args = self.class.default_sg_unique_args || {}
+      unique_args = unique_args.merge(@sg_unique_args)
+
+      header_opts[:unique_args] = unique_args
+    end
+
     # Set category
     if @sg_category && @sg_category == :use_subject_lines
       header_opts[:category] = mail.subject
@@ -184,12 +218,12 @@ module SendGrid
     elsif self.class.default_sg_category
       header_opts[:category] = self.class.default_sg_category
     end
-    
+
     # Set multi-recipients
     if @sg_recipients && !@sg_recipients.empty?
       header_opts[:to] = @sg_recipients
     end
-    
+
     # Set custom substitions
     if @sg_substitutions && !@sg_substitutions.empty?
       header_opts[:sub] = @sg_substitutions
@@ -214,10 +248,10 @@ module SendGrid
     if @sg_unique_args && !@sg_unique_args.empty?
       header_opts[:unique_args] = @sg_unique_args
     end
-    
+
     header_opts.to_json.gsub(/(["\]}])([,:])(["\[{])/, '\\1\\2 \\3')
   end
-  
+
   def filters_hash_from_options(enabled_opts, disabled_opts)
     filters = {}
     enabled_opts.each do |opt|
@@ -239,7 +273,7 @@ module SendGrid
               filters[:subscriptiontrack]['settings']['text/plain'] = self.class.default_subscriptiontrack_text[:plain]
             end
           end
-  
+
         when :footer
           if @footer_text
             filters[:footer]['settings']['text/html'] = @footer_text[:html]
@@ -248,21 +282,28 @@ module SendGrid
             filters[:footer]['settings']['text/html'] = self.class.default_footer_text[:html]
             filters[:footer]['settings']['text/plain'] = self.class.default_footer_text[:plain]
           end
-  
+
         when :spamcheck
           if self.class.default_spamcheck_score || @spamcheck_score
             filters[:spamcheck]['settings']['maxscore'] = @spamcheck_score || self.class.default_spamcheck_score
           end
+
+        when :ganalytics
+          if @ganalytics_options
+            @ganalytics_options.each do |key, value|
+              filters[:ganalytics]['settings'][key.to_s] = value
+            end
+          end
       end
     end
-    
+
     if disabled_opts
       disabled_opts.each do |opt|
         filters[opt] = {'settings' => {'enable' => 0}}
       end
     end
-    
+
     return filters
   end
-  
+
 end

data/sendgrid.gemspec

@@ -4,15 +4,14 @@
 # -*- encoding: utf-8 -*-
 
 Gem::Specification.new do |s|
-  s.name = %q{sendgrid}
-  s.version = "1.0.1"
+  s.name = "sendgrid"
+  s.version = "1.1.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
-  s.authors = ["Stephen Blankenship"]
-  s.date = %q{2011-09-08}
-  s.description = %q{This gem allows simple integration between ActionMailer and SendGrid. 
-                         SendGrid is an email deliverability API that is affordable and has lots of bells and whistles.}
-  s.email = %q{stephenrb@gmail.com}
+  s.authors = ["Stephen Blankenship", "Marc Tremblay", "Bob Burbach"]
+  s.date = "2012-10-05"
+  s.description = "This gem allows simple integration between ActionMailer and SendGrid. \n                         SendGrid is an email deliverability API that is affordable and has lots of bells and whistles."
+  s.email = "stephenrb@gmail.com"
   s.extra_rdoc_files = [
     "LICENSE",
     "README.md"
@@ -30,20 +29,15 @@ Gem::Specification.new do |s|
     "test/sendgrid_test.rb",
     "test/test_helper.rb"
   ]
-  s.homepage = %q{http://github.com/stephenb/sendgrid}
+  s.homepage = "http://github.com/stephenb/sendgrid"
   s.require_paths = ["lib"]
-  s.rubygems_version = %q{1.3.6}
-  s.summary = %q{A gem that allows simple integration of ActionMailer with SendGrid (http://sendgrid.com)}
-  s.test_files = [
-    "test/sendgrid_test.rb",
-    "test/test_helper.rb"
-  ]
+  s.rubygems_version = "1.8.24"
+  s.summary = "A gem that allows simple integration of ActionMailer with SendGrid (http://sendgrid.com)"
 
   if s.respond_to? :specification_version then
-    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
     s.specification_version = 3
 
-    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
       s.add_runtime_dependency(%q<json>, [">= 0"])
       s.add_development_dependency(%q<bundler>, ["~> 1.0.0"])
       s.add_development_dependency(%q<jeweler>, ["~> 1.5.1"])

metadata

@@ -1,86 +1,92 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: sendgrid
-version: !ruby/object:Gem::Version 
-  prerelease: false
-  segments: 
-  - 1
-  - 0
-  - 1
-  version: 1.0.1
+version: !ruby/object:Gem::Version
+  version: 1.1.0
+  prerelease: 
 platform: ruby
-authors: 
+authors:
 - Stephen Blankenship
+- Marc Tremblay
+- Bob Burbach
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2011-09-08 00:00:00 -05:00
-default_executable: 
-dependencies: 
-- !ruby/object:Gem::Dependency 
-  type: :runtime
+date: 2012-10-05 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
   name: json
-  version_requirements: &id001 !ruby/object:Gem::Requirement 
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        segments: 
-        - 0
-        version: "0"
-  requirement: *id001
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
   prerelease: false
-- !ruby/object:Gem::Dependency 
-  type: :development
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
   name: bundler
-  version_requirements: &id002 !ruby/object:Gem::Requirement 
-    requirements: 
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        segments: 
-        - 1
-        - 0
-        - 0
+      - !ruby/object:Gem::Version
         version: 1.0.0
-  requirement: *id002
-  prerelease: false
-- !ruby/object:Gem::Dependency 
   type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+- !ruby/object:Gem::Dependency
   name: jeweler
-  version_requirements: &id003 !ruby/object:Gem::Requirement 
-    requirements: 
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        segments: 
-        - 1
-        - 5
-        - 1
+      - !ruby/object:Gem::Version
         version: 1.5.1
-  requirement: *id003
+  type: :development
   prerelease: false
-- !ruby/object:Gem::Dependency 
-  type: :runtime
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.5.1
+- !ruby/object:Gem::Dependency
   name: json
-  version_requirements: &id004 !ruby/object:Gem::Requirement 
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        segments: 
-        - 0
-        version: "0"
-  requirement: *id004
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
   prerelease: false
-description: |-
-  This gem allows simple integration between ActionMailer and SendGrid. 
-                           SendGrid is an email deliverability API that is affordable and has lots of bells and whistles.
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: ! "This gem allows simple integration between ActionMailer and SendGrid.
+  \n                         SendGrid is an email deliverability API that is affordable
+  and has lots of bells and whistles."
 email: stephenrb@gmail.com
 executables: []
-
 extensions: []
-
-extra_rdoc_files: 
+extra_rdoc_files:
 - LICENSE
 - README.md
-files: 
+files:
 - .document
 - Gemfile
 - Gemfile.lock
@@ -92,36 +98,28 @@ files:
 - sendgrid.gemspec
 - test/sendgrid_test.rb
 - test/test_helper.rb
-has_rdoc: true
 homepage: http://github.com/stephenb/sendgrid
 licenses: []
-
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      segments: 
-      - 0
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      segments: 
-      - 0
-      version: "0"
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
 rubyforge_project: 
-rubygems_version: 1.3.6
+rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
 summary: A gem that allows simple integration of ActionMailer with SendGrid (http://sendgrid.com)
-test_files: 
-- test/sendgrid_test.rb
-- test/test_helper.rb
+test_files: []