Ruby on Rails Action Mailer configuration

Wiktor Plaga

March 25, 202313 min reading time

Ruby on Rails Action Mailer overview
Conclusion

If you're looking for Ruby on Rails Action Mailer configuration then you are in the right place.

This tutorial explains how to configure Ruby on Rails in the production environment toward sending emails via Ruby on Rails Action Mailer integrated with the most popular email providers

Gmail, Amazon SES, Mailgun, SendGrid, and Mailchimp's Mandrill are the most popular choices for sending emails with Ruby on Rails.

Let's learn how to configure Ruby on Rails Action Mailer module...

Ruby on Rails Action Mailer overview

Ruby on Rails Action Mailer is a module responsible for sending emails from Ruby on Rails application.

undefined "Ruby on Rails Action Mailer")

Ruby on Rails comes equipped with a dedicated generator, a command-line utility that builds a scaffold file structure for Mailers.

rails generate mailer OrderCompleted

Ruby on Rails Action Mailers live in the app/mailers directory of the application, inheriting from the ActionMailer::Base class.

app
└── mailers
  └── application_mailer.rb

Action Mailers have:

an ability to access a params hash,
associated views in app/views directory,
an ability to utilize view partials and layouts,
instance variables accessible in views,
an ability to send multipart emails, both text, and HTML versions,
mail, headers and attachments actions,
class names with a Mailer postfix.

We can definitely see multiple similarities to Ruby on Rails controllers.

Every Ruby on Rails Action Mailer class comes rigged with self-explanatory methods, called actions:

mail, responsible for sending emails.
headers, for setting email message headers,
attachments, to add attachments sent with emails,

