Rails Engine to provide Postmark configuration and support for Rails 3.2.x applications.
Ruby HTML JavaScript CSS
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
lib
test
.gitignore
.rubocop.yml
.ruby-version
.travis.yml
Gemfile
LICENSE
README.md
Rakefile
thincloud-postmark.gemspec

README.md

thincloud-postmark

Gem Version Dependency Status Build Status Code Climate Test Coverage

Description

Rails Engine to provide Postmark configuration for Thincloud applications.

The Thincloud::Postmark engine:

  • Manages all of the Postmark dependencies for your application
  • Optionally registers a Mail interceptor

Requirements

This gem requires Rails 3.2+ and has been tested on the following versions:

  • 3.2

This gem has been tested against the following Ruby versions:

  • 2.0
  • 2.1
  • 2.2

Installation

Add this line to your application's Gemfile:

gem "thincloud-postmark"
  • Run bundle

Or install it yourself as:

$ gem install thincloud-postmark

Usage

Thincloud::Postmark is only enabled for environments included in the environments array. For instance, to use Postmark in development and staging the list would look like this:

[:development, :staging]

The different configuration options and detailed below.

Configuration

Thincloud::Postmark configuration options are available to customize the engine behavior. Available options and their default values:

# Rails environment(s) that should use the `postmark` delivery method.
environments              = []
api_key                   = "POSTMARK_API_TEST"
interceptor_to            = nil
interceptor_cc            = nil
interceptor_bcc           = nil

# Rails environment(s) that should have mail intercepted.
interceptor_environments  = []

Note: Don't forget to set the default_url_options

config.action_mailer.default_url_options = { host: "mydomain.com" }

Environment Variables

Several of the options will use environment variables when found.

api_key          # ENV["POSTMARK_API_KEY"]
secure           # ENV["POSTMARK_SECURE"]
interceptor_to   # ENV["THINCLOUD_INTERCEPTOR_TO"]
interceptor_cc   # ENV["THINCLOUD_INTERCEPTOR_CC"]
interceptor_bcc  # ENV["THINCLOUD_INTERCEPTOR_BCC"]

Configuration Block

The Thincloud::Postmark module accepts a configure block that takes the same options listed above. This block can be put into an initializer or inside of a config\environments file.

Thincloud::Postmark.configure do |config|
  config.environments   = [:development, :production]
  config.api_key        = "MY_API_KEY"
  config.secure         = true
  config.interceptor_to = "keymaster@zuul.com"
  config.interceptor_cc = "gatekeeper@zuul.com"
  config.interceptor_environments = [:test, :development]
  # ...
end

Rails Configuration

You can also access the configuration via the Rails configuration object. In fact, the engine uses the Rails config as storage when the block syntax is used. The Thincloud::Postmark::Configuration object is made available under config.thincloud.postmark. You can access this configuration in config/application.rb or in your config/environments files.

#...
config.thincloud.postmark.environments = [:development, :production]
config.thincloud.postmark.api_key = "MY_API_KEY"
config.thincloud.postmark.secure  = false
config.thincloud.postmark.interceptor_environments = [:staging]
#...

Note: Configuration values take precendence over environment variables.

Default Interceptor

The default interceptor is registered for environments included in the interceptor_environments array. It replaces the recipients with those contained in the configuration and replaces the subject of outgoing email with the original to combined with the original subject.

class Thincloud::Postmark::Interceptor
  # ...
  def self.delivering_email(message)
    message.subject = "#{message.to} #{message.subject}"
    message.to      = self.to
    message.cc      = self.cc
    message.bcc     = self.bcc
    message
  end
end

Overriding the Interceptor

You may find that the default Interceptor does not meet your requirements. In that case you can easily create your own and prevent the default from being registered.

  • Disable the default interceptor
interceptor_environments = []
  • Create your interceptor
# Public: Mail Interceptor to use when overriding defaults
class MailInterceptor
  def self.delivering_email(message)
    message.subject = "#{message.to} #{message.subject}"
    message.to      = "#{ENV["USER"]}@localhost"
    message.cc      = nil
    message.bcc     = nil
  end
end
  • Register your interceptor in an initializer
require "mail_interceptor"

Mail.register_interceptor(MailInterceptor) unless Rails.env.production?

Contributing

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

License