rmm5t-sendgrid 0.1.0.20090110

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,5 @@
+*.sw?
+.DS_Store
+coverage
+rdoc
+pkg

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Stephen Blankenship
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.textile

@@ -0,0 +1,123 @@
+h1. sendgrid
+
+h3. What is SendGrid?
+
+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.
+* :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.
+

data/Rakefile

@@ -0,0 +1,58 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "rmm5t-sendgrid"
+    gem.summary = %Q{A gem that allows simple integration of ActionMailer with SendGrid (http://sendgrid.com)}
+    gem.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.}
+    gem.email = "stephenrb@gmail.com"
+    gem.homepage = "http://github.com/rmm5t/sendgrid"
+    gem.authors = ["Stephen Blankenship"]
+    # gem.add_development_dependency "thoughtbot-shoulda"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/*_test.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+task :test => :check_dependencies
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  if File.exist?('VERSION')
+    version = File.read('VERSION')
+  else
+    version = ""
+  end
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "sendgrid #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0.20090110

data/lib/sendgrid.rb

@@ -0,0 +1,210 @@
+require 'json'
+
+module SendGrid
+
+  VALID_OPTIONS = [
+    :opentrack,
+    :clicktrack,
+    :ganalytics,
+    :gravatar,
+    :subscriptiontrack,
+    :footer,
+    :spamcheck
+  ]
+  
+  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
+      end
+      attr_accessor :sg_category, :sg_options, :sg_disabled_options, :sg_recipients, :sg_substitutions, :subscriptiontrack_text, :footer_text, :spamcheck_score
+    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
+    # can still be overridden by calling sendgrid_category from within a
+    # mailer method.
+    def sendgrid_category(category)
+      self.default_sg_category = category
+    end
+    
+    # Enables a default option for all emails.
+    # See documentation for details.
+    #
+    # Supported options:
+    # * :opentrack
+    # * :clicktrack
+    # * :ganalytics
+    # * :gravatar
+    # * :subscriptiontrack
+    # * :footer
+    # * :spamcheck
+    def sendgrid_enable(*options)
+      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).
+    # Should be a hash containing the html/plain text versions: 
+    #   {:html => "html version", :plain => "plan text version"}
+    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: 
+    #   {:html => "html version", :plain => "plan text version"}
+    def sendgrid_footer_text(texts)
+      self.default_footer_text = texts
+    end
+
+    # Sets the default spamcheck score text (must be enabled).
+    def sendgrid_spamcheck_maxscore(score)
+      self.default_spamcheck_score = score
+    end
+  end
+
+  # Call within mailer method to override the default value.
+  def sendgrid_category(category)
+    @sg_category = category
+  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
+    options.each { |option| @sg_disabled_options << option if VALID_OPTIONS.include?(option) }
+  end
+
+  # Call within mailer method to add an array of recipients
+  def sendgrid_recipients(emails)
+    @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.
+  def sendgrid_substitute(placeholder, subs)
+    @sg_substitutions = Hash.new unless @sg_substitutions
+    @sg_substitutions[placeholder] = subs
+  end
+
+  # Call within mailer method to override the default value.
+  def sendgrid_subscriptiontrack_text(texts)
+    @subscriptiontrack_text = texts
+  end
+
+  # Call within mailer method to override the default value.
+  def sendgrid_footer_text(texts)
+    @footer_text = texts
+  end
+
+  # Call within mailer method to override the default value.
+  def sendgrid_spamcheck_maxscore(score)
+    @spamcheck_score = score
+  end
+
+  # Sets the custom X-SMTPAPI header after creating the email but before delivery
+  def create!(method_name, *parameters)
+    super
+    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
+
+  private
+
+  # Take all of the options and turn it into the json format that SendGrid expects
+  def sendgrid_json_headers(mail)
+    header_opts = {}
+
+    # Set category
+    if @sg_category && @sg_category == :use_subject_lines
+      header_opts[:category] = mail.subject
+    elsif @sg_category
+      header_opts[:category] = @sg_category
+    elsif self.class.default_sg_category && self.class.default_sg_category.to_sym == :use_subject_lines
+      header_opts[:category] = mail.subject
+    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
+    end
+
+    # Set enables/disables
+    header_opts[:filters] = {} unless header_opts.has_key?(:filters)
+    enabled_opts = []
+    if @sg_options && !@sg_options.empty?
+      # merge the options so that the instance-level "overrides"
+      merged = self.class.default_sg_options || []
+      merged += @sg_options
+      enabled_opts = merged
+    elsif self.class.default_sg_options
+      enabled_opts = self.class.default_sg_options
+    end
+    if !enabled_opts.empty? || (@sg_disabled_options && !@sg_disabled_options.empty?)
+      header_opts[:filters] = filters_hash_from_options(enabled_opts, @sg_disabled_options)
+    end
+    
+    header_opts.to_json
+  end
+  
+  def filters_hash_from_options(enabled_opts, disabled_opts)
+    filters = {}
+    enabled_opts.each do |opt|
+      filters[opt] = {'settings' => {'enable' => 1}}
+      case opt.to_sym
+        when :subscriptiontrack
+          if @subscriptiontrack_text
+            filters[:subscriptiontrack]['settings']['text/html'] = @subscriptiontrack_text[:html]
+            filters[:subscriptiontrack]['settings']['text/plain'] = @subscriptiontrack_text[:plain]
+          elsif self.class.default_subscriptiontrack_text
+            filters[:subscriptiontrack]['settings']['text/html'] = self.class.default_subscriptiontrack_text[:html]
+            filters[:subscriptiontrack]['settings']['text/plain'] = self.class.default_subscriptiontrack_text[:plain]
+          end
+  
+        when :footer
+          if @footer_text
+            filters[:footer]['settings']['text/html'] = @footer_text[:html]
+            filters[:footer]['settings']['text/plain'] = @footer_text[:plain]
+          elsif self.class.default_footer_text
+            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
+      end
+    end
+    
+    if disabled_opts
+      disabled_opts.each do |opt|
+        filters[opt] = {'settings' => {'enable' => 0}}
+      end
+    end
+    
+    return filters
+  end
+  
+end

data/test/sendgrid_test.rb

@@ -0,0 +1,7 @@
+require 'test_helper'
+
+class SendgridTest < Test::Unit::TestCase
+  should "probably rename this file and start testing for real" do
+    flunk "hey buddy, you should probably rename this file and start testing for real"
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,10 @@
+require 'rubygems'
+require 'test/unit'
+require 'shoulda'
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'sendgrid'
+
+class Test::Unit::TestCase
+end

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification 
+name: rmm5t-sendgrid
+version: !ruby/object:Gem::Version 
+  version: 0.1.0.20090110
+platform: ruby
+authors: 
+- Stephen Blankenship
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-01-10 00:00:00 -05:00
+default_executable: 
+dependencies: []
+
+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.
+email: stephenrb@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.textile
+files: 
+- .document
+- .gitignore
+- LICENSE
+- README.textile
+- Rakefile
+- VERSION
+- lib/sendgrid.rb
+- test/sendgrid_test.rb
+- test/test_helper.rb
+has_rdoc: true
+homepage: http://github.com/rmm5t/sendgrid
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+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