Skip to content
This repository has been archived by the owner on Jun 27, 2023. It is now read-only.

Mailgun webhook integration for Rack/RoR application

License

Notifications You must be signed in to change notification settings

chubchenko/mailgun-tracking

Folders and files

NameName
Last commit message
Last commit date

Latest commit

May 15, 2021
d145acc · May 15, 2021
May 15, 2021
Feb 4, 2020
Dec 31, 2020
May 15, 2021
Dec 31, 2020
Feb 4, 2020
Jan 30, 2020
Feb 5, 2020
May 12, 2018
Feb 5, 2020
Jan 4, 2021
May 17, 2020
Jan 4, 2021
Feb 5, 2020
Feb 5, 2020
Feb 3, 2020
Jul 8, 2017
Feb 3, 2020
Feb 4, 2020
Feb 5, 2020
Jan 4, 2021

Repository files navigation

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.