# griddler

**Repository Path**: mirrors_thoughtbot/griddler

## Basic Information

- **Project Name**: griddler
- **Description**: Simplify receiving email in Rails (deprecated)
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2020-08-18
- **Last Updated**: 2026-01-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

## Deprecated as of June 6, 2024

Griddler has been deprecated in favor of [ActionMailbox](https://guides.rubyonrails.org/action_mailbox_basics.html) since this is built into Rails now.

Griddler
========

### Receive emails in your Rails app

Griddler is a Rails engine that provides an endpoint for services that convert
incoming emails to HTTP POST requests. It parses these POSTs and hands off a
built email object to a class implemented by you.

Tutorials
---------

* SendGrid wrote a
  [great tutorial](https://sendgrid.com/blog/receiving-email-in-your-rails-app-with-griddler/)
  on integrating Griddler with your application.
* We have our own blog post on the subject over at
  [Giant Robots](https://robots.thoughtbot.com/griddler-is-better-than-ever).

Installation
------------

1. Add `griddler` and an [adapter] gem to your application's Gemfile
   and run `bundle install`.

   [adapter]: #adapters

2. A route is needed for the endpoint which receives `POST` messages. To add the
   route, in `config/routes.rb` you may either use the provided routing method
   `mount_griddler` or set the route explicitly. Examples:

   ```ruby
   # config/routes.rb

   # mount using default path: /email_processor
   mount_griddler

   # mount using a custom path
   mount_griddler('/email/incoming')

   # the DIY approach:
   post '/email_processor' => 'griddler/emails#create'
   ```

### 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/initializers/griddler.rb`:

```ruby
Griddler.configure do |config|
  config.processor_class = EmailProcessor # CommentViaEmail
  config.email_class = Griddler::Email # MyEmail
  config.processor_method = :process # :create_comment (A method on CommentViaEmail)
  config.reply_delimiter = '-- REPLY ABOVE THIS LINE --'
  config.email_service = :sendgrid # :cloudmailin, :postmark, :mandrill, :mailgun
end
```

| Option             | Meaning
| ------             | -------
| `processor_class`  | The class Griddler will use to handle your incoming emails.
| `email_class`      | The class Griddler will use to represent an incoming e-mail. It must support an initializer that receives a hash as the only argument. We recommend inheriting it from Griddler::Email or checking this class to see all the methods it responds to.
| `processor_method` | The method Griddler will call on the processor class when handling your incoming emails.
| `reply_delimiter`  | The string searched for that will split your body. You can also supply an array of string - useful if you need translated versions of the delimiter
| `email_service`    | Tells Griddler which email service you are using. The supported email service options are `:sendgrid` (the default), `:cloudmailin` (expects multipart format), `:postmark`, `:mandrill` and `:mailgun`. You will also need to have an appropriate [adapter] gem included in your Gemfile.

By default Griddler will look for a class named `EmailProcessor`. The class is
initialized with a `Griddler::Email` instance representing the incoming
email, and has a `process` method to actually process the email.
For example, in `./lib/email_processor.rb`:

```ruby
class EmailProcessor
  def initialize(email)
    @email = email
  end

  def process
    # all of your application-specific code here - creating models,
    # processing reports, etc

    # here's an example of model creation
    user = User.find_by_email(@email.from[:email])
    user.posts.create!(
      subject: @email.subject,
      body: @email.body
    )
  end
end
```

Griddler::Email attributes
--------------------------

| Attribute      | Description
| -------------- | -----------
| `#to`          | An array of hashes containing recipient address information.  See [Email Addresses](#email-addresses) for more information.
| `#from`        | A hash containing the sender address information.
| `#cc`          | An array of hashes containing cc email address information.
| `#subject`     | The subject of the email message.
| `#body`        | 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.
| `#raw_text`    | The raw text part of the body.
| `#raw_html`    | The raw html part of the body.
| `#raw_body`    | The raw body information provided by the email service.
| `#attachments` | An array of `File` objects containing any attachments.
| `#headers`     | A hash of headers parsed by `Mail::Header`, unless they are already formatted as a hash when received from the adapter in which case the original hash is returned.
| `#raw_headers` | The raw headers included in the message.
| `#to_h`        | A hash of the above attributes.

### Email Addresses

Gridder::Email provides email addresses as hashes. Each hash will have the following
information of each recipient:

| Key | Value
| --- | -----
| `:token` | All the text before the email's "@". 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.
| `:host` | All the text after the email's "@". This is important to filter the recipients sent to the application vs emails to other domains. More info below on the Upgrading to 0.5.0 section.
| `:email` | The email address of the recipient.
| `:full` | The whole recipient field (e.g., `Some User <hello@example.com>`).
| `:name` | The name of the recipient (e.g., `Some User`).

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:

```ruby
factory :email, class: OpenStruct do
  # Assumes Griddler.configure.to is :hash (default)
  to { [{ full: 'to_user@email.com', email: 'to_user@email.com', token: 'to_user', host: 'email.com', name: nil }] }
  from { { token: 'from_user', host: 'email.com', email: 'from_email@email.com', full: 'From User <from_user@email.com>', name: 'From User' } }
  subject { 'email subject' }
  body { 'Hello!' }
  attachments { '0' }

  trait :with_attachment do
    attachments {[
      ActionDispatch::Http::UploadedFile.new({
        filename: 'img.png',
        type: 'image/png',
        tempfile: File.new("#{File.expand_path(File.dirname(__FILE__))}/fixtures/img.png")
      })
    ]}
  end
end
```

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 tests, build with `email = build(:email)`
or `email = build(:email, :with_attachment)`.

Adapters
--------

Depending on the service you want to use Griddler with, you'll need to add an
adapter gem in addition to `griddler`.

| Service     | Adapter
| -------     | -------
| sendgrid    | [griddler-sendgrid]
| cloudmailin | [griddler-cloudmailin]
| mandrill    | [griddler-mandrill]
| mailgun     | [griddler-mailgun]
| postmark    | [griddler-postmark]
| sparkpost   | [griddler-sparkpost]
| ses (amazon)| [griddler-amazon_ses]

[griddler-sendgrid]: https://github.com/thoughtbot/griddler-sendgrid
[griddler-cloudmailin]: https://github.com/thoughtbot/griddler-cloudmailin
[griddler-mandrill]: https://github.com/wingrunr21/griddler-mandrill
[griddler-mailgun]: https://github.com/bradpauly/griddler-mailgun
[griddler-postmark]: https://github.com/r38y/griddler-postmark
[griddler-sparkpost]: https://github.com/PrestoDoctor/griddler-sparkpost
[griddler-amazon_ses]: https://github.com/ccallebs/griddler-amazon_ses

Writing an Adapter
------------------

Griddler can theoretically work with any email => POST service. In order to work
correctly, adapters need to have their POST parameters restructured.

`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:

| Parameter      | Contents
| ---------      | --------
| `: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, or an empty string
| `:attachments` | Array of attachments to the email. Can be an empty array.
| `:headers`     | The raw headers of the email. **Optional**.
| `:charsets`    | A JSON string containing the character sets of the fields extracted from the message. **Optional**.

All keys are required unless otherwise stated.

Adapters should be provided as gems. If you write an adapter, let us know and we
will add it to this README. See [griddler-sendgrid] for an example
implementation.

Credits
-------

Griddler was written by Caleb Hearth and Joel Oliveira.

Thanks to our [contributors](https://github.com/thoughtbot/griddler/contributors)!

<!-- START /templates/footer.md -->
## About thoughtbot

![thoughtbot](https://thoughtbot.com/thoughtbot-logo-for-readmes.svg)

This repo is maintained and funded by thoughtbot, inc.
The names and logos for thoughtbot are trademarks of thoughtbot, inc.

We love open source software!
See [our other projects][community].
We are [available for hire][hire].

[community]: https://thoughtbot.com/community?utm_source=github
[hire]: https://thoughtbot.com/hire-us?utm_source=github

<!-- END /templates/footer.md -->