Heya 👋

Heya is a campaign mailer for Rails. Think of it like ActionMailer, but for
timed email sequences. It can also perform other actions like sending a text
message.

Getting started

Getting started with Heya is easy:

1. Install the gem
2. Create a campaign
3. Run the scheduler

Prerequisites

Heya was built to work with PostgreSQL. Pull requests are welcome to support
more databases.

Installing the Heya gem

1. Add this line to your application’s Gemfile:

   gem "heya", github: "honeybadger-io/heya"
   

2. Then execute:

   bundle install
   rails generate heya:install
   rails db:migrate
   

This will:

1. Copy Heya’s migration files to db/migrate
2. Copy Heya’s default initializer to config/initializers/heya.rb
3. Create the file app/campaigns/application_campaign.rb
4. Run local migrations

# config/initializers/heya.rb
Heya.configure do |config|
config.user_type = "MyUser"
end

Creating your first campaign

1. Create a campaign:

   rails generate heya:campaign Onboarding welcome:0
   

2. Add a user to your campaign:

   OnboardingCampaign.add(user)
   

Add the following to your User model to send them the campaign
when they first sign up:

after_create_commit do
  OnboardingCampaign.add(self)
end

Running the scheduler

To start queuing emails, run the scheduler task periodically:

rails heya:scheduler

Heya uses ActiveJob to send emails in the background. Make sure your
ActiveJob backend is configured to process the heya queue. For example,
here’s how you might start Sidekiq:

bundle exec sidekiq -q default -q heya

You can change Heya’s default queue using the queue option:

# app/campaigns/application_campaign.rb
class ApplicationCampaign < Heya::Campaigns::Base
  default queue: "custom"
end

Bonus: tips for working with email in Rails

# config/environments/development.rb
Rails.application.configure do
  # ..

  # Use MailCatcher to inspect emails
  # http://mailcatcher.me
  # Usage:
  #   gem install mailcatcher
  #   mailcatcher
  #   # => Starting MailCatcher
  #   # => ==> smtp://127.0.0.1:1025
  #   # => ==> http://127.0.0.1:1080
  config.action_mailer.delivery_method = :smtp
  config.action_mailer.smtp_settings = {host: "localhost", port: 1025}
end

$ bundle add maildown
$ rails generate heya:campaign Onboarding welcome
      create  app/campaigns/application_campaign.rb
      create  app/campaigns/onboarding_campaign.rb
      create  app/views/heya/campaign_mailer/onboarding_campaign/welcome.md.erb

# test/mailers/previews/onboarding_campaign_preview.rb
class OnboardingCampaignPreview < ActionMailer::Preview
  def welcome
    OnboardingCampaign.welcome(user)
  end

  private

  def user
    User.where(id: params[:user_id]).first || User.first
  end
end

Configuration

You can use the following options to configure Heya (find this file in
config/initializers/heya.rb):

Heya.configure do |config|
  # The name of the model you want to use with Heya.
  config.user_type = "User"

  # The default options to use when processing campaign steps.
  config.campaigns.default_options = {from: "[email protected]"}

  # Campaign priority. When a user is added to multiple campaigns, they are
  # sent in this order. Campaigns are sent in the order that the users were
  # added if no priority is configured.
  config.campaigns.priority = [
    "FirstCampaign",
    "SecondCampaign",
    "ThirdCampaign"
  ]
end

Campaigns

Creating campaigns

Heya stores campaigns in app/campaigns/, similar to how Rails stores mailers
in app/mailers/. To create a campaign, run the following command inside your
Rails project:

rails generate heya:campaign Onboarding first second third

This will:

1. Create the file app/campaigns/onboarding_campaign.rb
2. Create the directory app/views/heya/campaign_mailer/onboarding_campaign/
3. Create email templates inside of app/views/heya/campaign_mailer/onboarding_campaign/
4. Create an ActionMailer preview at (test|spec)/mailers/previews/onboarding_campaign_preview.rb

Here’s the campaign that the above command generates:

# app/campaigns/application_campaign.rb
class ApplicationCampaign < Heya::Campaigns::Base
  default from: "[email protected]"
end

# app/campaigns/onboarding_campaign.rb
class OnboardingCampaign < ApplicationCampaign
  step :first,
    subject: "First subject"

  step :second,
    subject: "Second subject"

  step :third,
    subject: "Third subject"
end

Steps

The step method defines a new step in the sequence. When you add a user to the
campaign, Heya completes each step in the order that it appears.

The default time to wait between steps is two days, calculated from the time
the user completed the previous step (or the time the user entered the campaign,
in the case of the first step).

Each step has several options available (see the section Creating
messages).

Creating messages

Messages are defined inside Heya campaigns using the step method. When you add
a user to a campaign, Heya completes each step in the order that it appears.

