Mailgun Tracking
This gem provides a simple way for integration with Mailgun Webhooks.
Installation
Add this line to your application's Gemfile:
gem 'mailgun-tracking'
And then execute:
bundle
Or install it yourself as:
gem install mailgun-tracking
Configurations
To integrate Mailgun Tracking with your Rails application, you need to know
your api key and endpoint. Invoke the following command
and replace API_KEY
and ENDPOINT
with your values:
rails generate mailgun:tracking:install API_KEY ENDPOINT
This command will generate the Mailgun Tracking configuration file under
config/initializers/mailgun_tracking.rb
.
Usage
Rails
Mailgun::Tracking.configure do |config|
config.on 'delivered' do |payload|
# Do something with the incoming data.
end
config.all do |payload|
# Handle all event types.
end
end
Subscriber objects that respond to #call
class Bounced
def initialize(logger)
@logger = logger
end
def call(payload)
@logger.info(payload)
end
end
Mailgun::Tracking.configure do |config|
config.on 'bounced', Bounced.new(Rails.logger)
end
Sinatra
To use Mailgun Tracking with Sinatra, simply require
the gem, configure it and use
our Rack middleware.
require 'sinatra/base'
require 'mailgun/tracking'
Mailgun::Tracking.configure do |config|
config.api_key = 'key-qblubkqnkdn4lfes5oscf57ryllaia42'
config.endpoint = '/mailgun'
config.on 'bounced', Bounced.new
config.all do |payload|
# Handle all event types.
end
end
class Application < Sinatra::Base
use Mailgun::Tracking::Middleware
end
run Application.run!
Testing
Handling webhooks is a critical piece of modern systems. Verifying the behavior of Mailgun::Tracking
subscribers
can be done fairly easily by stubbing out the HTTP signature header used to authenticate the webhook request.
RequestBin is great for collecting the payloads. For exploratory phases of development,
UltraHook and other tools can forward webhook requests directly to the localhost.
Here an example of how to test Mailgun::Tracking
with RSpec request specs:
RSpec.describe 'Mailgun Webhooks' do
describe 'delivered' do
let(:payload) { File.read('spec/support/fixtures/delivered.json') }
let(:bounced) { instance_double(Bounced) }
before do
allow(bounced).to receive(:call)
allow(Bounced).to receive(:new).and_return(bounced)
end
it 'is successful' do
post('/mailgun', body: payload)
expect(bounced).to have_received(:call).with(payloads)
end
end
end
License
The gem is available as open source under the terms of the MIT License.