README.md in postmark-rails-0.15.0 vs README.md in postmark-rails-0.16.0

@@ -12,29 +12,31 @@
 
 For Rails 2.3 please take a look at [version 0.4](https://github.com/wildbit/postmark-rails/tree/v0.4.2). It may miss some new features, but receives all required bug fixes and other support if needed.
 
 ## Configuring your Rails application
 
-Add this to your Gemfile: (change version numbers if needed)
+Add `postmark-rails` to your Gemfile (change version numbers if needed) and run `bundle install`.
 
 ``` ruby
 gem 'postmark-rails', '~> 0.15.0'
 ```
 
-Don’t forget to run `bundle install` command every time you change something in the Gemfile.
+Save your Postmark API token to [config/secrets.yml](http://guides.rubyonrails.org/4_1_release_notes.html#config-secrets-yml).
 
-Add this to your config/application.rb:
+``` yaml
+postmark_api_token: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+```
 
+Set Postmark as your preferred mail delivery method via `config/application.rb`:
+
 ``` ruby
 config.action_mailer.delivery_method = :postmark
-config.action_mailer.postmark_settings = { :api_token => "your-api-token" }
+config.action_mailer.postmark_settings = { :api_token => Rails.application.secrets.postmark_api_token }
 ```
 
-The `postmark_settings` hash can contain [all options](https://github.com/wildbit/postmark-gem#communicating-with-the-api) supported by `Postmark::ApiClient`.
+**Note**: The `postmark_settings` hash can contain [any options](https://github.com/wildbit/postmark-gem#communicating-with-the-api) supported by `Postmark::ApiClient`.
 
-For the API details, refer to the [developer documentation](http://developer.postmarkapp.com).
-
 ## Tracking opens and tagging your deliveries
 
 You can use tags to categorize outgoing messages and attach application-specific information. Tagging the different types of email that you send lets you [review statistics and bounce reports separately](http://developer.postmarkapp.com/developer-build.html#message-format).
 
 Pass `:track_opens => 'true'` to enable/disable open tracking on per-message basis. Check out the [Triggers API](https://github.com/wildbit/postmark-gem/wiki/The-Triggers-API-Support) to see how Postmark can help you control this with tags. **Note that we pass a string here, since it becomes a header value. Passing a boolean may or may not work depending on your Rails version.**
@@ -100,10 +102,105 @@
 
 messages.all?(&:delivered)
 # => true
 ```
 
+## Error handling
+
+The gem respects the `ActionMailer::Base.raise_delivery_errors` setting and will surpress any exceptions
+if it’s set to `false`. When delivery errors are enabled, the gem can raise any one of the exceptions
+listed in the [postmark](https://github.com/wildbit/postmark-gem#error-handling) gem docs.
+
+
+### ActionMailer 5
+
+For ActionMailer 5 and above, use `ActionMailer::Base.rescue_from` to define handlers for
+each error you care about.
+
+#### Example
+
+``` ruby
+class ApplicationMailer < ActionMailer::Base
+  default from: '[e-mail]'
+  layout 'mailer'
+
+  rescue_from Postmark::InactiveRecipientError, with: :reactivate_and_retry
+
+  private
+
+  def postmark_client
+    ::Postmark::ApiClient.new(ActionMailer::Base.postmark_settings[:api_token],
+                              ActionMailer::Base.postmark_settings.except(:api_token))
+  end
+
+
+  # This is just an example. Sometimes you might not want to reactivate
+  # an address that hard bounced.
+  # Warning: Having too many bounces can affect your delivery reputation
+  # with email providers
+  def reactivate_and_retry(error)
+    Rails.logger.info("Error when sending #{message} to #{error.recipients.join(', ')}")
+    Rails.logger.info(error)
+
+    error.recipients.each do |recipient|
+      bounce = postmark_client.bounces(emailFilter: recipient).first
+      next unless bounce
+      postmark_client.activate_bounce(bounce[:id])
+    end
+
+    # Try again immediately
+    message.deliver
+  end
+end
+```
+
+### ActionMailer 4 and below
+
+Wrap any calls to `#deliver_now` in error handlers like the one described
+in the [postmark](https://github.com/wildbit/postmark-gem#error-handling) gem
+docs.
+
+Rails 4.2 introduces `#deliver_later` but doesn’t support `rescue_from` for
+mailer classes. Instead, use the following monkey patch for
+`ActionMailer::DeliveryJob`.
+
+``` ruby
+# app/mailers/application_mailer.rb
+
+class ApplicationMailer < ActionMailer::Base
+  default from: '[e-mail]'
+end
+
+class ActionMailer::DeliveryJob
+  rescue_from Postmark::InactiveRecipientError, with: :reactivate_and_retry
+
+  def postmark_client
+    ::Postmark::ApiClient.new(ActionMailer::Base.postmark_settings[:api_token],
+                              ActionMailer::Base.postmark_settings.except(:api_token))
+  end
+
+
+  # This is just an example. Sometimes you might not want to reactivate
+  # an address that hard bounced.
+  # Warning: Having too many bounces can affect your delivery reputation
+  # with email providers
+  def reactivate_and_retry(error)
+    Rails.logger.info("Error when sending a message to #{error.recipients.join(', ')}")
+    Rails.logger.info(error)
+
+    error.recipients.each do |recipient|
+      bounce = postmark_client.bounces(emailFilter: recipient).first
+      next unless bounce
+      postmark_client.activate_bounce(bounce[:id])
+    end
+
+    # Try again immediately
+    perform(*arguments)
+  end
+end
+```
+
 ## Additional information
 
 Looking for the advanced usage examples? Check out [the documentation](https://github.com/wildbit/postmark-gem/blob/master/README.md) for the `postmark` gem. The `postmark-rails` gem is built on top of it, so you can benefit from all its features.
 
 ## Requirements
@@ -131,6 +228,6 @@
 * Nicolás Sanguinetti
 * Laust Rud Jacobsen (rud)
 
 ## Copyright
 
-Copyright © 2010—2013 Wildbit LLC. See LICENSE for details.
+Copyright © 2010—2018 Wildbit LLC. See LICENSE for details.