Receiving Test Driven Incoming Email for Rails 3

One of the most frequent questions we are asked at CloudMailin is how can you develop your application and receives email offline, without opening ports, in a Rails app.

There are options that spring to mind. The first is to write a script that delivers a local email to your app simulating the response that you would get from an email server. The second solution is far simpler. You can perform test driven development and it can be really easy  get things up and running in development and even easier to move to production.

Here we are going to create a really simple example to take the subject of an email and create a model called movie poster from that subject. In a later post we will show how we can also use the attachments to create the images for the poster.

The First Step, a Controller to Receive the Email

In a previous article I highlighted a number of options for Receiving Email in Rails 3. Using some of the approaches you don’t even need to use a controller but in that case where email is delivered to your app via an HTTP POST the controller is needed. The controller doesn’t have to be complicated though. All we really want to do is pass a mail object to the receive method of our mailer. So supposing we have a mailer called MovieMailer we can do the following:

class IncomingMailsController < ApplicationController
   skip_before_filter :verify_authenticity_token
   def create
     # create a Mail object from the raw message
     movie_poster = MovieMailer.receiver([:message]))
     # if the movie poster was saved then send a status of 201 else give a 422 with the errors
     if !movie_poster.new_record?
        render :text => "Success", :status => 201, :content_type => Mime::TEXT.to_s
      render :text => movie_poster.errors.full_messages.join(', '), :status => 422, :content_type => Mime::TEXT.to_s

The example above assumes that you are using at least Rails 3.0 but it can easily be converted to work with older versions of Rails and you could use the TMail gem rather than Mail if you need to.

Now we have this controller we can create a functional test to check this in the same way we would any other controller in our app (note I’m doing this the wrong way round for illustration you should really write your test first!). If we mock the response from the Mailer for now we can use something like this with Shoulda but you could use RSpec or any other testing framework just as easily:

class IncomingMailsControllerTest < ActionController::TestCase
   context "An IncomingMailsController" do
     context "on POST to :create with an invalid item" do
        setup do
           post :create, :message => "From: #{}\r\nSubject: New Poster\r\n\r\nContent"

      should_respond_with 422
      should "not create the item" do
        assert assigns(:item).new_record?

    context "on POST to :create with a valid item" do
      setup do
        post :create, :message => "From: #{}\r\nSubject: New Task\r\n\r\nContent"

      should_respond_with 201
      should "set the items title to be the message subject" do
        assert_equal "New Task", assigns(:item).title

I have also created a really simple email message to pass as the message param here as an example with the header and body separated by two carriage return new lines but this isn’t really necessary with the use of mocha.

Subject: Subject


So on to the Mailer

Now that we have our controller sorted and fully tested we can create our Mailer, which will automatically create a functional test. It’s then just a case of adding the tests to test the receive method. The first step is to create a sample email that we can use in each of our tests. I am using the Mail gem again to do this.

  context "A MoveMailer" do
    setup do
      @message = do
        from ""
        to ""
        subject "New Movie"

Then we can add our tests making use of the example mail we added and changing any of the parts we want to.

  should "create a new movie poster with the email subject" do
    @message.subject = "new subject"
    assert_difference("Movie.count", 1) do
      movie_poster = MovieMailer.receive(message)
      assert movie_poster.persisted?, movie_poster.errors.full_messages
      assert_equal "new subject", movie_poster.subject

In this case we’re just going to add one test and we can now create our simple movie mailer to take the subject from the email and store it as a poster.

class MovieMailer < ActionMailer::Base

  # Called whenever a message is received on the movies controller or through the rails runner
  def receive(message)
    # For now just take the first attachment and assume there is only one
    attachment = message.attachments.first

    # Create the movie itself
    Movie.create do |movie|
      movie.title = message.subject

Now when your app goes into production you just deliver the message to the controller using the HTTP Post approaches, directly to the mailer using any of the other approaches discussed in the previous article.

Although the example is a little contrived you can hopefully See how you can benefit from testing at the development machine to ensure you system works perfectly once you put your code into production. You also have the added benefit of not having to keep checking things whenever you change your code. Just re-run your tests, same as you would with any other part of your app!


Ruby Gems and OSX 10.6 (Snow Leopard)

I recently upgraded to Snow Leopard. I had to fight the urge to install sooner because we had some big projects underway at work and couldn’t afford any downtime.

Due to not having time to do a complete re-install I simply did the upgrade and I must admit I am pretty impressed with how smoothly it went. When I get some more time I’ll do a clean install but I’m happy with things for now.

One of the things I am finding however is that a lot of gems that required native extensions need to be rebuilt. For a number of these things are quite obvious and its just a case of either updating or removing the gem and re-installing.

Autotest however wasn’t quite so obvious. Some gems install dependancies that required rebuilding and its not always 100% obvious like the following:

/Library/Ruby/Gems/1.8/gems/sys-uname-0.8.3/lib/sys/uname.bundle: dlopen(/Library/Ruby/Gems/1.8/gems/sys-uname-0.8.3/lib/sys/uname.bundle, 9): no suitable image found.  Did find: (LoadError)
/Library/Ruby/Gems/1.8/gems/sys-uname-0.8.3/lib/sys/uname.bundle: no matching architecture in universal wrapper - /Library/Ruby/Gems/1.8/gems/sys-uname-0.8.3/lib/sys/uname.bundle
from /Library/Ruby/Site/1.8/rubygems/custom_require.rb:31:in `require'
from /Library/Ruby/Gems/1.8/gems/autotest-fsevent-0.1.1/lib/autotest/fsevent.rb:3
from /Library/Ruby/Site/1.8/rubygems/custom_require.rb:36:in `gem_original_require'
from /Library/Ruby/Site/1.8/rubygems/custom_require.rb:36:in `require'
from /Users/stevesmith/.autotest:2
from /Library/Ruby/Gems/1.8/gems/ZenTest-4.1.3/lib/autotest.rb:195:in `load'
from /Library/Ruby/Gems/1.8/gems/ZenTest-4.1.3/lib/autotest.rb:195:in `initialize'
from /Library/Ruby/Gems/1.8/gems/ZenTest-4.1.3/lib/autotest.rb:194:in `each'
from /Library/Ruby/Gems/1.8/gems/ZenTest-4.1.3/lib/autotest.rb:194:in `initialize'
from /Library/Ruby/Gems/1.8/gems/autotest-rails-4.1.0/lib/autotest/rails.rb:7:in `initialize'
from /Library/Ruby/Gems/1.8/gems/ZenTest-4.1.3/lib/autotest.rb:138:in `new'
from /Library/Ruby/Gems/1.8/gems/ZenTest-4.1.3/lib/autotest.rb:138:in `run'
from /Library/Ruby/Gems/1.8/gems/ZenTest-4.1.3/bin/autotest:55
from /usr/bin/autotest:19:in `load'
from /usr/bin/autotest:19

The gem sys-uname makes use of native extensions but is obviously not reinstalled as autotest is its just assumed to already exist. In this case simply doing

sudo gem uninstall sys-uname
sudo gem install sys-uname

will bring it back. I guess this isn’t the most tricky thing to figure out but I thought I’d post it in case it was of use to anyone.