Skip to content

Latest commit

 

History

History
155 lines (104 loc) · 4.18 KB

README.rdoc

File metadata and controls

155 lines (104 loc) · 4.18 KB
Raw

SendGrid gem for Rails 3 <img src=“https://secure.travis-ci.org/PavelTyk/sendgrid-rails.png” /> ↑

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 => 'login@example.com',
  :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 ‘dummy@email.com’

In config/initializers/mail.rb:

SendGrid.configure do |config|
  config.dummy_recipient = 'noreply@example.com'
end

Usage examples ↑

Adding multiple recipients: ↑

class Mailer < ActionMailer::Base
  default :from => 'no-reply@example.com',
          :subject => 'An email sent via SendGrid'

  def email_with_multiple_recipients
    mail :to => %w(email1@email.com email2@email.com)
  end
end

Adding substitution vars ↑

Mailer class definition:

class Mailer < ActionMailer::Base
  default :from => 'no-reply@example.com',
          :subject => 'An email sent via SendGrid with substitutions'

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

    mail :to => %w(email1@email.com email2@email.com), :body => "Hello, -user_name-!"
  end
end

Adding category ↑

Mailer class definition:

class Mailer < ActionMailer::Base
  default :from => 'no-reply@example.com',
          :subject => 'An email sent via SendGrid with substitutions'

  def email_with_category
    category 'SendGridRocks'
    mail :to => 'email1@email.com'
  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 => 'no-reply@example.com',
          :subject => 'An email sent via SendGrid'

  def email_with_open_tracking_enabled
    open_tracking true
    mail :to => 'email@email.com'
  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 ‘dummy@email.com’ 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