The most important part of each step is its name, which must be unique to the
campaign. The step’s name is how Heya tracks which user has received which
message, so it’s essential that you don’t change it after the campaign is active
(if you do, Heya will assume it’s a new message).

Here’s an example of defining a message inside a campaign:

class OnboardingCampaign < ApplicationCampaign
  step :welcome, wait: 1.day,
    subject: "Welcome to my app!"
end

In the above example, Heya will send a message named :welcome one day after a
user enters the campaign, with the subject “Welcome to my app!”

The wait option tells Heya how long to wait before sending each message (the
default is two days). There are a few scheduling options that you can customize
for each step:

Heya uses the following additional options to build the message itself:

You can change the default options using the default method at the top of the
campaign. Heya applies default options to each step which doesn’t supply its
own:

class OnboardingCampaign < ApplicationCampaign
  default wait: 1.day,
    queue: "onboarding",
    from: "[email protected]",
    layout: "onboarding"

  # Will still be sent after one day from the
  # email address [email protected]
  step :welcome,
    subject: "Welcome to my app!"
end

Customizing the to field

You can customize the to field by passing a callable object, which Heya will
invoke with the user. For instance:

class OnboardingCampaign < ApplicationCampaign
  step :welcome,
    subject: "Welcome to my app!",
    to: -> (user) { ActionMailer::Base.email_address_with_name(user.email, user.nickname) }
end

It is recommended to rely on ActionMailer::Base.email_address_with_name so
that sanitization is correctly applied.

If the to param is not provided, Heya will default to:

1. user#first_name
2. user#name

If the user object doesn’t respond to these methods, it will fallback to a
simple user.email in the to field.

Quality control option

You may wish to apply quality control to individual steps of a campaign. For
example, when adding a new step to an existing campaign it is a good idea to
inspect real-time results in production. You can do this by using the bcc:
step option, which would look like this:

class OnboardingCampaign < ApplicationCampaign
  default wait: 1.day,
    queue: "onboarding",
    from: "[email protected]"

  # Will still be sent after one day from the
  # email address [email protected]
  step :welcome,
    subject: "Welcome to my app!"

  step :added_two_months_later,
    subject: "We now have something new to say!",
    bcc: '[email protected]'
end

Customizing email subjects for each user

The subject can be customized for each user by using a lambda instead of a String:

# app/campaigns/onboarding_campaign.rb
class OnboardingCampaign < ApplicationCampaign
  step :welcome,
    subject: ->(user) { "Heya #{user.first_name}!" }
end

Translations for email subjects (I18n)

If you don’t pass a subject to the step method, Heya will try to find it in
your translations. The performed lookup will use the pattern
<campaign_scope>.<step_name>.subject to construct the key.

# app/campaigns/onboarding_campaign.rb
class OnboardingCampaign < ApplicationCampaign
  step :welcome
end

# config/locales/en.yml
en:
  onboarding_campaign:
    welcome:
      subject: "Heya!"

To define parameters for interpolation, define a #heya_attributes method on
your user model:

# app/models/user.rb
class User < ApplicationRecord
  def heya_attributes
    {
      first_name: name.split(" ").first
    }
  end
end

# config/locales/en.yml
en:
  onboarding_campaign:
    welcome:
      subject: "Heya %{first_name}!"

Custom Actions

You can override the default step behavior to perform custom actions by passing
a block to the step method:

class OnboardingCampaign < ApplicationCampaign
  step :first_email,
    subject: "You're about to receive a txt"

  step :sms do |user|
    SMS.new(to: user.cell, body: "Hi, #{user.first_name}!").deliver
  end

  step :second_email,
    subject: "Did you get it?"
end

Step blocks receive two optional arguments: user and step, and are processed
in a background job alongside other actions.

Adding users to campaigns

Heya leaves when to add users to campaigns completely up to you; here’s how to
add a user to a campaign from anywhere in your app:

OnboardingCampaign.add(user)

To remove a user from a campaign:

OnboardingCampaign.remove(user)

Adding users to campaigns from Rails opens up some interesting automation
possibilities–for instance, you can start or stop campaigns from ActiveRecord
callbacks, or in response to other events that you’re already tracking in your
application. See here for a list of ideas.

Because Heya stacks campaigns by default (meaning it will never send more than
one at a time), you can also queue up several campaigns for a user, and they’ll
receive them in order:

WelcomeCampaign.add(user)
OnboardingCampaign.add(user)
EvergreenCampaign.add(user)

Note: you can customize the priority of campaigns via Heya’s configuration.

If you want to send a user two campaigns simultaneously, you can do so with the
concurrent option:

FlashSaleCampaign.add(user, concurrent: true)

