MailCannon

This Gem relies heavily on Sidekiq, you are encouraged to use it anywhere with Ruby (a http interface is on the Roadmap ). You REALLY should buy Sidekiq's Pro license for serious deployments, check it out.

This Gem provides a worker ready for deploy cooked with MongoDB + Mongoid + Sidekiq + Rubinius (feel free to use on MRI and jRuby as well).

For production deployment, you should take a look at both MailCannon Outpost and MailCannon Monitor projects.

You can check the changelog here.

Install

You can:

  $ gem install mailcannon

Or just add it to your Gemfile

  gem 'mailcannon'

Use

Create a MailCannon::Envelope:

envelope = MailCannon::Envelope.create(
  from: 'test@mailcannon.com',
  to: [{email: 'lucasmartins@railsnapraia.com', name: 'Lucas Martins'}],
  subject: 'Test',
  mail: MailCannon::Mail.new(text: 'you will see this when no HTML reader is available', html: 'this should be an HTML'))

envelope.post!

Campaign abstraction

Create a MailCannon::EnvelopeBag and add Envelopes to it:

envelope_bag = MailCannon::EnvelopeBag.new(integration_code: 'my-cool-campaign')
envelope = MailCannon::Envelope.create(
  from: 'test@mailcannon.com',
  to: [{email: 'lucasmartins@railsnapraia.com', name: 'Lucas Martins'}],
  subject: 'Test',
  mail: MailCannon::Mail.new(text: 'you will see this when no HTML reader is available', html: 'this should be an HTML'))
envelope_bag.push envelope
# envelope_bag.push ...
envelope_bag.post!

Multiple Sendgrid Accounts

You can pass an auth Hash to the Envelope and/or EnvelopeBag, the Envelope auth will always override the Bag's auth.

envelope_bag = MailCannon::EnvelopeBag.new(auth: {username: 'shared-account',password: '123'})
envelope = MailCannon::Envelope.create(
  auth: {username: 'hot-account',password: '456'}
  from: 'test@mailcannon.com',
  to: [{email: 'lucasmartins@railsnapraia.com', name: 'Lucas Martins'}],
  subject: 'Test',
  mail: MailCannon::Mail.new(text: 'you will see this when no HTML reader is available', html: 'this should be an HTML'))
envelope_bag.push envelope
envelope_bag.post! # this will be sent using the 'hot-account'.

Configuration file

If you are on Rails, run the following command to generate a config file:

$ rails g mailcannon:config

Otherwise, just copy the template file:

$ cd my-project
$ cp `bundle show mailcannon`/templates/config/mailcannon.yml config/

Edit the file to meet your environemnt needs.

Check the specs to see the testing example, it will surely make it clearer.

Statistics & MapReduce

MailCannon provides statistics calculation/reduce for the events related to an Envelope, like open,click,spam, etc. Assuming you have your Outpost running properly (running reduce jobs), you can access the data through the envelope.stats method to get the following hash:

{
  "posted"=>{"count"=>0.0, "targets"=>[]},
  "processed"=>{"count"=>0.0, "targets"=>[]},
  "delivered"=>{"count"=>1.0, "targets"=>["1"]},
  "open"=>{"count"=>1.0, "targets"=>["2"]},
  "click"=>{"count"=>0.0, "targets"=>[]},
  "deferred"=>{"count"=>0.0, "targets"=>[]},
  "spam_report"=>{"count"=>0.0, "targets"=>[]},
  "spam"=>{"count"=>0.0, "targets"=>[]},
  "unsubscribe"=>{"count"=>0.0, "targets"=>[]},
  "drop"=>{"count"=>0.0, "targets"=>[]},
  "bounce"=>{"count"=>1.0, "targets"=>["3"]}
}

You can trigger the reduce operation directly with envelope.reduce_statistics.

Targets are your glue_id to link this data inside your own application, we use it as the "Contact#id" so we can show witch Contact has received, read, or clicked the email.

Repeating events on the same target will increase the array: "click"=>{"count"=>3.0, "targets"=>["3","3","3"]}

Docs

You should check the factories to learn what you need to build your objects, and the tests to learn how to use them. But hey, we have docs right here.

Roadmap

• Load testing;
• Webhook service to receive Sendgrid events;
• Memory optimization (focused on MailCannon Outpost);
• HTTP (webservice) interface - so you don't need to be coding Ruby to use it!;

Contribute

Just fork MailCannon, add your feature+spec, and make a pull request. DO NOT mess up with the version file though.

Support

This is an opensource project so don't expect premium support, but don't be shy, post any troubles you're having in the Issues page and we'll do what we can to help.

License

Please see LICENSE for licensing details.