sendgrid 0.2.0 → 1.0.0

data/README.md

@@ -0,0 +1,120 @@
+sendgrid
+=========
+
+_Now updated to work with Rails 3._
+
+What is SendGrid?
+-----------------
+
+SendGrid is an awesome service that helps you send large amounts of email (bells and whistles included) without spending large amounts of money. This gem allows for painless integration between ActionMailer and the SendGrid SMTP API. The current scope of this gem is focused around setting configuration options for outgoing email (essentially, setting categories, filters and the settings that can accompany those filters). SendGrid's service allows for some other cool stuff (such as postback notification of unsubscribes, bounces, etc.), but those features are currently outside the scope of this gem.
+
+Visit [SendGrid](http://sendgrid.com) to learn more.
+
+Getting Started
+---------------
+
+First of all, you'll need the gem. It's at http://rubygems.org/gems/sendgrid. If you're using Bundler, just add the following to your Gemfile.
+
+    gem 'sendgrid'
+
+
+Before you can do anything with the sendgrid gem, you'll need to create your very own SendGrid account. Go ahead and do so at [http://sendgrid.com](http://sendgrid.com) (there's even a FREE account option).
+
+Next, update your application's SMTP settings to use SendGrid's servers (see [SendGrid's getting started guide](http://wiki.sendgrid.com/doku.php?id=get_started) for instructions).
+
+Example:
+
+    ActionMailer::Base.smtp_settings = {
+      :address => "smtp.sendgrid.net",
+      :port => 25,
+      :domain => "mysite.com",
+      :authentication => :plain,
+      :user_name => "sendgrd_username@mysite.com",
+      :password => "sendgrid_password"
+    }
+
+Using the sendgrid Gem
+----------------------
+
+If you do not already have an ActionMailer class up and running, then check out [this guide.](http://guides.rubyonrails.org/action_mailer_basics.html#walkthrough-to-generating-a-mailer)
+
+1) add the following line within your mailer class:
+
+    include SendGrid
+
+
+2) customize your sendgrid settings:
+
+There are 2 main types of settings
+
+* Category settings
+* Enable/disable settings
+
+You can set both global and per-email settings - the same syntax is used in either case.
+Here is an example of what typical usage may look like:
+
+    class MyMailer < ActionMailer::Base
+      include SendGrid
+      sendgrid_category :use_subject_lines
+      sendgrid_enable   :ganalytics, :opentracking
+  
+      def welcome_message(user)
+        sendgrid_category "Welcome"
+        mail :to => user.email, :subject => "Welcome #{user.name} :-)"
+      end
+  
+      def goodbye_message(to_user)
+        sendgrid_disable :ganalytics
+        mail :to => user.email, :subject => "Fare thee well :-("
+      end
+    end
+
+Category settings can be any text you like and SendGrid's website will allow you to view email statistics per-category (very nice). There is also a custom global setting that will automatically use the subject line of each email as the sendgrid\_category:
+
+    sendgrid_category :use_subject_lines
+
+If you have any dynamic subject lines, you'll want to override this setting within the mailer method. Calling sendgrid\_category from within one of your mailer methods will override this global setting. Similarly, calling sendgrid\_enable/sendgrid\_disable from within a mailer method will add or remove from any defaults that may have been set globally.
+
+Here are a list of supported options for sendgrid\_enable and sendgrid\_disable:
+
+* :opentrack
+* :clicktrack
+* :ganalytics
+* :gravatar
+* :subscriptiontrack
+  * Call sendgrid\_subscriptiontrack\_text(:html => 'Unsubscribe <% Here %>', :plain => 'Unsubscribe Here: <% %>') to set a custom format for html/plain or both.
+  * OR Call sendgrid\_subscriptiontrack\_text(:replace => '|unsubscribe\_link|') to replace all occurrences of |unsubscribe\_link| with the url of the unsubscribe link
+* :footer
+  * 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)
+
+
+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. 
+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.
+
+
+    sendgrid_recipients ["email1@blah.com", "email2@blah.com", "email3@blah.com", ...]
+
+
+One issue that arises when delivering multiple emails at once is custom content. Luckily, there is also a per-mailer-method setting that can be used to substitute custom content.
+
+
+    sendgrid_substitute "|subme|", ["sub text for 1st recipient", "sub text for 2nd recipient", "sub text for 3rd recipient", ...]
+
+
+In this example, if <code>|subme|</code> is in the body of your email SendGrid will automatically substitute it for the string corresponding the recipient being delivered to. NOTE: You should ensure that the length of the substitution array is equal to the length of the recipients array.
+
+
+TODO
+----
+
+* Test coverage (I would appreciate help writing tests).
+* Possibly integrate with SendGrid's Event API and some of the other goodies they provide.
+

