MailyHerald - email processing solution for Ruby on Rails applications

Manage your application mailings like a PRO.

Ruby on Rails gem that will seamlessly integrate with your app, manage and log all your mailings and provide you with great WebUI.

Get it!

Just add it to your Gemfile:

gem "maily_herald"

gem "maily_herald-webui" # optionally

You can also fetch it from our GitHub repository.

Usage

Refer to the README.md on GitHub or API Docs. You can also have a look at the test application which demonstrates some basic usage of MailyHerald.

Use cases

Maily is great both for developers (API) and end-users (WebUI). The API provides access to all Maily features while the WebUI has somewhat limitied capabilities, but is great for non-technical users or for those who simply want to see their mailing data visualized.

For the purpose of this Showcase, we are now going to demonstrate some use cases where Maily comes in handy. Examples below are primarily aimed at developers but if you are a non-technical person, you can read the descriptions too to get an overview on how Maily works.

Ad-Hoc Mailing using Action Mailer

Ad-Hoc Mailing is very similar to the standard Rails method of sending emails, while at the same time utilizing features which Maily provides like background delivery and message logging.

Let's assume you have your User model up and running. You also have your UserMailer class and views that send nice emails to users. Now it's time to plug in MailyHerald.

# app/models/user.rb

class User < ActiveRecord::Base
end

# app/mailers/user_mailer.rb

class UserMailer < MailyHerald::Mailer
  def hello user
    mail subject: "Hi #{user.name}!"
  end
end

# app/views/user_mailer/hello.text.erb

How are you doing?

# config/initializers/maily_herald.rb

MailyHerald.setup do |config|
  config.context :all_users do |context|
    context.scope {User.all}
    context.destination = :email
  end

  config.list :all_users do |list|
    list.context_name = :all_users
  end

  config.ad_hoc_mailing :hello do |mailing|
    mailing.list = :all_users
    mailing.mailer_name = "UserMailer"
    mailing.enable
  end
end

user = User.first

MailyHerald.subscribe user, :all_users

# For Action Mailer syntax compatibility and synchronous delivery use this:
UserMailer.hello(user).deliver

# For background delivery and better control, use this:
MailyHerald.ad_hoc_mailing(:hello).schedule_delivery_to user, Time.now

In the first case, Maily behaves in the same way as Action Mailer: delivery schedule is created implicitly and email is delivered instantly in current thread. In the second case, Maily queues email for background delivery - a mailing schedule is created and finally processed by Paperboy daemon when its time comes. If you open the WebUI, you'll see the delivery log with date, recipient name, address and full message body.

As you can see, you can send your emails just like you did before using UserMailer.hello(user).deliver syntax. Maily handles that behind the scenes. All you need to do to make it work is extend your mailer class with MailyHerald::Mailer and subscribe the user to a mailing list before the delivery.

Ad-Hoc Mailing using Liquid templates

You can also use Maily without dedicated Action Mailers by defining a mailing template on-the-fly using Liquid syntax. Here's how to do it.

Code samples:
user.rb
maily_herald.rb
irb

# app/models/user.rb

class User < ActiveRecord::Base
end

# config/initializers/maily_herald.rb

MailyHerald.setup do |config|
  config.context :all_users do |context|
    context.scope {User.all}
    context.destination = :email
    context.attributes do |user| 
      attribute_group(:user) do
        attribute(:name) {user.name}
        attribute(:email) {user.email}
        attribute(:created_at) {user.created_at}
      end
    end
  end

  config.list :all_users do |list|
    list.context_name = :all_users
  end

  config.ad_hoc_mailing :hello do |mailing|
    mailing.list = :all_users
    mailing.subject = "Hello {{user.name}}!"
    mailing.template = "What's up?"
    mailing.enable
  end
end

user = User.first
MailyHerald.subscribe user, :all_users

UserMailer.hello(user).deliver

Note that in order to access user attributes from Liquid templates, you need to define some context attributes.

This way of defining mailings is really convenient for WebUI users who create and edit mailings using just text fields and predefined context attributes.

Welcome email with One-Time Mailing

One-Time Mailing is meant to be sent once to given recipient. Unlike AdHocMailing, its delivery is automatic and scheduled based on the start_at attribute value. It can be either a Ruby code block or a string using Liquid syntax.

Here's how you can use One-Time Mailing to manage your welcome emails.

# app/models/user.rb

class User < ActiveRecord::Base
  after_create do |user|
    MailyHerald.subscribe(user, :all_users)
  end
end

# config/initializers/maily_herald.rb

