sendgrid

About this fork

This fork improves the sendgrid gem by adding a gemspec for Bundler compatibility (via Ryan Bigg). This fork is expected
to work on Rails 2.3.

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 to learn more.

Getting Started

First of all, you’ll need the gem. Add sendgrid to Gemfile:

gem 'sendgrid', :git => 'git://github.com/jeremyw/sendgrid.git'

Then run bundle install.

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 (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 for instructions).

Example:

ActionMailer::Base.smtp_settings = {
  :address => "smtp.sendgrid.net",
  :port => 25,
  :domain => "mysite.com",
  :authentication => :plain,
  :user_name => "[email protected]",
  :password => "sendgrid_password"
}

Using the sendgrid Gem

If you do not already have an ActionMailer class up and running, then check out this guide.

1) add the following line within your mailer class:

include SendGrid

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:

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

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:

sendgrid_category :use_subject_lines

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.

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.

sendgrid_recipients ["email1blah.com", “[email protected]”, “[email protected]”, …]@

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_substitue "<subme>", ["sub text for 1st recipient", "sub text for 2nd recipient", "sub text for 3rd recipient", ...]

In this example, if <subme> 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.