Griddler is a Rails engine that provides an endpoint for SendGrid, Cloudmailin, Postmark or Mandrill and hands off the email to your application.
Tutorials
- SendGrid wrote a great tutorial on integrating Griddler with your application.
- We have our own blog post on the subject over at Giant Robots.
Installation
Add griddler to your application's Gemfile and then run bundle install
:
Griddler comes with a default endpoint that will be displayed at the bottom
of the output of rake routes
. If there is a previously defined route that
matches /email_processor
— or you would like to rename the
matched path — you may add the route to the desired position in routes.rb
with the following:
Defaults
By default Griddler will look for a class named EmailProcessor
which you create. It will initialize that class with a
Griddler::Email
instance representing the incoming email, then call
the process
instance method on that class. The process
should handle processing the incoming email. For example, in
./lib/email_processor.rb
:
The email
object passed into your initialize method is a
Griddler::Email
instance that responds to:
.to
.from
.subject
.body
.raw_text
.raw_html
.raw_body
.attachments
.headers
.raw_headers
Each of those has some sensible defaults.
.from
, .raw_body
, .raw_headers
, and .subject
will contain the obvious
values found in the email, the raw values from those fields.
.body
will contain the full contents of the email body unless there is a
line in the email containing the string -- Reply ABOVE THIS LINE --
. In that
case .body
will contain everything before that line.
.to
will contain all of the text before the email's "@" character. We've found
that this is the most often used portion of the email address and consider it to
be the token we'll key off of for interaction with our application.
.attachments
will contain an array of attachments as multipart/form-data files
which can be passed off to attachment libraries like Carrierwave or Paperclip.
.headers
will contain a hash of header names and values as parsed by the Mail
gem. Headers will only be parsed if the adapter supports a headers option.
Configuration Options
An initializer can be created to control some of the options in Griddler. Defaults
are shown below with sample overrides following. In config/initializer/griddler.rb
:
config.processor_class
is the class Griddler will use to handle your incoming emails.config.processor_method
is the method Griddler will call on the processor class when handling your incoming emails.config.reply_delimiter
is the string searched for that will split your body.config.email_service
tells Griddler which email service you are using. The supported email service options are:sendgrid
(the default),:cloudmailin
(expects multipart format),:postmark
and:mandrill
.
Testing In Your App
You may want to create a factory for when testing the integration of Griddler into your application. If you're using factory_girl this can be accomplished with the following sample factory.
Bear in mind, if you plan on using the :with_attachment
trait, that this
example assumes your factories are in spec/factories.rb
and you have
an image file in spec/fixtures/
.
To use it in your test(s) just build with email = build(:email)
or email = build(:email, :with_attachment)
.
Adapters
Griddler::Email
expects certain parameters to be in place for proper parsing
to occur. When writing an adapter, ensure that the normalized_params
method
of your adapter returns a hash with these keys:
-
:to
The recipient field -
:from
The sender field -
:subject
Email subject -
:text
The text body of the email -
:html
The html body of the email, nil or empty string if not present -
:attachments
(can be an empty array) Array of attachments to the email -
:headers
(optional) The raw headers of the email -
:charsets
(optional) A JSON string containing the character sets of the fields extracted from the message
Upgrading to Griddler 0.5.0
Because of an issue with the way Griddler handled recipients in the To
header,
a breaking change was introduced in Griddler 0.5.0 that requires a minor change
to EmailProcessor
or processor_class
.
Previously, a single address was returned from Griddler::Email#to
. Moving
forward, this field will always be an array. Generally speaking, you will want
to do something like this to handle the change:
Using Griddler with Mandrill
When adding a webhook in their administration panel, Mandrill will issue a HEAD request to check if the webhook is valid (see Adding Routes). If the HEAD request fails, Mandrill will not allow you to add the webhook. Since Griddler is only configured to handle POST requests, you will not be able to add the webhook as-is. To solve this, add a temporary route to your application that can handle the HEAD request:
Once you have correctly configured Mandrill, you can go ahead and delete this code.
More Information
- SendGrid
- SendGrid Parse API
- Cloudmailin
- Cloudmailin Docs
- Postmark
- Postmark Docs
- Mandrill
- Mandrill Docs
Credits
Griddler was written by Caleb Thompson and Joel Oliveira. It is maintained by Gabe Berke-Williams.
Large portions of the codebase were extracted from thoughtbot's Trajectory.
The names and logos for thoughtbot are trademarks of thoughtbot, inc.