= SendGrid gem for Rails 3 {<img src="https://secure.travis-ci.org/PavelTyk/sendgrid-rails.png" />}[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 => 'login@example.com',
      :password => 'your password'
    }

=== 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 deefault 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

*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