Webhook processing and event decoration to make using Mandrill with Rails just that much easier
Webhook processing and event decoration to make using Mandrill with Rails just that much easier
The primary goal of Mandrill::Rails is to make supporting Mandrill web hooks as easy and Rails-native as possible. As other opportunities for better Rails integration of the Mandrill API are discovered, these may be rolled in too.
I thought about implementing this as an engine, but the overhead did not seem appropriate. Maybe that view will change..
Mandrill::Rails currently does not need or require any direct Mandrill API integration, such as provided by various Mandrill and MailChimp gems. If you need direct API integration in addition to Mandrill::Rails features, you can choose to add whichever best meets your needs.
FYI, Mandrill is the transactional email service by the same folks who do MailChimp.
For Rails 7+, use Action Mailbox instead. Mandrill::Rails is no longer being maintained for newer Rails versions.
Mandrill::Rails 1.5.0+ supports Rails 5 and Rails 6.
For Rails >= 3.0.3, use Mandrill::Rails 1.4.1.
Add this line to your application's Gemfile:
gem 'mandrill-rails'And then execute:
bundleOr install it yourself as:
gem install mandrill-railsIf you want to work on enhancements or fix bugs in Mandrill::Rails, fork and clone the github repository. If you are using bundler (recommended), run bundle to install development dependencies.
Run tests using rake or rake spec, and note that guard is also included with the development dependencies so
you can kick-off continuous testing of changed files by running bundle exec guard.
See the section below on 'Contributing to Mandrill::Rails' for more information.
Say we have configured Mandrill to send requests to /inbox at our site (see the next recipes for how you do that).
Once we have Mandrill::Rails in our project, we just need to do two things. You can run a generator to do it for you, or you can configure things manually:
Run the generator and specify the name for your route and controller:
rails generate mandrill inboxThis will create a resource route and corresponding controller at /inbox.
If you need a namespaced controller, specify it in the name:
rails generate mandrill hooks/inboxThis creates an inbox route that points to the Hooks:InboxController class.
If you prefer pluralized names, that can be specified with a flag:
rails generate mandrill inbox --pluralize_namesThis will create an InboxesController class and a resource route called inboxes.
First, configure a resource route:
resource :inbox, :controller => 'inbox', :only => [:show,:create]Next, create the corresponding controller:
class InboxController Once we have configured Mandrill and setup our routes and controllers, our app will successfully receive WebHook event notifications from Mandrill. But we are not doing anything with the payload yet.
To handle specific Mandrill event payloads, we just need to implement a handler for each event type we are interested in.
The list of available event types includes: inbound, send, hard_bounce, soft_bounce, open, click, spam, unsub, and reject.
In our controller, we simply write a method called handle_ and it will be called
for each event payload received. The event payload will be passed to this method
as a Mandrill::WebHook::EventDecorator - basically a Hash with some additional methods to
help extract payload-specific elements.
For example, to handle inbound email:
class InboxController "click"
event_payload['ts']
=> 1350377135
event_payload['msg']
=> {...}If you would like examples of the actual data structures sent by Mandrill for different event types, some are included in the project source under spec/fixtures/webhook_examples.
In addition to providing full Hash-like access to the raw message, the event_payload object
(a Mandrill::WebHook::EventDecorator) provides a range of helper methods for some of the more obvious
things you might need to do with the payload. Here are some examples (see
Mandrill::WebHook::EventDecorator class documentation
for full details)
event_payload.message_id
# Returns the message_id.
# Inbound events: references 'Message-Id' header.
# Send/Open/Click events: references '_id' message attribute.
event_payload.user_email
# Returns the subject user email address.
# Inbound messages: references 'email' message attribute (represents the sender).
# Send/Open/Click messages: references 'email' message attribute (represents the recipient).
event_payload.references
# Returns an array of reference IDs.
# Applicable events: inbound
event_payload.recipients
# Returns an array of all unique recipients (to/cc)
# [ [email,name], [email,name], .. ]
# Applicable events: inbound
event_payload.recipient_emails
# Returns an array of all unique recipient emails (to/cc)
# [ email, email, .. ]
# Applicable events: inboundIt's likely you may benefit from adding more application-specific intelligence to the
event_payload object.
There are many ways to do this, but it is quite legitimate to reopen the EventDecorator class and add your own methods if you wish.
For example event_payload.user_email returns the subject user email address, but perhaps I will commonly want to
match that with a user record in my system. Or I similarly want to resolve event_payload.recipient_emails to user records.
In this case, I could extend EventDecorator in my app like this:
# Extends Mandrill::WebHook::EventDecorator with app-specific event payload transformation
class Mandrill::WebHook::EventDecorator
# Returns the user record for the subject user (if available)
def user
User.where(email: user_email).first
end
# Returns user records for all to/cc recipients
def recipient_users
User.where(email: recipient_emails)
end
endThe EventDecorator class provides an attachments method to access an array of attachments (if any).
Each attachment is encapsulated in a class that describes the name, mime type, raw and decoded content.
For example:
def handle_inbound(event_payload)
if attachments = event_payload.attachments.presence
# yes, we have at least 1 attachment. Lets look at the first:
a1 = attachments.first
a1.name
# => e.g. 'sample.pdf'
a1.type
# => e.g. 'application/pdf'
a1.base64
# => true
a1.content
# => this is the raw content provided by Mandrill, and may be base64-encoded
# e.g. 'JVBERi0xLjMKJcTl8uXrp/Og0MTGCjQgMCBvY ... (etc)'
a1.decoded_content
# => this is the content decoded by Mandrill::Rails, ready to be written as a File or whatever
# e.g. '%PDF-1.3\n%\xC4\xE5 ... (etc)'
end
endThe EventDecorator class provides an images method to access an array of images (if any).
Each image is encapsulated in a class that describes the name, mime type, raw and decoded content.
For example:
def handle_inbound(event_payload)
if images = event_payload.images.presence
# yes, we have at least 1 image. Lets look at the first:
a1 = images.first
a1.name
# => e.g. 'sample.png'
a1.type
# => e.g. 'image/png'
a1.base64
# => true # always
a1.content
# => this is the raw content provided by Mandrill (always base64)
# e.g. 'iVBORw0K ... (etc)'
a1.decoded_content
# => this is the content decoded by Mandrill::Rails, ready to be written as a File or whatever
# e.g. '\x89PNG\r\n ... (etc)'
end
endMandrill::Rails currently does not need or require any direct Mandrill API integration (such as provided by various Mandrill and MailChimp gems). If you need direct API integration in addition to Mandrill::Rails features, you can choose to add whichever best meets your needs and use as normal.
Copyright (c) 2012 Paul Gallagher. See LICENSE for further details.
No open issues yet, or sync has not completed.