capistrano-mailgun

Capistrano::Mailgun

Bust a cap in your deployment notifications

Mailgun.org is an excellent, API-driven email provider. So, bust out your nine, pop in the clip and send emails easily from inside your Capistrano recipes.

Capistrano::Mailgun provides a simple interface for notifying of deploys, exposing your Capistrano variables to your ERB template built on top of a more robust public interface to the Mailgun API. It's built on top of Capnotify, so it's extensible via Capnotify plugins and accepts Capnotify configuration options.

Installation

Add this line to your application's Gemfile:

gem 'capistrano-mailgun', '~> 2.0'

And then execute:

$ bundle

Or install it yourself as:

$ gem install capistrano-mailgun

In your Capfile, add:

require 'capistrano-mailgun'

Quickstart

To send a notification after deploy, add the following to your deploy.rb file:

set :mailgun_api_key, 'key-12345678901234567890123456789012' # your mailgun API key
set :mailgun_domain, 'example.com' # your mailgun email domain
set :mailgun_from, '[e-mail]' # who the email will appear to come from
set :mailgun_recipients, [ '[e-mail]', '[e-mail]' ] # who will receive the email

# create an after deploy hook
after :deploy, 'mailgun_notify'

That's it. When you do a deploy, it should automatically send an email using the built-in text and HTML templates.

Capistrano::Mailgun defines a mailgun_notify task which calls the mailgun.notify_of_deploy function, using your Capistrano configuration to send the notification.

Example using mailgun.send_email

If you need a little more control over the message being sent or you want to bcc or be a little more conditional over what you're sending, see the following example, which should be placed in your deploy.rb file:

# when using send_email, the following 2 settings are REQUIRED
set :mailgun_api_key, 'key-12345678901234567890123456789012' # your mailgun API key
set :mailgun_domain, 'example.com' # your mailgun email domain

set :mailgun_recipient_domain, 'example.com' # append this to any unqualified email addresses

set(:email_body) { abort "Please set email_body using `-s email_body='this is the body of the email'" }

# some variables that we'll use when calling mailgun.send_email
set :ops_emails, [ 'alice', 'bob' ]
set :dev_emails, [ '[e-mail]', 'dave' ]

# some basic tasks
namespace :email do
  task :ops do
    mailgun.send_email(
      :to => ops_emails, # build_recipients gets called automatically by Capistrano::Mailgun
      :from => '[e-mail]',
      :subject => 'you have just been mailgunned',
      :text => email_body
    )
  end

  task :devs do
    mailgun.send_email(
      :to => '[e-mail]',
      :from => '[e-mail]',
      :bcc => mailgun.build_recipients(dev_emails, 'audit.example.com'), # note the different domain
      :subject => 'You guys are just developers',
      :text => email_body
    )
  end
end

This defines 2 tasks that can be used to send emails to ops or devs. The email:ops task is using an Capistrano variable email_body which should be set on the commandline. With this example, you could send an email to ops guys like the following:

cap email:ops -s email_body="You guys are awesome. Keep up the good work"

You could also take advantage of :text_template and/or :html_template for more complex messages. The above is just an example.

Also, notice the use of mailgun.build_recipients. See documentation below for more information.

Disabling Emails

If you want to prevent sending any email notifications for any reason, you can set the mailgun_off Capistrano variable either via the set command or with the -s commandline options when calling cap.

If using the Capistrano multistage plugin, you can put the following into one of your stage files that you want to disable notifications for:

set :mailgun_off, true

Or, when doing a normal deploy and you want to prevent notifications for this deploy, you can do the following:

cap deploy -s mailgun_off=1

Heads up: Setting mailgun_off to anything will disable emails. This includes setting it to false.

Capistrano Variables

Capistrano::Mailgun leverages variables defined in Capistrano to reduce the amount of configuration you need to do. The following are all variables it supports:

mailgun_api_key (required)

Your API key. This MUST include the key- prefix.

mailgun_domain (required)

The domain of your Mailgun account. This is used when calling the API and is required.

mailgun_from (required for notify_of_deploy)

The email address that your notifications will appear to come from (by default).

mailgun_recipients (required for notify_of_deploy)

The email address as a string or an array of email addresses who should recieve an email from notify_of_deploy.

You can optionally only specify just the part of the email address before the @ and Capistrano::Mailgun will automatically append the mailgun_recipient_domain to it. See mailgun_recipient_domain.

