cerebris / mailhopper

An ActiveRecord based queue for email storage and delivery in Rails apps

Mailhopper

Mailhopper provides a simple ActiveRecord-based queue for asynchronous delivery of email in Rails apps.

Why use Mailhopper to queue your email?

• Mailhopper captures the full content and headers of emails at their time of creation. It can handle multiple MIME types and attachments.
• If email can't be delivered from your queue (e.g. your smtp server is down), you can retry delivery until successful.
• Emails can be accessed at any time, even after they've been sent.

The complete rationale is explained in this blog post: http://www.cerebris.com/blog/2011/09/07/tame-rails-email-dragons-with-mailhopper/

Mailhopper is intended to be used along with a delivery agent such as DelayedMailhopper, which uses DelayedJob to deliver email from the Mailhopper queue. Without a delivery agent, emails will accumulate in the Mailhopper queue but won't be delivered.

DelayedMailhopper can be found here: https://github.com/cerebris/delayed_mailhopper

Requirements

Rails 3.1+

Installation

Add to your project's Gemfile:

gem 'mailhopper'

Install with bundler:

bundle install

Generate default initializer and migration files:

rails generate mailhopper

Before migrating your database, please take a moment to review the CreateEmails migration that has been generated. In particular, please review the limit to the content field, which has been set to a safe but very large size (100MB characters). You may wish to change this based upon your needs and particular database.

When you're ready, migrate your database:

rake db:migrate

Don't forget to also install a delivery agent, such as DelayedMailhopper, so that emails will be delivered from your queue !!!

Configuration

If you want all of your application's email to be queued with Mailhopper, configure mailers either in application.rb or your application's environment-specific configuration files:

MyApp::Application.configure do
  config.action_mailer.delivery_method = :mailhopper
end

Alternatively, or additionally, configure individual mailers to use Mailhopper:

class MyMailer < ActionMailer::Base
  ActionMailer::Base.delivery_method = :mailhopper
end

Options

The following options can be configured in your initializer (config/initializers/mailhopper):

Mailhopper::Base.setup do |config|
  # The base email class used by Mailhopper
  config.email_class = Mailhopper::Email

  # The base mailer class used by Mailhopper
  config.mailer_class = Mailhopper::Mailer

  # The method used by the delivery agent to deliver emails from your queue
  config.default_delivery_method = :smtp
end

It's preferable to leave these options out of your initializer if the defaults, shown above, are acceptable. Delivery agents may override some defaults (e.g. DelayedMailhopper sets email_class = DelayedMailhopper::Email).

Copyright

Copyright (c) 2011 Cerebris Corporation. This is free software released under the MIT License (see MIT-LICENSE for details).

mailhopper's Issues

Rails 4 incompatibility

At the moment when integrating mailhopper into Ruby 2.0 / Rails 4.0.2 application the following error is raised:

roodymac:curate roody$ bundle exec rails generate mailhopper
/Users/roody/.rvm/gems/ruby-2.0.0-p247@curate/gems/activemodel-4.0.2/lib/active_model/deprecated_mass_assignment_security.rb:14:in `attr_accessible': `attr_accessible` is extracted out of Rails into a gem. Please use new recommended protection model for params(strong_parameters) or add `protected_attributes` to your Gemfile to use old one. (RuntimeError)
    from /Users/roody/.rvm/gems/ruby-2.0.0-p247@curate/gems/mailhopper-0.2.0/app/models/mailhopper/email.rb:3:in `<class:Email>'
    from /Users/roody/.rvm/gems/ruby-2.0.0-p247@curate/gems/mailhopper-0.2.0/app/models/mailhopper/email.rb:2:in `<module:Mailhopper>'
    from /Users/roody/.rvm/gems/ruby-2.0.0-p247@curate/gems/mailhopper-0.2.0/app/models/mailhopper/email.rb:1:in `<top (required)>'
    from /Users/roody/.rvm/gems/ruby-2.0.0-p247@curate/gems/activesupport-4.0.2/lib/active_support/dependencies.rb:229:in `require'
    from /Users/roody/.rvm/gems/ruby-2.0.0-p247@curate/gems/activesupport-4.0.2/lib/active_support/dependencies.rb:229:in `block in require'
    from /Users/roody/.rvm/gems/ruby-2.0.0-p247@curate/gems/activesupport-4.0.2/lib/active_support/dependencies.rb:214:in `load_dependency'
    from /Users/roody/.rvm/gems/ruby-2.0.0-p247@curate/gems/activesupport-4.0.2/lib/active_support/dependencies.rb:229:in `require'
    from /Users/roody/.rvm/gems/ruby-2.0.0-p247@curate/gems/mailhopper-0.2.0/lib/mailhopper/base.rb:1:in `<top (required)>'
    from /Users/roody/.rvm/gems/ruby-2.0.0-p247@curate/gems/activesupport-4.0.2/lib/active_support/dependencies.rb:229:in `require'
    from /Users/roody/.rvm/gems/ruby-2.0.0-p247@curate/gems/activesupport-4.0.2/lib/active_support/dependencies.rb:229:in `block in require'
    from /Users/roody/.rvm/gems/ruby-2.0.0-p247@curate/gems/activesupport-4.0.2/lib/active_support/dependencies.rb:214:in `load_dependency'
    from /Users/roody/.rvm/gems/ruby-2.0.0-p247@curate/gems/activesupport-4.0.2/lib/active_support/dependencies.rb:229:in `require'
    from /Users/roody/.rvm/gems/ruby-2.0.0-p247@curate/gems/mailhopper-0.2.0/lib/mailhopper.rb:3:in `<top (required)>'
    from /Users/roody/.rvm/gems/ruby-2.0.0-p247@global/gems/bundler-1.3.5/lib/bundler/runtime.rb:72:in `require'
    from /Users/roody/.rvm/gems/ruby-2.0.0-p247@global/gems/bundler-1.3.5/lib/bundler/runtime.rb:72:in `block (2 levels) in require'
    from /Users/roody/.rvm/gems/ruby-2.0.0-p247@global/gems/bundler-1.3.5/lib/bundler/runtime.rb:70:in `each'
    from /Users/roody/.rvm/gems/ruby-2.0.0-p247@global/gems/bundler-1.3.5/lib/bundler/runtime.rb:70:in `block in require'
    from /Users/roody/.rvm/gems/ruby-2.0.0-p247@global/gems/bundler-1.3.5/lib/bundler/runtime.rb:59:in `each'
    from /Users/roody/.rvm/gems/ruby-2.0.0-p247@global/gems/bundler-1.3.5/lib/bundler/runtime.rb:59:in `require'
    from /Users/roody/.rvm/gems/ruby-2.0.0-p247@global/gems/bundler-1.3.5/lib/bundler.rb:132:in `require'
    from /Users/roody/dev/contract/curate/config/application.rb:7:in `<top (required)>'
    from /Users/roody/.rvm/gems/ruby-2.0.0-p247@curate/gems/railties-4.0.2/lib/rails/commands.rb:43:in `require'
    from /Users/roody/.rvm/gems/ruby-2.0.0-p247@curate/gems/railties-4.0.2/lib/rails/commands.rb:43:in `<top (required)>'
    from bin/rails:4:in `require'
    from bin/rails:4:in `<main>'

