Mail::SES

Mail::SES is a mail delivery method handler for Amazon SES (Simple Email Service) which can be used with Rails' Action Mailer.

This gem is inspired by Drew Blas' AWS::SES gem, but uses the official AWS SDK v3 for SES under-the-hood. By passing parameters through to the SDK, this gem supports greater flexibility with less code (including IAM instance profiles, retry parameters, etc.)

Compatibility

Ruby 2.1+
Ruby on Rails 3.2+
AWS SDK v3

Shameless Plug

ActionMailer::SES is sponsored by TableCheck, Japan's leading restaurant management app. If you are a ninja-level Javascript/Ruby coder, designer, project manager, etc. and are eager to work in Tokyo with other ninjas, Japan in a dynamic environment, please get in touch at [email protected].

Getting Started

In your Gemfile:

gem 'mail-ses'

Next, make a new initializer at config/initializers/mail_ses.rb:

ActionMailer::Base.add_delivery_method :ses, Mail::SES,
    region: 'us-east-1',
    access_key_id: 'abc',
    secret_access_key: '123'

Finally, in the appropriate config/environments/*.rb:

config.action_mailer.delivery_method = :ses

Advanced Usage

AWS SES Client Options

Any options supported by the Aws::SES::Client class can be passed into the initializer, for example:

ActionMailer::Base.add_delivery_method :ses, Mail::SES,
    region: 'us-east-1',
    session_token: 'foobar',
    retry_limit: 5,
    retry_max_delay: 10

In addition, the shortcut option :use_iam_profile (Boolean) which activates the IAM instance profile.

ActionMailer::Base.add_delivery_method :ses, Mail::SES,
    region: 'us-east-1',
    use_iam_profile: true

Default Mail Options

In the initializer you can set :mail_options (Hash) which are default options to pass-through to each mail sent:

ActionMailer::Base.add_delivery_method :ses, Mail::SES,
    # ...
    mail_options: {
      source_arn: 'arn:aws:ses:us-east-1:123456789012:identity/example.com',
      tags: [
        { name: 'MessageTagName', value: 'MessageTagValue' },
      ],
    }

AWS Error Handling

To handle errors from AWS API, in the initializer you can set :error_handler (Proc) which takes two args: the error which was raised, and the raw_email options hash. This is useful for notifying your bug tracking service. Setting :error_handler causes the error to be swallowed unless it is raised again in the handler itself.

ActionMailer::Base.add_delivery_method :ses, Mail::SES,
    # ...
    error_handler: ->(error, raw_email) do
      Bugsnag.notify(error){|r| r.add_tab('email', { email: raw_email })}
      raise error    
    end

Send Email as a Standalone

You can send one-off mails using the Mail::SES object and #deliver method.

mail = Mail.new(args)

ses  = Mail::SES.new(region: 'us-east-1',
                     access_key_id: 'abc',
                     secret_access_key: '123')

options = { source_arn: 'arn:aws:ses:us-east-1:123456789012:identity/example.com' }

ses.deliver!(mail, options) #=> returns AWS API response

mail.message_id #=> "00000138111222aa-33322211-cccc-cccc-cccc-ddddaaaa0680-000000@email.amazonses.com"

Please also see the AWS SDK v3 for SES for alternate approaches.

Statistics, Verified Addresses, Bounce Rate, etc.

Please use the official AWS SDK v3 for SES.