MailyHerald.setup do |config|
  config.context :all_users do |context|
    context.scope {User.all}
    context.destination = :email
    context.attributes do |user| 
      attribute_group(:user) do
        attribute(:name) {user.name}
        attribute(:email) {user.email}
        attribute(:created_at) {user.created_at}
      end
    end
  end

  config.list :all_users do |list|
    list.context_name = :all_users
  end

  config.one_time_mailing :welcome do |mailing|
    mailing.title = "Welcome"
    mailing.list = :all_users
    mailing.subject = "Hello {{user.name}}!"
    mailing.template = "Nice to have you on board. Cheers!"

    mailing.start_at = Proc.new{|user| user.created_at + 5.minutes}
    # Alternatively you can use Liquid:
    # mailing.start_at = "user.created_at | plus: 5, 'minutes'"

    mailing.enable
  end
end

# app/controllers/account_controller.rb

class AccountController < ApplicationController

  # You'll probably need much more code in this controller to handle signups.
  # This is just a minimal example that gives you an overview how Maily works.

  def create
    user = User.create(user_params)

    # Because of `after_create` callback, user is now subscribed to :all_users
    # list and welcome mailing has been scheduled.
  end
end

With this setup, a welcome email will be sent to every user 5 minutes after signup.

Weekly newsletters with Periodical Mailing

Periodical Mailings are meant for delivery of emails at scheduled times for specified recipients.

Let's see how easy it is to set up.

Code samples:
user.rb
maily_herald.rb

# app/models/user.rb

class User < ActiveRecord::Base
  after_create do |user|
    MailyHerald.subscribe(user, :all_users)
  end
end

# config/initializers/maily_herald.rb

MailyHerald.setup do |config|
  config.context :all_users do |context|
    context.scope {User.all}
    context.destination = :email
    context.attributes do |user| 
      attribute_group(:user) do
        attribute(:name) {user.name}
        attribute(:email) {user.email}
        attribute(:created_at) {user.created_at}
      end
    end
  end

  config.list :all_users do |list|
    list.context_name = :all_users
  end

  config.periodical_mailing :weekly_newsletter do |mailing|
    mailing.title = "Weekly newsletter"
    mailing.list = :newsletters
    mailing.start_at = "2015-10-05 08:00:00 +0000"
    mailing.period = 1.week
    mailing.subject = "Weekly update"
    mailing.template = "Lots of stuff have happened during this week."
    mailing.enable
  end
end

This mailing uses "general scheduling" mode (see README.md). This will send emails to subscribed users every week on Monday at 8am GMT starting from the first week after the user's signup.

The above example uses a generic mailer with Liquid templates, but in real life periodicals probably make more sense with customized ActionMailer emails providing more complex, individual content for each recipient (like user statistics, latest activity etc.).

User onboarding with Sequence Mailing

Sequences serve the purpose of sending a bunch of different mailings, one after another, to each recipient with various delays. There are many possible applications of Sequence Mailings. One of them is sending out onboarding emails to new users.

Code samples:
user.rb
maily_herald.rb

# app/models/user.rb

class User < ActiveRecord::Base
  after_create do |user|
    MailyHerald.subscribe(user, :all_users)
  end
end

# config/initializers/maily_herald.rb

MailyHerald.setup do |config|
  config.context :all_users do |context|
    context.scope {User.all}
    context.destination = :email
    context.attributes do |user| 
      attribute_group(:user) do
        attribute(:name) {user.name}
        attribute(:email) {user.email}
        attribute(:created_at) {user.created_at}
      end
    end
  end

  config.list :all_users do |list|
    list.context_name = :all_users
  end

  config.sequence :onboarding do |seq|
    seq.title = "Onboarding"
    seq.list = :all_communication
    seq.start_at = "user.created_at"
    seq.enable
    seq.mailing :onboarding_first_message do |mailing|
      mailing.title = "First message"
      mailing.absolute_delay = 1.day
      mailing.subject = "First message"
      mailing.template = "How are you?"
      mailing.enable
    end
    seq.mailing :onboarding_second_message do |mailing|
      mailing.title = "Second message"
      mailing.absolute_delay = 7.days
      mailing.subject = "Second message"
      mailing.template = "Is everything ok?"
      mailing.enable
    end
    seq.mailing :onboarding_final_message do |mailing|
      mailing.title = "Final message"
      mailing.absolute_delay = 30.days
      mailing.subject = "Third message"
      mailing.template = "Are you sure?"
      mailing.enable
    end
  end
end

With the above, users will get three onboarding messages. The first is sent 1 day after signup, the second 6 days after that, and the last one 23 days after the second message.

That's all folks!

Stay tuned by signing up to our development status newsletters. New features and improvements are coming soon: message analytics, link tracking, email service integration and better templating.

We'd love to see you contributing to MailyHerald development. Start by forking our repository.

In case you have any questions, comments, or found a bug - file an issue on GitHub or contact us directly.

MailyHerald is created by Sology. We are a Ruby on Rails software house based in Kraków, Poland.