Thanks.

This isn't so much an issue as a suggestion

Since Mailhopper already nicely handles storing emails in the database and sending them via DJ/Resque, it would be great if there was a clean way to integrate with something like this:

https://github.com/aceofspades/sendgrid_postback

That gem tracks delivery information (bounces, spam reports, invalid emails, etc) via sendgrid postbacks but it's just using a simple MailObserver to actually save the records and the UUID needed to map the postbacks to the send message. If there was a clean way to map that data into the existing Mailhopper records...well that would be slick.

Email body too long - Mysql text column handles only 64kb

We had some complaints that emails were cut off from the middle. After a while of debugging we realized that content column is saved as text. Mysql text takes only 64kb. (http://dev.mysql.com/doc/refman/5.0/en/string-type-overview.html)

64kb can be easily reached with a longer html message. And its definitely is reached if you have any attachments.

I guess Postgresql has no limit?

Solutions

Force longtext column in mysql. Change following line to migration
https://github.com/cerebris/mailhopper/blob/master/lib/generators/mailhopper/templates/migrations/create_emails.rb#L19

t.text   :content, :limit => 100.megabytes  # limit is number of characters, not actually bytes

Rails sql handler will use the right columns depending on the sql server. So it should work with Postgresql etc. 100.megabytes is just a random good big number as a limit. We are using utf8 chars in db so 100 megabytes is actually multiplied by three.

Also readme.md could have some info:

Generate default initializer and migration files: `rails generate mailhopper`.
Default max-size for content is quite large. Depending on your needs
and sql server you can modify the migration.

Btw, thanks for the gem, has helped a lot :)

Option to send email without saving to DB.

Is there an option to send single email without saving to DB as normal? We have mailer method that sends mails with attachments and it fails. We having MySQL (closed MySQL connection) error when sending this email.

Is it possible to inject session data for record keeping?

For example, when users are logged in I'd like to add a column to the emails table that stored the user_id of the logged in user who sent the message. Is there an easy way to do something like this with MailHopper without having to track down every outgoing email on my system?

Question: mails per second

This is a question rather than an issue.

Amazon SES imposes a limit on the number of emails that can be sent per second. Can we impose the restriction using mail hopper queueing?

Addresses [email protected] fails, mail returns string, not array of recipients

Creating a email with a bit weirder format so that mail cannot parse it well results in error in delivering.

Try creating email, then setting

@email = SomeEmail()
@email.to = "[email protected]"
@email.to # returns ["[email protected]"]
@email.to = "[email protected]"
@email.to # returns [email protected], string, not an array
@email.deliver # delivering with mailhopper fails

Results in error error

undefined method `join' for "[email protected]":String

mailhopper (0.0.9) lib/mailhopper/queue.rb:21:in `address_to_s'
mailhopper (0.0.9) lib/mailhopper/queue.rbin `deliver!'
...

Easiest fix would be probably to fix address_to_s(field) method:
https://github.com/cerebris/mailhopper/blob/master/lib/mailhopper/queue.rb#L21

to begin with return field if field.is_a?(String)