A journey on sending emails - ActionMailer

August 2, 2014

Today I was playing around with ActionMailer and using it outside of Rails to send emails. I have previously written about sending emails in Ruby. What I discovered on the Ruby toolbox is that there are quite a few different ways to send emails using Ruby. So I would like to take you through using ActionMailer outside of a Rails application.

ActionMailer allows you to send an email from your application using a mailer model and views. What this means you can pass a model with different properties to a regular ERB view and based on that model you will have different information you can use in the email you intend to send. The great thing about using views as your email templates is that you get to use the full power of the ERB processor, and you can put in proper separation between your application code and email templates.

As with most things in Rails there are certain conventions that ActionMailer expects but thankfully they are over-ridable. Enough with the talking give me the skinny.

First thing is to make sure you have the ActionMailer gem; you can install the ActionMailer gem with

gem install actionmailer

alternatively you can create a gemfile and include the ActionMailer gem in there.

Great you now have the required gem installed, and you are ready to start writing some code.

At the top of your .rb file, you will need a directive to require the ActionMailer gem.

require 'action_mailer'

Depending on the method of delivery you will want to set the delivery_method. I am using Gmail as my mail server with SMTP, so I need to pass along that configuration to ActionMailer. Here is what your file should look like this thus far:

With this boilerplate code in place, we can start writing our mail sending code.

You need to define a class that inherits from ActionMailer::Base. Inheriting from the Base class will give us the ‘deliver’ method that is necessary to do the actual sending.

Here is how our code with the configuration and class definition:

Now we are ready to write a method that will do the work of creating an email and setting variables that we need in our email template.

In our method, we want to set variables that are going to be used in the template as well as in the sending of the email. In our example, we need the ‘to’ and ‘from’ addresses as well as the ‘subject’ of the email. To pass in these different parameters we are going to use a Hash, creatively called details. First here is our method declaration:

Once we add the awesome_email method to our Mailer class and set the Hash with the details, our code should look like this:

Here comes the one thing that might trip you up. ActionMailer uses convention over configuration; this is the Rails way. Convention over configuration allows things to work automagically but in our case we do not have the whole Rails shebang, so we need to override some of that convention to allow our mailing system to work.

We need to let ActionMailer know where to look for our views. That can be done by setting the ‘view_paths’ property to the same path as our mailer script.

ActionMailer::Base.view_paths= File.dirname(__FILE__)
When ActionMailer now scans for the email templates it will follow the convention mailer_script_path/class_name/method_name.(html text).erb. If we look at this convention, we see that we can have HTML and plain text versions of our email template.

Awesome we are now ready to create our email template. Go ahead and create a directory called mailer. Inside of mailer you will need to create a file awesome_email.html.erb since we are only going to send the HTML version of our template, so there is no need to create a plain text version.

Using ERB means we can pass along variables to our email templates. This is extremely handy as email templates are exactly that, templates that need certain information supplied to work correctly. To reference a variable inside of your template, you will need a class level instance variable, so a variable whose name starts with the ‘@’ symbol. If we look at the awesome_email method, we see we have two such variables ‘@to’ and ‘@from’. Inside the awesome_email.html.erb email template you need to add the following to make use of these variables:

Hello this email has been sent to <%= @to %> from <%= @from %>

Great the majority of our email sending code is complete as well as a template. At this point, we are ready to send an email. Here is the simple code you will need to send an email using your Mailer class:

email = Mailer.awesome_email( details )

Here is the full code listing:

ActionMailer is by far the most-used email gem in Ruby, from what I see the majority of that is from Rails applications, it has a simple API, and it is quite straightforward to getting it working in any application.

ActionMailer comes with a lot of dependencies, so it’s not as clean as sending an email using the Standard Library but it is well-tested and widely used, so you are definitely in good company.

Discussion, links, and tweets

My name is Deon Heyns and I am a developer learning things and documenting them in realtime. Python, Ruby, Scala, .NET, and Groovy are all languages I have written code in. I appeared in the New York Post once. I host my code up at GitHub and Bitbucket so have a look at my code, fork it and send those pull requests.

comments powered by Disqus