If you omit the domain and don't specify mailgun_recipient_domain, a error will be raised.

mailgun_cc

An array of email addresses who should be CC'd when mailgun.notify_of_deploy is called. This will follow the same rules as the mailgun_recipients variable with respect to the handling of unqualified email addresses.

mailgun_bcc

An array of email addresses who should be BCC'd when mailgun.notify_of_deploy is called. This will follow the same rules as the mailgun_recipients variable with respect to the handling of unqualified eail addresses.

mailgun_recipient_domain

The domain that will be automatically appended to incomplete email addresses in the mailgun_recipients.

Example:

set :mailgun_recipient_domain, 'example.com'
set :mailgun_recipients, [ 'alice', 'bob', '[e-mail]' ]

When an email is sent from Capistrano::Mailgun, the recipients will be processed and the email will be sent to:

• [e-mail]
• [e-mail]
• [e-mail]

If mailgun_recipient_domain is not set, Capistrano::Mailgun will raise an error.

mailgun_subject

The subject to be used in deployment emails. This defaults to:

[Deployment] #{ application.capitalize } deploy completed

In the event that you're using multistage, it will include that:

[Deployment] #{ stage.capitalize } #{ application.capitalize } deploy completed

Setting this variable yourself will override the default.

mailgun_message

An optional message can be specified to be included in the email. This is used inside the default templates, so if you use your own templates, you'll have to include support for this variable yourself.

The purpose of this variable is to be set when calling capistrano so you can have a custom, per-deploy message. You would call it in the following manner:

cap deploy -s mailgun_message="Fixes that really nasty bug where our site does not work"

mailgun_off

Setting mailgun_off to any value, either via the -s commandline switch or with set in your recipe will completely disable any Mailgun notifications, regardless of whether they're sent with mailgun.send_email or with the built-in mailgun_notify task.

See above Disabling Emails section for examples.

Capistrano Tasks

mailgun_notify

This task is defined strictly for convenience in defining Capistrano hooks and for sending a notification from the commandline. All it does is run mailgun.notify_of_deploy on your local machine.

Normally, you'd want to have an after-hook on deploy defined as follows:

after :deploy, 'mailgun_notify'

Function API

Capistrano::Mailgun has a couple of functions to simplify some common tasks. The following are the functions:

mailgun.build_recipients( recipients, default_domain=nil )

Given an array of email addresses, this will join them with a comma so any recipients field with more than 1 recipient will be formatted properly, have the recipients list deduplicated and returned as a string. Typically, you will not call this function directly as Capistrano::Mailgun calls it implicitely on your to, cc and bcc fields before hitting the Mailgun API.

You can also pass an alternate default_domain. This is useful if you're not using the global mailgun_recipient_domain Capistrano variable of if you want to override the behavior in a specific case. mailgun.build_recipients will always choose the specified default_domain passed to the function over the Capistrano variable mailgun_recipient_domain.

mailgun.notify_of_deploy

This is a convenience function to send an email via the Mailgun api using your Capistrano variables for declarative configuration. It will use mailgun_html_template and mailgun_text_template to generate the email body when set, mailgun_recipients for who to address the email to, mailgun_from for the reply-to field of the email and mailgun_subject for the subject of the email.

See Quickstart, above, for an example.

mailgun.send_email( options )

This is the base function for operating the Mailgun API. It uses the mailgun_api_key and mailgun_domain Capistrano variables for interacting with the service. If you need additional control over headers and options when sending the emails, call this function directly. For a full list of options, see the Mailgun REST API documentation:

http://documentation.mailgun.net/api-sending.html

The templates will have access to all of your Capistrano variables and anything else that Capistrano can see such as methods and Capistrano plugins (including Capistrano::Mailgun).

Of course, you can also pass :text and :html options for the exact text/html bodies of the sent emails as they will be passed directly to the Mailgun API.

No validation is done from this function, so errors from Mailgun will percolate up to you.

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 new Pull Request

Acknowledgements

Capistrano::Mailgun is a Capnotify extension. See Capnotify for additional configuration options.

Capistrano::Mailgun is written by Spike Grobstein and is used in production at Ticket Evolution

Capistrano::Mailgun leverages the awesome email sending API of Mailgun.org. You should definitely check it out.

License

Capistrano::Mailgun is ©2012-2013 Spike Grobstein and licensed under the MIT License. See LICENSE file.