For the complete list of options available to Ruby on Rails Action Mailer, take a look at the `mail`` gem used by the framework.

It is possible to set the default SMTP settings on the Ruby on Rails Action Mailer instance, using the default method.

The Ruby on Rails Action Mailer configuration resides in the corresponding environment files in the config directory.

config.action_mailer.perform_deliveries = true
config.action_mailer.raise_delivery_errors = true
config.action_mailer.preview_path = "#{Rails.root}/tmp/mailers/previews"
config.action_mailer.delivery_method = :smtp
config.action_mailer.smtp_settings = {
  address: 'smtp.example.com',
  port: 1025,
  domain: 'example.com',
  user_name: '<username>',
  password: '<password>',
  authentication: 'plain',
  enable_starttls_auto: true
}
config.action_mailer.default_url_options = {
  host: '',
  port: 1025,
  protocol: 'http'
}

See the documentation for a full list of Action Mailer configuration options

There are multiple ways to avoid sending emails in the Ruby on Rails development environment:

letter-opener gem: it opens incoming emails in the browser
MailHog: runs a simple SMTP server
MailCatcher: runs a simple SMTP server

There's also a full section dedicated to testing Mailers on the Ruby on Rails website if you're using MiniTest, and RSpec has their own instructions on the matter, too.

Let's now see how to configure Ruby on Rails Action Mailer to send emails with the most popular email providers.

Ruby on Rails Action Mailer Gmail configuration

Ruby on Rails Action Mailer is able to send emails with the Gmail account when provided matching SMTP configuration.

Gmail, standing for Google Mail, enables each account to send 500 emails each day through its SMTP server in the free plan.

It is also worth reviewing the GSuite sending limits (2,000 for standard and 500 for trial accounts) if your Ruby on Rails application is going to send more emails than that.

undefined "Ruby on Rails Action Mailer with Gmail")

Let's dive into it.

Gmail account setup

In order to use Ruby on Rails Action Mailer with Gmail, the best solution that does not violate your other security measures such as 2-Step Verification is using AppPassword.

If your account uses 2-Step Verification, the App Password is a 16-digit passcode that gives a non-Google device or app access to your Google Account.

Follow the steps below in order to generate your Gmail App Password. - Open your Google Account Security settings.

undefined "Google Account Security settings")

In "Signing to Google" tile, navigate to App passwords.
Google might ask you to reauthenticate at this point.
On the App passwords page, select the "Mail" app and "Other" device, providing the name of your Ruby on Rails application. Then, click "Generate". undefined "Create App Password")
That's it, copy your App Password from the yellow box. undefined "Copy your App Pasword")

If you are using a Gmail account that is not secured with 2-Step Verification, you can simply use your usual password instead, as the App passwords functionality is not available in this case.

Gmail Rails config

Ruby on Rails Action Mailer is able to send emails via Gmail with simple SMTP settings configured in the chosen environment files.

It does not require any additional gems to be installed, as it's just a simple SMTP configuration, available for many other email providers as well.

config/production.rb

config.action_mailer.delivery_method = :smtp
config.action_mailer.smtp_settings = {
  port: 587,
  address: 'smtp.gmail.com',
  user_name: 'wiktor.plaga@gmail.com',
  password: 'abcdef0123456789',
  authentication: :plain,
  enable_starttls_auto: true
}

Storing information that sensitive is a bad idea though, so you're better of keeping it in the environment variables, using dotenv-rails gem.

.env

SMTP_USER_NAME=wiktor.plaga@gmail.com
SMTP_PASSWORD=abcdef0123456789

With this in place, edit the Ruby on Rails Action Mailer SMTP configuration as follows.

config/production.rb

config.action_mailer.delivery_method = :smtp
config.action_mailer.smtp_settings = {
  port: 587,
  address: 'smtp.gmail.com',
  user_name: ENV['SMTP_USER_NAME'],
  password: ENV['SMTP_PASSWORD'],
  authentication: :plain,
  enable_starttls_auto: true
}

At this point, your Ruby on Rails Action Mailer can easily send emails using your Gmail account.

Ruby on Rails Action Mailer Amazon SES configuration

Ruby on Rails Action Mailer is easily configurable to use Amazon Simple Email Service.

undefined "Ruby on Rails Action Mailer with Amazon SES")

Let's do it.

Amazon SES account setup

In order for Ruby on Rails Action Mailer to send emails via Amazon SES, you need to create the AWS account.

After doing so, follow the steps below.

Log into your AWS Console.
In the "Services" dropdown go to "Customers Engagement" section and navigate to "Simple Email Service". undefined "AWS Simple Email Service")
In the left-hand sidebar navigate to "SMTP Settings", copy your "Server name" and click the "Create My SMTP Credentials" button. undefined "Create My SMTP Credentials")
Click the "Create" button. undefined "Click the Create button")
Download or copy Amazon SES SMTP credentials for later usage. undefined "Download Amazon SES SMTP credentials")

Sending emails in production via Amazon SES additionally requires requesting a sending limit increase - after doing so, you will be able to send emails to everybody.

You can do that in Email Sending > Sending Statistics > Request Sending Limit increase.

undefined "Production: Request Sending Limit Increase")

However, in order to test your Ruby on Rails Action Mailer configuration, it's enough to verify your email address in Identity Management > Email Addresses section of the Amazon SES dashboard.

undefined "Verify testing email")

Add your email address to which you want to send a message via Ruby on Rails Action Mailer and head to your mailbox - you will receive a verification link.

After securely saving the SMTP credentials for Amazon SES usage, let's move to Ruby on Rails Action Mailer configuration.

Amazon SES Rails config

Ruby on Rails Action Mailer needs SMTP configuration toward sending emails via Amazon Simple Email Service.

config/production.rb

config.action_mailer.delivery_method = :smtp
config.action_mailer.smtp_settings = {
  port: 587,
  address: 'email-smtp.eu-west-1.amazonaws.com',
  user_name: 'your-aws-smtp-username',
  password: 'your-aws-smtp-username',
  authentication: :plain,
  enable_starttls_auto: true
}

In order to follow the Twelve-Factor App guideline, it is better to use environment management gem such as dotenv-rails.

.env

SMTP_ADDRESS=email-smtp.eu-west-1.amazonaws.com
SMTP_USER_NAME=your-aws-smtp-username
SMTP_PASSWORD=your-aws-smtp-password

With environment variables in place, you are ready to edit the configuration file as follows.

config/production.rb

config.action_mailer.delivery_method = :smtp
config.action_mailer.smtp_settings = {
  port: 587,
  address: ENV['SMTP_ADDRESS'],
  user_name: ENV['SMTP_USER_NAME'],
  password: ENV['SMTP_PASSWORD'],
  authentication: :plain,
  enable_starttls_auto: true
}

All done, your Ruby on Rails Action Mailer is ready to send emails via Amazon SES SMTP account.

Ruby on Rails Action Mailer Mailgun configuration

Ruby on Rails Action Mailer is capable of sending emails with Mailgun via its SMTP configuration.

undefined "Ruby on Rails Action Mailer with Mailgun")

Let's dive in.

Mailgun account setup

In order for Ruby on Rails Action Mailer to send emails with Mailgun via SMTP, you need to create your Mailgun account.

Follow the steps below.

Create an account on the official Mailgun website undefined "Mailgun Signup website")
Choose your Mailgun plan. undefined "Choose your Mailgun plan")

In order to send emails, you have to additionally verify your domain by adding required TXT records to your domain's DNS.

Let's now set up Ruby on Rails Action mailer with the brand new Mailgun account.

Mailgun Rails config

Ruby on Rails Action Mailer is able to send emails via your Mailgun account with this simple configuration.

config/production.rb

config.action_mailer.delivery_method = :smtp
config.action_mailer.smtp_settings = {
  port: 587,
  address: 'smtp.mailgun.org',
  domain: 'hix.dev',
  user_name: 'wiktorplaga@hix.dev',
  password: 'secret-mailgun-account-password',
  authentication: :plain
}

It is better not to store any secrets in your Ruby on Rails application source code, so we recommend using dotenv-rails gem instead.

.env

DOMAIN_NAME=hix.dev
SMTP_USER_NAME=wiktorplaga@hix.dev
SMTP_PASSWORD=secret-mailgun-account-password

config/production.rb

config.action_mailer.delivery_method = :smtp
config.action_mailer.smtp_settings = {
  port: 587,
  address: 'smtp.mailgun.org',
  domain: ENV['DOMAIN_NAME'],
  user_name: ENV['SMTP_USER_NAME'],
  password: ENV['SMTP_PASSWORD'],
  authentication: :plain
}

That's it, you can start sending emails now.

However, there's another thing to consider when it comes to sending emails with Ruby on Rails using Mailgun.

Mailgun exposes an email sending API, that's dedicated for better long term performance and maintenance wise.

undefined "Mailgun SMTP and API comparison")

In order for your Ruby on Rails application to send emails with Mailgun API, you can use the mailgun-ruby gem.

Add the following to your Gemfile.

Gemfile

gem 'mailgun-ruby'

and run bundle install.

The last step toward sending emails via Mailgun API with Ruby on Rails Action mailer is its configuration.

Mailgun sends you the API key upon account registration.

undefined "Registration email with Mailgun API Key.")

In case you've already deleted it, it's still available on your Mailgun account > Settings > API Keys section.

undefined "Mailgun API Key in Settings > API Keys dashboard")

Now that you've got the Mailgun API key ready, let's add it to the Ruby on Rails Action Mailer configuration file.

config/production.rb

config.action_mailer.delivery_method = :mailgun
config.action_mailer.mailgun_settings = {
  api_key: 'api-myapikey',
  domain: 'mydomain.com',
  # api_host: 'api.eu.mailgun.net'  # Uncomment this line for EU region domains
}

Both configuration values are better off residing in the dedicated environment file.

.env

DOMAIN_NAME=hix.dev
MAILGUN_API_KEY=api-myapikey

config/production.rb

config.action_mailer.delivery_method = :mailgun
config.action_mailer.mailgun_settings = {
  api_key: ENV['MAILGUN_API_KEY'],
  domain: ENV['DOMAIN_NAME'],
  # api_host: 'api.eu.mailgun.net'  # Uncomment this line for EU region domains
}

That's it, your Ruby on Rails Action Mailer is ready to send emails via Mailgun API.

Ruby on Rails Action Mailer SendGrid configuration

Ruby on Rails Action Mailer is easily configurable to send emails with SendGrid.

undefined "Ruby on Rails Action Mailer with SendGrid")

Let's do it.

SendGrid account setup

Let's create a free account for sending emails with Ruby on Rails Action Mailer with SendGrid.

Follow the steps below.

Start for free on an official SendGrid website. undefined "SendGrid official website")
Provide your username, password and email address. undefined "SendGrid signup - account credentials")
Visit your mailbox and verify the email address provided.
Provide further personal and business information. undefined "SendGrid signup - personal information")
In account's dashboard "Send your first email" section, click the "Start" button in the first "Integrate using our Web API or SMTP relay" section. undefined "Integrate SendGrid Web API or SMTP relay")

The first way is a classic SMTP integration.

Follow the steps below in order to obtain your SendGrid SMTP account password.

Choose "SMTP Relay" integration option. undefined "Choose 'SMTP relay' integration")
Provide your first API key name, click "Create Key" and copy the generated key. undefined "SendGrid key form")
On the bottom of the page, check the checkbox and click the "Next: Verify Integration" button. undefined "SendGrid API key verification")

The second option, that's recommended by SendGrid, is using the Web API. This will require installing an additional third-party gem to work with Ruby on Rails Action Mailer.

Follow the steps below for generating your SendGrid Web API key. - Choose "Web API" integration option.

undefined "Choose "Web API" integration")

Choose Ruby language. undefined "Choose Ruby language")
Provide your first API key name, click "Create" and copy the generated API key. undefined "SendGrid API key form")
On the bottom of the page, check the checkbox and click the "Next: Verify Integration" button. undefined "SendGrid API key verification")

Now that we've created the SendGrid account with all the credentials required, let's get to Ruby on Rails Action Mailer configuration.

SendGrid Rails config

In order for Ruby on Rails Action Mailer to send emails with SendGrid, we need proper SMTP settings in place.

config/production.rb

config.action_mailer.delivery_method = :smtp
config.action_mailer.smtp_settings = {
  user_name: 'your_sendgrid_username',
  password: 'your_sendgrid_password',
  domain: 'yourdomain.com',
  address: 'smtp.sendgrid.net',
  port: 465,
  authentication: :plain,
  enable_starttls_auto: true
}

Although it is better to keep those secrets out. Use dotenv-rails gem instaed.

.env

DOMAIN_NAME=hix.dev
SMTP_USER_NAME=wiktorplaga
SMTP_PASSWORD=you-will-never-guess-it

With those environment variables in place, replace a previous configuration with the following.

config/production.rb

config.action_mailer.delivery_method = :smtp
config.action_mailer.smtp_settings = {
  user_name: ENV['SMTP_USER_NAME'],
  password: ENV['SMTP_PASSWORD'],
  domain: ENV['DOMAIN_NAME'],
  address: 'smtp.sendgrid.net',
  port: 465,
  authentication: :plain,
  enable_starttls_auto: true
}

In order to test the SMTP integration locally, you might need to change the port to 25 or 587, as the 465 is reserved for SSL connections and does not work unless you have a local self-signed certificate.

There's also another way for Ruby on Rails Action Mailer to send emails with SendGrid - it's by using SendGrid API.

First, install the sendgrid-actionmailer gem

The gem also extends the usual mail action with SendGrid-specific options that are not available with the default Ruby on Rails Action Mailer functionality.

Gemfile

gem 'sendgrid-actionmailer'

After running bundle install in the CLI, prepare your Ruby on Rails Action Mailer configuration for SendGrid API.

.env

SENDGRID_API_KEY=your-sendgrid-api-key

config/production.rb

config.action_mailer.delivery_method = :sendgrid_actionmailer
config.action_mailer.sendgrid_actionmailer_settings = {
  api_key: ENV['SENDGRID_API_KEY'],
  raise_delivery_errors: true
}

Your Ruby on Rails Action Mailer is now ready to send emails via SendGrid API.

Go back to your SendGrid dashboard and verify the previously generated SMTP or API key.

Ruby on Rails Action Mailer Mandrill configuration

Ruby on Rails Action Mailer is able to integrate with Mandrill via SMTP settings.

undefined "Ruby on Rails Action Mailer with Mandrill")

Let's set it up.

Mandrill account setup

Mandrill is a transactional email API for Mailchimp users.

Mandrill is available as an add-on to Standard and higher monthly plans, or the legacy Monthly Plan. Free, Essentials, and Pay As You Go users will need to upgrade to use Mandrill.

Mailchimp's Mandrill documentation

Follow the steps below to create your Mailchimp account. - Visit the official Mailchimp website official Mailchimp website and fill out the signup forms.

Next, Add Mandrill to your Mailchimp account
In your account API settings, create Mandrill API Key.

Let's move to the Ruby on Rails Action Mailer configuration.

Mandrill Rails config

With Mandrill API Key in place, you're ready to configure Ruby on Rails Action Mailer SMTP settings to work with Mandrill.

config/production.rb

config.action_mailer.delivery_method = :smtp
config.action_mailer.smtp_settings = {
  address: 'smtp.mandrillapp.com',
  port: 25,
  enable_starttls_auto: true,
  user_name: 'wiktorplaga@hix.dev',
  password: 'mandrill-api-key',
  authentication: 'login',
  domain: 'hix.dev'
}

However, it's better to use dotenv-rails gem.

.env

DOMAIN_NAME=hix.dev
MANDRILL_USERNAME=wiktorplaga@hix.dev
MANDIRLL_API_KEY=mandrill-secret-api-key

With those Mandrill environments variables in place, the production configuration file looks like this.

config/production.rb

config.action_mailer.delivery_method = :smtp
config.action_mailer.smtp_settings = {
  address: 'smtp.mandrillapp.com',
  port: 25,
  enable_starttls_auto: true,
  user_name: ENV['MANDRILL_USERNAME'],
  password: ENV['MANDRILL_API_KEY'],
  authentication: 'login',
  domain: ENV['DOMAIN_NAME']
}

Your Ruby on Rails Action Mailer is ready to send emails with Mandrill.

Conclusion

Ruby on Rails Action Mailer configuration is simple and straightforward no matter what email service you use.

All it takes is a few SMTP configuration options, and in some cases, an additional gem.

In order to configure Action Mailer along with your Ruby on Rails application setup, use the hix.dev Ruby on Rails Template.

Hix Software Project Starter

Automate your project configuration with the Hix project starter.

Skip all the mundane tasks and start delivering.

Next.js

Rails

Table of Contents:

Ruby on Rails Action Mailer overview

Ruby on Rails Action Mailer Gmail configuration

Gmail account setup

Gmail Rails config

Ruby on Rails Action Mailer Amazon SES configuration

Amazon SES account setup

Amazon SES Rails config

Ruby on Rails Action Mailer Mailgun configuration

Mailgun account setup

Mailgun Rails config

Ruby on Rails Action Mailer SendGrid configuration

SendGrid account setup

SendGrid Rails config

Ruby on Rails Action Mailer Mandrill configuration

Mandrill account setup

Mandrill Rails config

Conclusion