ActionMailer delivery with Amazon Simple Email Service

This gem contains ActionMailer delivery method classes with Amazon SES and SESV2. See the API documentation for the full reference.

Installation

Add this gem to your Rails project's Gemfile:

gem 'aws-sdk-rails', '~> 5'
gem 'aws-actionmailer-ses', '~> 1'

Then run bundle install.

This gem also brings in the following AWS gems:

• aws-sdk-ses
• aws-sdk-sesv2

You will have to ensure that you provide credentials for the SDK to use. See the latest AWS SDK for Ruby Docs for details.

If you're running your Rails application on Amazon EC2, the AWS SDK will check Amazon EC2 instance metadata for credentials to load. Learn more: IAM Roles for Amazon EC2

Usage

To use these mailers as a delivery method, set the delivery method and configure the corresponding settings in an environment file (for example config/environments/production.rb).

SES API (v1)

Rails.application.configure do |config|
  # ...
  config.action_mailer.delivery_method = :ses
  config.action_mailer.ses_settings = { region: 'us-west-2' }

  # Optional: reuse one client (e.g. fewer credential refreshes per email)
  ses_client = Aws::SES::Client.new(region: 'us-west-2')
  config.action_mailer.ses_settings = { ses_client: ses_client }
end

SESV2 API

Rails.application.configure do |config|
  # ...
  config.action_mailer.delivery_method = :ses_v2
  config.action_mailer.ses_v2_settings = { region: 'us-west-2' }

  # Optional: reuse one client (e.g. fewer credential refreshes per email)
  sesv2_client = Aws::SESV2::Client.new(region: 'us-west-2')
  config.action_mailer.ses_v2_settings = { sesv2_client: sesv2_client }
end

SendEmail Options (SESV2)

The SESV2 delivery method supports forwarding select SendEmail API parameters as typed settings. These are extracted from your settings and passed directly to the API call (not to the client constructor):

Option	Description
:configuration_set_name	The name of the configuration set to use for event tracking, reputation monitoring, etc.
:email_tags	A list of message tag hashes ([{ name: '...', value: '...' }]) for fine-grained event publishing.
:list_management_options	A hash ({ contact_list_name: '...', topic_name: '...' }) for SES subscription management.

See the API documentation for full details and usage examples.

Using ARNs with SES

This gem uses `Aws::SES::Client#send_raw_email` and `Aws::SESV2::Client#send_email` to send emails. These operations allows you to specify a cross-account identity for the email's Source, From, and Return-Path. To set these ARNs, use any of the following headers on your Mail::Message object returned by your Mailer class:

• X-SES-SOURCE-ARN
• X-SES-FROM-ARN
• X-SES-RETURN-PATH-ARN

Example:

# in your Rails controller
message = MyMailer.send_email(options)
message['X-SES-FROM-ARN'] = 'arn:aws:ses:us-west-2:012345678910:identity/bigchungus@memes.com'
message.deliver