Repository is archived
No release in over 3 years
Low commit activity in last 3 years
Integration with Mailgun Webhooks
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies

Development

~> 2.2
~> 13.0
~> 3.7
~> 0.79.0
~> 0.17.1

Runtime

~> 0.1.2
 Project Readme

Mailgun Tracking

Gem Version Badge Build Badge Gem Downloads Badge Code Climate Badge Test Coverage Badge Inline Docs Badge

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.