A simple double opt-in broadcast email application built on Heroku and Mailgun.
JavaScript Ruby
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Mailcannon: a simple broadcast email app built on Heroku and Mailgun

Mailcannon is a simple broadcast email client built on top of Mailgun. The application makes it easy to collect email addresses via a double opt-in confirmation process. Once confirmed, the application sends an immediate welcome email, then stores the user's email address in a broadcast list within the administrator's Mailgun account.

Broadcast emails (in Markdown format) are checked into the app's git repository, and can be previewed by sending to the administrator's email address. The broadcast is then sent to the list by running a Rake command.

Note: for security, this application should be run using SSL.

Set Global Variables

Edit the /config/globals.rb file to set the following options:

  • URL (the https url of this application, no trailing slash)
  • DESCRIPTION (describe your list name to a user)
  • MAILGUN_DOMAIN (your internal Mailgun subdomain)
  • MAILGUN_LIST (our internal Mailgun mailing list name)
  • ADMIN_NAME (your name)
  • ADMIN_URL (your website / domain)
  • ADMIN_EMAIL (your email)
  • ADMIN_BUSINESS (your business name, for CAN-SPAM purposes)
  • ADMIN_CONTACT (your business address, for CAN-SPAM purposes)
  • SALT (a random string or phrase for a bit of added security)

In addition, you need to set your Mailgun API key by running $ heroku config:add MAILGUN_PRIVATE_KEY=t0psecret in the terminal. Be sure to replace t0psecret with your actual Mailgun key.

Sending Email Broadcasts

The included Rakefile contains two Rake tasks that make it easy to send broadcast emails to your users. For security, broadcast emails are sent via the command line vs. a web-based interface, since Heroku command line logins require both your SSH key file and password.

Step 1: Upload Files

Add your email message to /email/broadcast, and upload the fie to Heroku by running $ git push heroku master after adding and committing the file to your repo. Broadcast messages support Markdown for easy message creation. I recommend using a YEAR-MONTH-DAY-filename.md naming scheme to make your messages easy to find later.

Add file attachments to /email/attachments.

Step 2: Preview Your Email

Use this command to send a preview email to the administrator email set in the /config/globals.rb file.

$ heroku run rake 'email:preview["Subject Line","2013-01-01-message.md"]'

Step 3: Send the Broadcast

Use this command to send a broadcast email to the Mailgun list set in the /config/globals.rb file.

$ heroku run rake 'email:broadcast["Subject Line","2013-01-01-message.md"]'

Scheduling a Specific Delivery Time

If you'd like to specify a delivery time, use this command (all times GMT):

$ heroku run rake 'email:schedule["Subject Line","2013-01-01-message.md","01 Jan 2013 00:00:00"]'