Email subscriptions made easy
Branch: master
Clone or download
Latest commit 69f1c1b Feb 9, 2019

README.md

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

Build Status

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
rails 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 < ApplicationRecord
  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', '>= 2'

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

Mailgun

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

You may want to split your emails into multiple categories, like sale emails and order reminders. Set the list in the url:

mailkick_unsubscribe_url(list: "order_reminders")

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

Reference

Change how the user is determined

Mailkick.user_method = ->(email) { User.find_by(email: email) }

Use a different email field

mailkick_user email_key: :email_address

Unsubscribe

user.opt_out

Resubscribe

user.opt_in

Access the opt-out model directly

Mailkick::OptOut.all

History

View the changelog

Contributing

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