How to fully customize Rails transactional emails (Devise)

#ruby #rails #devise #email

At RMTWRK we are building the world’s largest remote only jobs board 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 API for sending emails rather than through SMTP (more on this later), and lastly we wanted to use the amazing Premailer gem to inline the CSS styles in our emails before sending.

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.

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:

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:

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:

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.
Two resource models; User and Individual, using Devise.
Separate branding, i.e. layout files per model.
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

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

<!-- 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

<!-- 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>