data/VERSION

@@ -1 +1 @@
-0.2.0
+1.0.0

data/lib/sendgrid.rb

@@ -128,32 +128,43 @@ module SendGrid
     @spamcheck_score = score
   end
 
-  # Sets the custom X-SMTPAPI header after creating the email but before delivery
-  # NOTE: This override is used for Rails 2 ActionMailer classes. 
-  def create!(method_name, *parameters)
-    super
-    if @sg_substitutions && !@sg_substitutions.empty?
-      @sg_substitutions.each do |find, replace|
-        raise ArgumentError.new("Array for #{find} is not the same size as the recipient array") if replace.size != @sg_recipients.size
+  # Call within mailer method to set unique args for this email.
+  def sendgrid_unique_args(args)
+    @sg_unique_args = args
+  end
+
+  # only override the appropriet methods for the current rails version
+  if Rails.version < '3.0.0'
+
+    # Sets the custom X-SMTPAPI header after creating the email but before delivery
+    # NOTE: This override is used for Rails 2 ActionMailer classes. 
+    def create!(method_name, *parameters)
+      super
+      if @sg_substitutions && !@sg_substitutions.empty?
+        @sg_substitutions.each do |find, replace|
+          raise ArgumentError.new("Array for #{find} is not the same size as the recipient array") if replace.size != @sg_recipients.size
+        end
       end
+      puts "SendGrid X-SMTPAPI: #{sendgrid_json_headers(mail)}" if Object.const_defined?("SENDGRID_DEBUG_OUTPUT") && SENDGRID_DEBUG_OUTPUT
+      @mail['X-SMTPAPI'] = sendgrid_json_headers(mail)
     end
-    puts "SendGrid X-SMTPAPI: #{sendgrid_json_headers(mail)}" if Object.const_defined?("SENDGRID_DEBUG_OUTPUT") && SENDGRID_DEBUG_OUTPUT
-    @mail['X-SMTPAPI'] = sendgrid_json_headers(mail)
-  end
-  
-  protected
-  
-  # Sets the custom X-SMTPAPI header after creating the email but before delivery
-  # NOTE: This override is used for Rails 3 ActionMailer classes.
-  def mail(headers={}, &block)
-    super
-    if @sg_substitutions && !@sg_substitutions.empty?
-      @sg_substitutions.each do |find, replace|
-        raise ArgumentError.new("Array for #{find} is not the same size as the recipient array") if replace.size != @sg_recipients.size
+
+  else
+
+    protected
+
+    # Sets the custom X-SMTPAPI header after creating the email but before delivery
+    # NOTE: This override is used for Rails 3 ActionMailer classes.
+    def mail(headers={}, &block)
+      super
+      if @sg_substitutions && !@sg_substitutions.empty?
+        @sg_substitutions.each do |find, replace|
+          raise ArgumentError.new("Array for #{find} is not the same size as the recipient array") if replace.size != @sg_recipients.size
+        end
       end
+      puts "SendGrid X-SMTPAPI: #{sendgrid_json_headers(message)}" if Object.const_defined?("SENDGRID_DEBUG_OUTPUT") && SENDGRID_DEBUG_OUTPUT
+      self.headers['X-SMTPAPI'] = sendgrid_json_headers(message)
     end
-    puts "SendGrid X-SMTPAPI: #{sendgrid_json_headers(message)}" if Object.const_defined?("SENDGRID_DEBUG_OUTPUT") && SENDGRID_DEBUG_OUTPUT
-    self.headers['X-SMTPAPI'] = sendgrid_json_headers(message)
   end
 
   private
@@ -197,6 +208,11 @@ module SendGrid
     if !enabled_opts.empty? || (@sg_disabled_options && !@sg_disabled_options.empty?)
       header_opts[:filters] = filters_hash_from_options(enabled_opts, @sg_disabled_options)
     end
+
+    # Set unique_args
+    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

data/sendgrid.gemspec

@@ -5,24 +5,24 @@
 
 Gem::Specification.new do |s|
   s.name = %q{sendgrid}
