Gem Version Build Status Code Climate Test Coverage

Recoil makes sure you're Amazon SES reputation is preserved by blacklisting emails with a bad reputation. Recoil does this with two simple tools: 1. A HTTP-endpoint to receive bounce notifications and saves them in the database. 2. A ActionMailer interceptor which is able to filter emails with high-bounce rates.

Getting started

Recoil works with Rails 4.0 onward. You can add it to you Gemfile with:

gem 'recoil'

Run the bundle command to install it. After you've installed Recoil you need to copy the migrations and migrate the database:

rake recoil:install:migrations
rake db:migrate

Add the endpoint to your routes.rb:

mount Recoil::Engine => '/ses'

Add an initializer: config/initializers/recoil.rb to initialize the interceptor:


You're now ready to subscribe to SNS-notifications. Go to the SES-dashboard > Topics > Create new topic, give it a name and save it. Create a new http/https subscription for this topic with the Recoil-URL as endpoint. Make sure Recoil is mounted to this URL because SNS wil send a verification request as soon as you add the subscription. Lastly, when the subscription is added and verified, you're able to let SES send notifications to the SNS topic. This is configurable in the SES-dashboard.


There is just a single configuration option for recoil: blacklist_threshold. This is a lamdba with an ActiveRecord-scope as argument. The default configuration is do blacklist all email with 10+ bounces in the last two weeks. This is a very loose policy, but it's easy to change:

# config/initializers/recoil.rb
  Recoil.setup do |c|
    c.blacklist_threshold = ->(scope) { scope.where('created_at > ?', 1.week.ago).count > 10 }


You can view the Recoil documentation in RDoc format here:


  1. Fork it ( )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request