How to fully customize Rails transactional emails (Devise)
Tags: ruby, rails, devise, email
Published: 2019-02-04 04:43:00

---
title: How to fully customize Rails transactional emails (Devise)
published: true
description: 
tags: ruby, rails, devise, email
---

At [RMTWRK](https://rmtwrk.com) we are building the world’s [largest remote only jobs board](https://rmtwrk.com) to help match companies hiring remote or distributed teams with people who are looking for a more flexible work environment. As a result our rails app has two user types, Company Users, people doing the hiring and Individual Users, people wanting to be hired and we wanted to have separate confirmation emails for each user type. Additionally we wanted to use [Mailgun’s](http://mailgun.com/) API for sending emails rather than through SMTP (more on this later), and lastly we wanted to use the amazing [Premailer](https://github.com/premailer/premailer) gem to inline the CSS styles in our emails before sending.

[Devise](https://github.com/plataformatec/devise) is one of the long standing and best written ruby/rails libraries around and one of the easiest to customize, workaround, and override. It does so much though that it can sometimes be hard to know where to start.

We are going to go over the 3 methods (or degrees, if you will) of customizing Devise’s emails.

**Method 1:** Simple customization of Devise’s default emails
**Method 2:** Customizing the “layout” and “templates” used by Devise for sending emails
**Method 3:** Overriding how Devise sends emails to use an API (Mailgun) instead of SMTP

I’ll briefly touch on and link to other resources for the first 2 methods.

### Method 1: Simple customization of Devise’s default emails

If you only want to modify a few simple things about the layout of something like the **email confirmation** email or **password reset** email then this is the method for you. First run the following in your terminal and then you can edit the views for the emails you are interested in inside of *views/devise/mailer*.

`rails generate devise:views`

For further details, the best place to look would be the Devise Readme on GitHub.

### Method 2: Customizing the “layout” and “templates” used by Devise for sending emails

If you want to go a bit further and customize the layout that each email template is rendered into then you can do so by creating your own Mailer class that subclasses `Devise::Mailer`. Devise also has a great Readme on how to do this here: [How To: Create custom layouts](https://github.com/plataformatec/devise/wiki/How-To:-Create-custom-layouts).

There are a couple of potential gotchas to be aware of with this method. If you have two resource types, like say `User` and `Individual` (the names of our actual models), the simplest way to have two separate mailers is to use the method **devise_mailer** in each resource.rb model file (simplified example below). If you plan to move the location of the mailer templates, be sure to delete the existing templates in *devise/mailer* as they will override your other views.

This is an example of a simple customized Devise Mailer:

```ruby
class RmtwrkDeviseMailer < Devise::Mailer
  helper  :application # helpers defined within `application_helper`
  include Devise::Controllers::UrlHelpers # eg. `confirmation_url`
  default template_path: 'rmtwrk/devise/mailer
  default from: 'RMTWRK <rmtwrk@wrkhq.com>'
  default reply_to: 'RMTWRK <rmtwrk@wrkhq.com>'
  layout  'mailer_rmtwrk'
end
```

And you can tell your `Individual` model to use this mailer using the devise_mailer method like this:

```ruby
class Individual < ApplicationRecord
  devise :database_autenticatable,..., :confirmable
  def devise_mailer
    RmtwrkDeviseMailer
  end
end
```

But what if you wanted to do some other things to the email before sending it? That’s where method 3 comes in.

### Method 3: Overriding how Devise sends emails to use an API instead of SMTP

Our constraints:

1. Sending email vis an API rather than SMTP. Most email providers recommend using their API rather than SMTP for a variety of reasons. Here are Sendrid’s and Mailgun’s reasons as examples.
1. Two resource models; User and Individual, using Devise.
1. Separate branding, i.e. layout files per model.
1. Inlining our CSS using Premailer.

In order to accomplish this the essential piece of the puzzle is overriding the `Devise::Mailer` method(s) you are interested in. For this example we will only focus on the email confirmation email. This is handled by the `confirmation_instructions` method by default, which uses `ActionMailer` and SMTP by default.

Here is what our final custom Devise Mailer will look like:

**rmtwrk_devise_mailer.rb**

```ruby
class RmtwrkDeviseMailer < Devise::Mailer
  helper :application # gives access to all helpers defined within `application_helper`.
  include Devise::Controllers::UrlHelpers # Optional. eg. `confirmation_url`
  default from: 'RMTWRK <rmtwrk@inflowhq.com>'
  default reply_to: 'RMTWRK <rmtwrk@inflowhq.com>'

  layout 'mailer_rmtwrk'

  #############################
  # CONFIRMATION EMAIL
  # overrides Devise's confirmation_instructions method
  #############################
  def confirmation_instructions(record, token, opts={})
    @individual = record
    @token = token
    @to_email = @individual.email

    template = render_to_string(template: "mailers/rmtwrk/confirmation_instructions")
    premailer = Premailer.new(template, :with_html_string => true, :warn_level => Premailer::Warnings::SAFE)

    mg_client = Mailgun::Client.new
    mb_obj    = Mailgun::MessageBuilder.new

    mb_obj.from("RMTWRK <rmtwrk@wrkhq.com>")
    mb_obj.add_recipient(:to, @to_email, {'first' => "#{@individual.first_name}", 'last' => "#{@individual.last_name}"})
    mb_obj.subject("RMTWRK - email confirmation instructions")
    # mb_obj.body_text("Plaint text email goes here")
    mb_obj.body_html((premailer.to_inline_css).to_str)

    # mg_client.send_message(Rails.application.credentials.dig(Rails.env.to_sym, :mailgun, :domain), mb_obj)
    mg_client.send_message("mailgun.domain.url/goes/here", mb_obj)
  end
end
```

**mailer_rmtwrk.html.erb**

```ruby
<!-- views/layouts/mailer_rmtwrk.html.erb -->

<!DOCTYPE html>
<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <meta name="viewport" content="width=device-width"/>

    <style type="text/css">
      @font-face {
        font-family: 'Roboto';
        font-style: normal;
        font-weight: 400;
        src: local('Roboto'), local('Roboto-Regular'), url(https://fonts.gstatic.com/s/roboto/v18/KFOmCnqEu92Fr1Mu4mxK.woff2) format('woff2');
      }
      @font-face {
        font-family: 'Roboto';
        font-style: normal;
        font-weight: 500;
        src: local('Roboto Medium'), local('Roboto-Medium'), url(https://fonts.gstatic.com/s/roboto/v18/KFOlCnqEu92Fr1MmEU9fBBc4.woff2) format('woff2');
      }
      body,
      .body {
        font-family: 'Roboto', sans-serif;
        color: #1C1C1C;
        font-weight: 400;
        font-size: 14px;
      }
      .logo {
        margin-bottom: 8px;
      }
      .even-more-styles {
        // etc.
      }
    </style>
  </head>

  <body>
    <a href="https://rmtwrk.com"><img class="logo" src="https://s3.amazonaws.com/inflow-public/rmtwrkEmailLogo.png" width="64"/></a>
    <%= yield %>
  </body>
</html>
```

**confirmation_instructions.html.erb**

```ruby
<!-- views/mailers/rmtwrk/confirmation_instructions.html.erb -->

<div class="secondary-text light-gray space-below">Just need to confirm your email!</div>

<div class="secondary-text light-gray">You can activate your RMTWRK subscription through the link below:</div>

<div class="secondary-text space-below"><%= link_to 'Confirm my email address', @individual.devise_confirmation_url(@token) %></div>

```


I hope that this has been helpful! Please leave comments or questions and I’d be happy to respond.

Thanks for reading - Andrew