-  s.version = "0.2.0"
+  s.version = "1.0.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Stephen Blankenship"]
-  s.date = %q{2011-05-05}
+  s.date = %q{2011-06-09}
   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.extra_rdoc_files = [
     "LICENSE",
-    "README.textile"
+    "README.md"
   ]
   s.files = [
     ".document",
     "Gemfile",
     "Gemfile.lock",
     "LICENSE",
-    "README.textile",
+    "README.md",
     "Rakefile",
     "VERSION",
     "lib/sendgrid.rb",
@@ -32,7 +32,7 @@ Gem::Specification.new do |s|
   ]
   s.homepage = %q{http://github.com/stephenb/sendgrid}
   s.require_paths = ["lib"]
-  s.rubygems_version = %q{1.5.3}
+  s.rubygems_version = %q{1.3.7}
   s.summary = %q{A gem that allows simple integration of ActionMailer with SendGrid (http://sendgrid.com)}
   s.test_files = [
     "test/sendgrid_test.rb",
@@ -40,6 +40,7 @@ Gem::Specification.new do |s|
   ]
 
   if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
     s.specification_version = 3
 
     if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then

metadata

@@ -1,8 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: sendgrid
 version: !ruby/object:Gem::Version 
-  prerelease: 
-  version: 0.2.0
+  hash: 23
+  prerelease: false
+  segments: 
+  - 1
+  - 0
+  - 0
+  version: 1.0.0
 platform: ruby
 authors: 
 - Stephen Blankenship
@@ -10,53 +15,69 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-05-05 00:00:00 -05:00
+date: 2011-06-09 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
+  prerelease: false
+  type: :runtime
   name: json
-  requirement: &id001 !ruby/object:Gem::Requirement 
+  version_requirements: &id001 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
         version: "0"
-  type: :runtime
-  prerelease: false
-  version_requirements: *id001
+  requirement: *id001
 - !ruby/object:Gem::Dependency 
+  prerelease: false
+  type: :development
   name: bundler
-  requirement: &id002 !ruby/object:Gem::Requirement 
+  version_requirements: &id002 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
       - !ruby/object:Gem::Version 
+        hash: 23
+        segments: 
+        - 1
+        - 0
+        - 0
         version: 1.0.0
-  type: :development
-  prerelease: false
-  version_requirements: *id002
+  requirement: *id002
 - !ruby/object:Gem::Dependency 
+  prerelease: false
+  type: :development
   name: jeweler
-  requirement: &id003 !ruby/object:Gem::Requirement 
+  version_requirements: &id003 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
       - !ruby/object:Gem::Version 
+        hash: 1
+        segments: 
+        - 1
+        - 5
+        - 1
         version: 1.5.1
-  type: :development
-  prerelease: false
-  version_requirements: *id003
+  requirement: *id003
 - !ruby/object:Gem::Dependency 
+  prerelease: false
+  type: :runtime
   name: json
-  requirement: &id004 !ruby/object:Gem::Requirement 
+  version_requirements: &id004 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
         version: "0"
-  type: :runtime
-  prerelease: false
-  version_requirements: *id004
+  requirement: *id004
 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.
@@ -67,13 +88,13 @@ extensions: []
 
 extra_rdoc_files: 
 - LICENSE
-- README.textile
+- README.md
 files: 
 - .document
 - Gemfile
 - Gemfile.lock
 - LICENSE
-- README.textile
+- README.md
 - Rakefile
 - VERSION
 - lib/sendgrid.rb
@@ -94,17 +115,23 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
       version: "0"
 required_rubygems_version: !ruby/object:Gem::Requirement 
   none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
       version: "0"
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.5.3
+rubygems_version: 1.3.7
 signing_key: 
 specification_version: 3
 summary: A gem that allows simple integration of ActionMailer with SendGrid (http://sendgrid.com)

data/README.textile

@@ -1,127 +0,0 @@
-h1. sendgrid
-
-h3. What is SendGrid?
-
-* NOTE: Now updated to work with Rails 3! *
-
-SendGrid is an awesome way to send large amounts of email (bells and whistles included) without spending large amounts of money. This gem allows for painless integration between ActionMailer and the SendGrid SMTP API. The current scope of this gem is focused around setting configuration options for outgoing email (essentially, setting categories, filters and the settings that can accompany those filters). SendGrid's service allows for some other cool stuff (such as postback notification of unsubscribes, bounces, etc.), but you'll have to integrate those features on your own.
-
-Visit "SendGrid":http://sendgrid.com to learn more.
-
-h3. Getting Started
-
-First of all, you'll need the gem. You can add sendgrid to your Rails requirements:
-<pre>
-  config.gem "sendgrid", :source => 'http://gemcutter.org'
-</pre>
-
-Or, you can install it as a gem:
-<pre>
-  # if you haven't already, add gemcutter to your gem sources
-  sudo gem install gemcutter
-  gem tumble
-  # install sendgrid
-  sudo gem install sendgrid
-</pre>
-
-Before you can do anything with the sendgrid gem, you'll need to create your very own SendGrid account. Go ahead and do so at "http://sendgrid.com":http://sendgrid.com (there's even a FREE account option).
-
-Next, update your application's SMTP settings to use SendGrid's servers (see "SendGrid's getting started guide":http://wiki.sendgrid.com/doku.php?id=get_started for instructions).
-
-Example:
-<pre>
-ActionMailer::Base.smtp_settings = {
-  :address => "smtp.sendgrid.net",
-  :port => 25,
-  :domain => "mysite.com",
-  :authentication => :plain,
-  :user_name => "sendgrd_username@mysite.com",
-  :password => "sendgrid_password"
-}
-</pre>
-
-h3. Using the sendgrid Gem
-
-If you do not already have an ActionMailer class up and running, then check out "this guide.":http://guides.rubyonrails.org/action_mailer_basics.html#walkthrough-to-generating-a-mailer
-
-1) add the following line within your mailer class:
-<pre>
-  include SendGrid
-</pre>
-
-2) customize your sendgrid settings:
-
-There are 2 types of settings
-- Category settings
-- Enable/disable settings
-
-You can set both global and per-email settings - the same syntax is used in either case.
-Here is an example of what typical usage may look like:
-
-<pre>
-class MyMailer < ActionMailer::Base
-  include SendGrid
-  sendgrid_category :use_subject_lines
-  sendgrid_enable   :ganalytics, :opentracking
-  
-  def welcome_message(to_user)
-    sendgrid_category "Welcome"
-    
-    recipients to_user.email
-    subject "Welcome :-)"
-    body :to_user => to_user
-  end
-  
-  def goodbye_message(to_user)
-    sendgrid_disable :ganalytics
-    
-    recipients to_user.email
-    subject "Fare thee well :-("
-    body :to_user => to_user
-  end
-end
-</pre>
-
-Category settings can be any text you like and will allow you to view statistics per-category (very nice). There is also a custom global setting that will automatically use the subject-line of your email as the sendgrid_category:
-<pre>
-  sendgrid_category :use_subject_lines
-</pre>
-Calling sendgrid_cateogry from within one of your mailer methods will override this global setting. Similarly, calling sendgrid_enable/sendgrid_disable from within a mailer method will add or remove from any defaults that may have been set globally.
-
-Here are a list of supported options for sendgrid_enable and sendgrid_disable:
-* :opentrack
-* :clicktrack
-* :ganalytics
-* :gravatar
-* :subscriptiontrack
-** Call sendgrid_subscriptiontrack_text(:html => 'Unsubscribe <% Here %>', :plain => 'Unsubscribe Here: <% %>') to set a custom format for html/plain or both.
-** OR Call sendgrid_subscriptiontrack_text(:replace => '.unsubscribe_link.') to replace all occurrences of .unsubscribe_link. with the url of the unsubscribe link
-
-* :footer
-** 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
-
-h3. Delivering to multiple recipients
-
-There is a per-mailer-method setting that can be used to deliver campaigns to multiple recipients at once. You should still set the "recipients" to an address per the normal ActionMailer usage, but it will not be used.
-
-<pre>
-  sendgrid_recipients ["email1@blah.com", "email2@blah.com", "email2@blah.com", ...]
-</pre>
-
-One issue that arises when delivering multiple emails at once is custom content. Luckily, there is also a per-mailer-method setting that can be used to substitute custom content.
-
-<pre>
-  sendgrid_substitue "<subme>", ["sub text for 1st recipient", "sub text for 2nd recipient", "sub text for 3rd recipient", ...]
-</pre>
-
-In this example, if <code><subme></code> is in the body of your email SendGrid will automatically substitute it for the string corresponding the recipient being delivered to. NOTE: You should ensure that the length of the substitution array is equal to the length of the recipients array.
-
-h3. TODO
-
-* Test coverage (I would appreciate help writing tests).
-* Possibly integrate with SendGrid's Event API and some of the other goodies they provide.
-