I wanted to preview my HTML emails without having to fill up my online email inboxes with tons of email (and then I’d have to make filters too). I also didn’t want to manage actually sending real email. So, I set up my machine for local delivery. Read on for instructions.

I am running Ubuntu 9.04, however these instructions should be fine at least back to 8.04.

Step 1 – Install Postfix

sudo aptitude install postfix

During the install, choose “Local Delivery Only”

Step 2 – Configure Evolution for Receiving Locally

Open up Evolution “Applications->Internet->Evolution Mail”

Set up a new account and choose local delivery. When it asks you for a path, put in:

/var/mail/<username>

Note that this path may not exist if you’ve never received mail.

Step 3 – Configure Sanitize Email

In your rails test environment.rb put:

config.action_mailer.delivery_method = :sendmail

Then, in the initializer where you set up sanitize email:

ActionMailer::Base.sanitized_recipients = ["@"]
ActionMailer::Base.local_environments = %w( test )

If you need to know your username or hostname, just open up a terminal. The command “whoami” will give you your username, and “hostname” will give you the hostname.

Step 4 – Run your tests

Now, run your rails tests. You should have a test for every email you send, and that should trigger them to be sent locally. You may have to tell Evolution to Send/Receive. Keep in mind your tests will probably fail because they will expect email to be in test mode.

Step 5 – Set it back

Remember, when you’re done previewing your email, reset config.action_mailer.delivery_method!

Not long ago I stumbled upon Peter Boling’s plugin implementation of sanitize_email. I’ve since forked it, turned it into a gem, and continued to apply maintenance commits to it as rails has marched forward through versions 2.2 and 2.3.

The primary value sanitize_email provides is that it allows you to reroute all email without having to alter any application code. It’s environment-specific and doesn’t introduce any production/deployment dependencies.

Installation

To install, simply execute:

  $> sudo gem install sanitize_email

Use Cases

There are three primary use cases for sanitize_email.

Working Locally with Production Data

Scenario: you have a mechanism for recreating your production environment in your development environment (capistrano-extensions provides this capability for MySQL databases). You want to pull down the production data to troubleshoot a live email issue. Using sanitize_email, we can set up our dev environment to override all email envelopes so that email actually goes to an inbox of your choice.

Re-routing Email on a Staging or QA Server

During initial development of a new email feature, it’s imperative that the client/stakeholder be able to review all emails being generated. sanitize_email makes it dead simple to specify that your staging environment route all email generated to a specific email address without having to change any application code.

Testing Email from a Hot Production Server

You can install sanitize_email on your production server, and then utilize it from the console to give you more freedom when poking and prodding your application. You can trigger any email you need to without fear that it will go to a real live email address.

Sample Usage of sanitize_email

sanitize_email uses ActionMailer::Base.local_environments to specify in which environments to override the SMTP envelope. Note that a set of defaults can be configured in an initializer file, and then overridden in specific environment files for further control.

    # Settings for sanitize_email gem.  These can be overridden in individual config/%env%/environment.rb files.
    require 'sanitize_email'
    ActionMailer::Base.sanitized_recipients = "john@smartlogicsolutions.com"
    ActionMailer::Base.sanitized_bcc = nil
    ActionMailer::Base.sanitized_cc = nil

    # These are the environments whose outgoing email BCC, CC and recipients fields will be overridden!
    # All environments not listed will be treated as normal.
    ActionMailer::Base.local_environments = %w( development test staging )

Closing Notes

The functionality provided by sanitize_email is truly very basic, and admittedly a little static. You can only set a single override for any given environment, which doesn’t lend itself to a QA/review team that consists of more than a single person. I have been working on rails-caddy which is a tool for bringing a lot of QA goodness to the browser. One feature it provides is an integration with sanitize_email, allowing these overridden email addresses to be set on a per session basis, which in turn allows several individuals to work on a staging server at the same time and each receive the email that their own actions triggered. It’s still in its early stages (pre 0.1.0 release), but it’s something we’re using on several apps already.

Related Links

RDoc | Source on GitHub