sendgrid-rails

sendgrid-rails copied to clipboard

= SendGrid gem for Rails 3 {}[http://travis-ci.org/PavelTyk/sendgrid-rails]

SendGrid gem provides ActionMailer::Base extensions to use SendGrid API features in you emails. It extends ActionMailer with next methods:

substitute(patters_string, array_of_substitunion_strings)
uniq_args(hash_of_unique_args)
category(category_string)
open_tracking(enabled = true)
add_filter_setting(filter_name, setting_name, value)

== Rails 3 configuration

In your Gemfile:

gem 'sendgrid-rails', '~> 2.0'

In config/initializers/mail.rb:

ActionMailer::Base.register_interceptor(SendGrid::MailInterceptor)

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

If you use Heroku, here what the mailer initializer may look like:

ActionMailer::Base.register_interceptor(SendGrid::MailInterceptor)

if ENV['SENDGRID_USERNAME'] && ENV['SENDGRID_PASSWORD']
  ActionMailer::Base.smtp_settings = {
    :address        => 'smtp.sendgrid.net',
    :port           => '465',
    :authentication => :plain,
    :user_name      => ENV['SENDGRID_USERNAME'],
    :password       => ENV['SENDGRID_PASSWORD'],
    :domain         => 'heroku.com',
    :enable_starttls_auto => true,
    :ssl => true
  }
  ActionMailer::Base.delivery_method = :smtp
end

=== Overriding default recipient in standard SMTP header

Dummy recipient email used in sent email's "To" header and seen in received email's Received header. By default set to '[email protected]'

In config/initializers/mail.rb:

SendGrid.configure do |config|
  config.dummy_recipient = '[email protected]'
end

== Usage examples

=== Adding multiple recipients:

class Mailer < ActionMailer::Base
  default :from => '[email protected]',
          :subject => 'An email sent via SendGrid'

  def email_with_multiple_recipients
    mail :to => %w([email protected] [email protected])
  end
end

=== Adding substitution vars

Mailer class definition:

class Mailer < ActionMailer::Base
  default :from => '[email protected]',
          :subject => 'An email sent via SendGrid with substitutions'

  def email_with_substitutions
    substitute '-user_name-', %w(User1 User2)

    mail :to => %w([email protected] [email protected]), :body => "Hello, -user_name-!"
  end
end

=== Adding category

Mailer class definition:

class Mailer < ActionMailer::Base
  default :from => '[email protected]',
          :subject => 'An email sent via SendGrid with substitutions'

  def email_with_category
    category 'SendGridRocks'
    mail :to => '[email protected]'
  end
end

== Apps (formerly called Filters)

Apps can be applied to any of your email messages and can be configured through SendGrid gem.

=== Open Tracking

Add an invisible image at the end of the email to track e-mail opens. If the email recipient has images enabled on the email client, a request to server for the invisible image is executed and an open is logged.

class Mailer < ActionMailer::Base
  default :from => '[email protected]',
          :subject => 'An email sent via SendGrid'

  def email_with_open_tracking_enabled
    open_tracking true
    mail :to => '[email protected]'
  end
end

== Change log

v3.1.0

• Introduced template_id feature

v3.0.0

• Depricated method :alias_method_chain has been replaced with Module#prepend Ruby 2.0 feature
• Requires Ruby 2.0+

v2.0.5

• Introduced deliver_at feature.

v2.0.4

• CC and BCC are copied to SendGrid XSMTP-API header

v2.0.3

• Ability to change "dummy_recipient" in config

v2.0.2

• ApiHeader#to_json wraps array items with spaces

v2.0.1

• Standard SMTP To attribute set to '[email protected]' after recipients added to X-SMTPAPI header

v2.0

• Using mail interceptor
• ActionMailer::Base#add_recipients - removed
• Standard SMTP To attribute get nullified after recipients added to X-SMTPAPI header