Gem Version Travis Status

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 #=> "[email protected]il.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.

Copyright (c) 2018 TableCheck Inc. See LICENSE for further details.