Courier Rails

This gem provides seamless integration of Courier with ActionMailer. It provides a delivery_method based upon the Courier API, and makes getting setup and sending notifications in a Rails app using Courier easier.

Installation

Add this line to your application's Gemfile:

gem 'courier_rails'

And then execute:

$ bundle install

Configuration

Retrieve your Courier Authentication Token. By default, the gem will look for your token in your environment, with the key COURIER_AUTH_TOKEN. You can override this key by setting it manually in the file config/initializers/courier_rails.rb:

CourierRails.configure do |c|
  c.api_key = 'your-auth-token'
end

Then, edit config/application.rb or config/environments/$ENVIRONMENT.rb and add/change the following to the ActionMailer configuration:

config.action_mailer.delivery_method = :courier

Usage

Normal ActionMailer usage will now send notifications from the Courier template designer, using the Courier API:

data = {
    event: "EVENT_ID",
    recipient: "RECIPIENT_ID",
    data: {
        hello: "Rails!"
    }
}

mail(to: "[email protected]", body: "not used", courier_data: data)

The "body" parameter is required for ActionMailer, even though the email body is already described by the notification designer. You can also add default body: not used to the top of your mailer instead of this parameter.

The elements of "courier_data" are described below:

event (required)

The unique identification key of a notification template to be sent. If the notification is mapped to an event key, use the event key here instead.

recipient (optional)

The unique identification key attached to a recipient and their profile. The value should be a string, all other values will be converted to a string. If empty, the code will either use the email provided in the to or auto-generate a unique key.

profile (optional)

An object that includes the profile data attached to this message. For example,

c_data={
    event: "your.event.key"
    profile:{
        phone_number: "555-123-4567",
        name: "Jane Doe"
        email: "[email protected]"
        ...
    }
}
mail(body: "not used", courier_data: c_data)

As shown above, the recipient's email can be set inside of the profile instead of using the ActionMailer to:"email" parameter. When both are used, however, the "to" parameter overrides the profile email.

data (optional)

An object that includes any data you want to pass to a Courier template. The data will populate the corresponding template variables.

When calling the deliver! method on the mail object returned from your mailer. CourierRails provides the response data directly back from Courier in a Courier::SendResponse object.

result = MyMailer.welcome_message(user).deliver!
puts result.code # Status Code
puts result.message_id # Message ID

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/trycourier/courier_rails. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct. See CONTRIBUTING.md for more info.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the CourierRails project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.