Mailkick

🚄 Email subscriptions made easy

• Add one-click unsubscribe links to your emails
• Fetch bounces and spam reports from your email service

Gracefully handles email address changes

📮 Check out Ahoy Email for analytics

Installation

Add this line to your application’s Gemfile:

gem 'mailkick'

And run the generator. This creates a model to store opt-outs.

rails generate mailkick:install
rake db:migrate

How It Works

Add an unsubscribe link to your emails.

Text

Unsubscribe: <%= mailkick_unsubscribe_url %>

HTML

<%= link_to "Unsubscribe", mailkick_unsubscribe_url %>

When a user unsubscribes, he or she is taken to a mobile-friendly page and given the option to resubscribe.

To customize the view, run:

rails generate mailkick:views

which copies the view into app/views/mailkick.

Sending Emails

Before sending marketing emails, make sure the user has not opted out.

Add the following method to models with email addresses.

class User < ActiveRecord::Base
  mailkick_user
end

Get all users who have opted out

User.opted_out

And those who have not - send to these people

User.not_opted_out

Check one user

user.opted_out?

Bounces and Spam Reports

Fetch bounces, spam reports, and unsubscribes from your email service.

Mailkick.fetch_opt_outs

Sendgrid

Add the gem

gem 'sendgrid_toolkit'

Be sure ENV["SENDGRID_USERNAME"] and ENV["SENDGRID_PASSWORD"] are set.

Mandrill

gem 'mandrill-api'

Be sure ENV["MANDRILL_APIKEY"] is set.

Mailchimp

gem 'gibbon'

Be sure ENV["MAILCHIMP_API_KEY"] and ENV["MAILCHIMP_LIST_ID"] are set.

Mailgun [master]

gem 'mailgun-ruby'

Be sure ENV["MAILGUN_API_KEY"] is set.

Other

Will gladly accept pull requests.

Advanced

For more control over services, set them by hand.

Mailkick.services = [
  Mailkick::Service::Sendgrid.new(api_key: "API_KEY"),
  Mailkick::Service::Mandrill.new(api_key: "API_KEY")
]

Multiple Lists [beta]

You may want to split your emails into multiple categories, like sale emails and order reminders.

Set the list in the mailer.

class UserMailer < ActionMailer::Base

  def order_reminder(user)
    header[:mailkick_list] = "order_reminders"
    # ...
  end

end

Pass the list option to methods.

User.opted_out(list: "order_reminders")
User.not_opted_out(list: "order_reminders")
user.opted_out?(list: "order_reminders")

Opt-In Lists

For opt-in lists, you’ll need to manage the subscribers yourself.

Check opt-ins against the opt-outs

User.where(send_me_sales: true).not_opted_out(list: "sales")

Check one user

user.send_me_sales && !user.opted_out?(list: "sales")

Bonus

More great gems for email

• Roadie - inline CSS
• Letter Opener - preview email in development

TODO

• Make it easy to customize controller
• Subscribe to events

Reference

Change how the user is determined

Mailkick.user_method = proc {|email| User.where(email: email).first }

Use a different email field

mailkick_user email_key: :email_address

Unsubscribe

user.opt_out

Resubscribe

user.opt_in

History

View the changelog

Contributing

Everyone is encouraged to help improve this project. Here are a few ways you can help:

• Report bugs
• Fix bugs and submit pull requests
• Write, clarify, or fix documentation
• Suggest or add new features