A webhook event manager for Mailgun
Ruby HTML JavaScript CSS
Latest commit cc56429 Dec 23, 2015 Doug Avery Adding code.viget.com plug to README
Failed to load latest commit information.
config Change root path to accept POST Nov 13, 2013
lib Bump version to 0.1.3 Mar 27, 2015
spec Update specs with lowercased message_id parameter name Mar 27, 2015
.coveralls.yml Add Coveralls configuration Jan 16, 2014
.gitignore Initial creation of SpecialDelivery engine Nov 13, 2013
.travis.yml Configure Travis CI Jan 16, 2014
Gemfile Initial creation of SpecialDelivery engine Nov 13, 2013
README.md Adding code.viget.com plug to README Dec 23, 2015
README.rdoc Initial creation of SpecialDelivery engine Nov 13, 2013
special-delivery.gemspec Add Coveralls configuration Jan 16, 2014


Code Climate Coverage Status Build Status Gem Version

Special Delivery

A Mailgun Webhook Event Manager

Special Delivery is a Rails engine that enables powerful and easy-to-use callbacks in response to Mailgun events POSTed via webhook.

Say what now? Example time:

Let's say you have an application that sends an email to notify a user that they have won the lottery. This email is obviously pretty important, so we'd like to send a message to an admin if the lottery-winner email bounces. How the heck do we do that?

Special Delivery saves a reference to each outgoing email messages to recreate state when Mailgun informs your application that a particular event occured for that message.

So by using Special Delivery when sending out a lottery-winner email, the application is then able to listen for bounce events for that particular email, and evaluate a callback with knowlege of the user record to which the email was originally sent.


You know the drill. Add the gem to your Gemfile.

gem 'special-delivery'


Set Your API Key

Your mailgun API key is used to authenticate webhook requests from Mailgun, and must be accessible via MAILGUN_CONFIG[:api_key].

Routes File

Mount Special Delivery as an engine within your config/routes.rb at a path of your choosing. Make sure to then point your Mailgun webhooks to this URL.

mount SpecialDelivery::Engine => "/email_events"

Your Custom Callback Class File

Create a new class to handle callbacks initiated by Mailgun POST requests made to your app. Callbacks for the specific types of Mailgun events should be defined as methods within your class. Your class can respond to as many or as few of Mailgun's event types as you would like. Event types include bounced, clicked, complained, delivered, dropped, opened, and unsubscribed.

So if we want a callback class to manage sending a message to an admin when our lottery winner emails bounce, we would write:

class LotteryEmail::WinnerCallback < SpecialDelivery::Callback
  def bounced(user)
    send_message_to_admin "#{user.name} did not receive their lottery winner email."

And if we wanted to send a different message to the admin when the email was opened, we could add a method to the callback class:

def opened(user)
 send_message_to_admin "#{user.name} just opened their lottery winner email."

Mailer Files

Include the Mailer helper module in your mailer class (e.g. app/mailers/lottery_mailer.rb if you wanted to use Special Delivery in your LotteryMailer.

class LotteryMailer < ActionMailer::Base
  include SpecialDelivery::Mailer


Within your mailer's methods, pass your mail method calls into special_delivery as a block. Pass the special_delivery method call a hash containing at least your callback class (at :callback_class of course). You may optionally provide an ActiveRecord object for :callback_record that will be passed into your callback method as an argument.

def winner_email(user)
    :callback_class  => LotteryEmail::WinnerCallback,
    :callback_record => user
  ) do
    mail(:to => user.email, :subject => 'All the Monies!')

Code At Viget

Visit code.viget.com to see more projects from Viget.