When you remove a user from a campaign and add them back later, they’ll continue
where they left off. If you want them to start over from the beginning, use the
restart option:

TrialConversionCampaign.add(user, restart: true)

Automation ideas

Using ActiveSupport::Notifications to respond to lifecycle events (which could
be sent from your Stripe controller, for instance):

ActiveSupport::Notifications.subscribe("user.trial_will_end") do |*args|
    event = ActiveSupport::Notifications::Event.new(*args)
    if event.payload[:user_id]
      user = User.find(event.payload[:user_id])
      TrialConversionCampaign.add(user, restart: true)
    end
end

Scheduling campaigns in ActiveRecord callbacks:

class User < ApplicationRecord
  after_create_commit do
    WelcomeCampaign.add(self)
    OnboardingCampaign.add(self)
    EvergreenCampaign.add(user)
  end
end

Customizing who gets what

Heya can send individual messages to certain users using the segment option.
The following campaign will send the message to inactive users–active users
will be skipped:

class ActivationCampaign < ApplicationCampaign
  step :activate, segment: ->(user) { user.inactive? }
end

When you’re checking the value of a single method on the user, the segment can
be simplified to the symbol version:

class ActivationCampaign < ApplicationCampaign
  step :activate, segment: :inactive?
end

Segmenting specific campaigns

You can also narrow entire campaigns to certain users using the segment
method. For instance, if you have a campaign with a specific goal such as
performing an action in your app, then you can send the campaign only to the
users who haven’t performed the action:

class UpgradeCampaign < ApplicationCampaign
  segment { |u| !u.upgraded? }

  step :one
  step :two
  step :three
end

If they upgrade half way through the campaign, Heya will stop sending messages
and remove them from the campaign.

Likewise, you can require that users meet conditions to continue receiving a
campaign. Here’s a campaign which sends messages only to trial users–non-trial
users will be removed from the campaign:

class TrialCampaign < ApplicationCampaign
  segment :trial?

  step :one
  step :two
  step :three
end

Segmenting all campaigns

Heya campaigns inherit options from parent campaigns. For example, to make sure
unsubscribed users never receive an email from Heya, create a segment in the
ApplicationCampaign, and then have all other campaigns inherit from it:

class ApplicationCampaign < Heya::Campaigns::Base
  segment :subscribed?
end

Handling exceptions

Heya campaigns are rescuable.
Use the rescue_from method to handle exceptions in campaigns:

class OnboardingCampaign < ApplicationCampaign
  rescue_from Postmark::InactiveRecipientError, with: :log_error

  private

  def log_error(error)
    Rails.logger.error("Got Heya error: #{error}")
  end
end

See the
Rails documentation
for additional details.

Extending campaign mailers

The campaign generator does not create a Mailer class for campaigns. In order to
enhance a campaign with a macro from another gem (such as for adding analytics),
you can do so by extending the Heya::ApplicationMailer class.

1. Create a new file at app/mailers/heya/application_mailer.rb
2. Add the following to it:

module Heya
  class ApplicationMailer < ActionMailer::Base
    macro_to_add_to_all_campaign_mailers
  end
end

For example, here’s how to extended Heya::ApplicationMailer to include Ahoy
Email’s
has_history
and
track_clicks
macros:

# app/mailers/heya/application_mailer.rb

module Heya
  class ApplicationMailer < ActionMailer::Base
    has_history

    track_clicks campaign: -> {
      params[:step].campaign.name
    }
  end
end

This does two things:

1. has_history enables history tracking for all Heya emails
2. The track_clicks block appends the name of the campaign to all
   (non-unsubscribe) links in an email so that each campaign can keep its data
   separate from the other campaigns.

The result of this is that you can run a command like this in the console:

AhoyEmail.stats "OnboardingCampaign"

…and receive a result:

=> {:sends=>1, :clicks=>2, :unique_clicks=>1, :ctr=>100.0}

Campaigns FAQ

What happens when:

Less frequently asked questions:

Upgrading Heya

Heya adheres to Semantic Versioning, and
should be considered unstable until version 1.0.0. Always check
CHANGELOG.md prior to upgrading (breaking changes will always
be called out there). Upgrade instructions for breaking changes are in
UPGRADING.md.

Roadmap

See here for things we’re
considering adding to Heya.

Contributing

1. Fork it.
2. Create a topic branch git checkout -b my_branch
3. Make your changes and add an entry to CHANGELOG.md.
4. Commit your changes git commit -am "Boom"
5. Push to your branch git push origin my_branch
6. Send a pull request

Releasing

1. gem install gem-release
2. gem bump -v [version] -t -r
3. Update unreleased heading in CHANGELOG.md (TODO: automate
   this in gem-release command)
4. git push origin main --tags

License

Heya is licensed under the LGPL.