x
Adi

Ruby on Rails - Mandrill Templating System

over 3 years ago by Adrian

Popup

Virtually all applications have some form of email notifications. While the messages are usually short, informing users about events, the overall design of the email is a good opportunity to present a company’s brand. Images such as logos and the copy might change from season to season to reflect the various stages a company is in. Because marketeers enjoy A/B testing emails much more than us, engineers, do, we decided to use Mandrill templates to allow non-engineers to customize emails without a developer’s involvement. In this article we show you how to integrate Mandrill templates (and then MailChimp templates) with a Ruby on Rails application.

Here is what you need to do to setup Mandrill templates.

Add in your gemfile:

gem "mandrill-api"

Then run:

bundle install

Mandrill templates work in the production environment. While implementing this, we suggest using the same production settings in the development mode also. Note that real emails will be sent out. Once you are happy with the results, you can switch back to your development settings which might include opening emails in browser with a gem such as letter-opener. Development settings while testing might look like this:

config.action_mailer.default_url_options = { :host => "localhost:3000" }
config.action_mailer.delivery_method = :smtp
config.action_mailer.perform_deliveries = true
config.action_mailer.raise_delivery_errors = false
config.action_mailer.default :charset => "utf-8"
config.action_mailer.smtp_settings = {
    :port => "587",
    :address => "smtp.mandrillapp.com",
    :user_name => "username",
    :password => "password",
    :domain => "domain (e.g. domain.herokuapp.com)",
    :authentication => :plain
}

When sending emails we no longer need regular Ruby on Rails mailer views. In your mailer.rb file, add the following lines:

require "mandrill"

def mandrill_client
    @mandrill = Mandrill::API.new "APIKEY"
end

Define your email method:

def my_email_method(user)
    template_name = "my-email-method"
    template_content = []
    message = {
        to: [{email: user.name}],
        subject: "Subject message",
        merge_vars: [
            {
            rcpt: @user.email,
            vars: [
                        {name: "USER_NAME", content: user.name},
                        {name: "LOG_IN_URL", content: root_url}
                 ]
            } 
         ]
    }
    mandrill_client.messages.send_template template_name, template_content, message
end

Variables are defined in merge_vars array. For each recipient you can define variables with name and content. You can display these values in the email by writing the variables in your template with:

*|VARIABLE_NAME|*

In order to configure Mandrill templates, you should go to Mandrill > Outbound > Templates > Create Template

In template name you add your email method name (e.g. my_email_method).

Create Mandrill Template

Template slug will be automatically completed with my-email-method (our template name defined in function – this will be used to identify the correct template for each email).

Create Mandrill Template

After configuring your email you can publish it.

Create Templates in MailChimp

MailChimp can be used to design your Mandrill templates. It offers many tools that help you customize your templates.
First, you need to create a MailChimp account. After logging in, you can create templates. If the template already exists in Mandrill, you have to use same template name in both places.

When it is ready, you should link your MailChimp account with your Mandrill account:
Link MailChimp account

After linking your accounts you have to export your MailChimp templates to Mandrill:
Export MailChimp templates

When exporting templates, if there already exists a template with the same name in Mandrill, its content will be overwritten with the one in MailChimp.

Overwrite Ruby on Rails Devise Mailer

If you want to overwrite devise mailer you can create a custom devise mailer:

class CustomDeviseMailer < Devise::Mailer
    default from: "[email protected]"
  
    require "mandrill"
 
    def mandrill_client
        @mandrill = Mandrill::API.new "APIKEY"
    end

    def confirmation_instructions(record, token, opts={})
        template_name = "confirmation-instructions"
        template_content = []
        message = {
            to: [{email: record.email}],
            subject: "Confirmation instructions",
            var_user_email: record.email,
            merge_vars: [
            {rcpt: record.email,
                vars: [
                    {name: "USER_EMAIL", content: record.email},
                    {name: "CONFIRMATION_LINK", content: user_confirmation_url(confirmation_token: token)}
                ]
            }]
        }
        mandrill_client.messages.send_template template_name, template_content, message
    end

    def reset_password_instructions(record, token, opts={})
        template_name = "reset-password-instructions"
        template_content = []
        message = {
        to: [{email: record.email}],
        subject: "Reset password instructions",
        var_user_email: record.email,
        merge_vars: [
            {rcpt: record.email,
             vars: [
                 {name: "USER_EMAIL", content: record.email},
                 {name: "RESET_PASSWORD", content: reset_password_url(reset_password_token: record.reset_password_token)}
             ]}
        ]
        }
        mandrill_client.messages.send_template template_name, template_content, message
    end
end

Define your custom devise mailer in devise.rb initializer:

config.mailer = "CustomDeviseMailer"

That’s it! Hope you enjoyed our article!

Did you like this post? Share it with your friends!