Rails 6: Action Mailbox — Explained. Why?How? When?

Sanjay Prajapati
4 min readApr 12, 2019

There are many new shiny features are going to be unveiled in Rails 6. New methods for ActiveRecord, ActionText, Action Mailbox are some of them. We are going to talk about Action Mailbox today. What it is? How to use it? How it helped us to solve one real time problem?


Action Mailbox routes incoming emails to controller-like mailboxes for processing in Rails. It supports all major platforms or ingresses like Amazon SES, Mailgun, Mandrill, Postmark, and SendGrid. You can also handle inbound mails directly via the built-in Exim, Postfix, and Qmail ingresses.


As I mentioned before, Action Mailbox is going to be shipped with Rails 6 which is not released officially yet when I am writing this blog. You need to install the — pre version of rails to use this feature.

Rails 6 needs Ruby version 2.5 or higher. But I met with class loading issue and after searching around found that there is an issue with version 2.5 and Action Mailbox. So use ruby 2.6 or higher version. Here is the issue link

Install rails 6 using below command. Make sure you are using ruby-2.6 or higher.

gem install rails --pre

I would strongly recommend to create gemsets for it. And create below two files in the root directory.

.ruby-version and .ruby-gemset

After installing the rails, create new rails project using below command. This will install all dependencies and take postgres as database

rails new action_mailbox -d postgresql

Now run bellow generator to create mailbox related migration and files.

rails action_mailbox:install

This will create migrations related to active storage and action mailbox tables.

Run rails db:migrate to create tables for it.

Run rails webpacker:install to install asset files otherwise it will throw error while running rails server.

Start rails server using rails server command and check localhost:3000 to check if everything is working fine.

You would need to configure your email service provider to post JSON data to your rails webhook when someone sends email to you.

You can find all the details on the official doc here

Use Case/Problem

One of our clients comes with a problem that, users send him lots of emails asking the price of specific product and he would need to reply manually after checking the price.

Technically we would need to perform below actions:

1. Read inbox with a subject contains SKU

2. Read SKU from body and identify SKU

3. Call an external API to get product details.

4. Send predefined email with product details to sender.


You might have already got the idea how Action Mailbox will help us.

When you have ran rails action_mailbox:install it would have created ApplicationMailbox.rb.

In this file you can define controller-like routes and based on that assign relevant mailbox. There is a specific syntax to define that routes which we will see later.

In our case if the subject or message body has the word SKU then we would need to process the email using PriceFinderMailbox and perform the other actions.

Here are some rules for defining the routes based on the original doc.

We have used the proc like route to identify if the subject or body has specific word and accordingly choose the mailbox.

Behind the Scene

When your rails app got the request via webhook, it will hit the below controller which you can’t find in your code.


In our case <email_ingress> is Postmark.

It will create entry in below tables.

1. ActionMailbox::InboundEmail
2. ActiveStorage::Blob
3. ActiveStorage::Attachment

ActionMailbox::InboundEmail has status field. This is how the status updates.

During the processing of the inbound email, the status will be tracked. Before processing begins, the email will normally have the pending status. Once processing begins, just before callbacks and the process method is called, the status is changed to processing. If processing is allowed to complete, the status is changed to delivered. If a bounce is triggered, then bounced. If an unhandled exception is bubbled up, then failed.

It actually manages using enums

ActionMailbox::InboundEmail.statuses{"pending"=>0, "processing"=>1, "delivered"=>2, "failed"=>3, "bounced"=>4}

This is how Action Mailbox added one more feather to Rails framework and we solved the problem for the client.

Here is the video blog of it : https://www.youtube.com/watch?v=WmoLaoskN4c

Thanks for reading!!

At BoTree Technologies, we build web and mobile applications to add value to our client’s business. We align ourselves to ensure that our client benefits the most out of our engagement.

We work in Ruby on Rails, Python, Java, React, Android, iOS and RPA as well.

Drop us a line to discuss how can we help take your business to the next level.



Sanjay Prajapati

Sr. Ruby on Rails Developer | Ruby | Rails | Javascript | TDD | ReactJS