Mailkick

Email unsubscribes for Rails

• 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
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

The following services are supported:

• AWS SES
• Mailchimp
• Mailgun
• Mandrill
• Postmark
• SendGrid

Will gladly accept pull requests for others.

AWS SES

Add the gem

gem 'aws-sdk-sesv2'

And configure your AWS credentials. Requires ses:ListSuppressedDestinations permission.

Mailchimp

Add the gem

gem 'gibbon', '>= 2'

And set ENV["MAILCHIMP_API_KEY"] and ENV["MAILCHIMP_LIST_ID"].

Mailgun

Add the gem

gem 'mailgun-ruby'

And set ENV["MAILGUN_API_KEY"].

Mandrill

Add the gem

gem 'mandrill-api'

And set ENV["MANDRILL_APIKEY"].

Postmark

Add the gem

gem 'postmark'

And set ENV["POSTMARK_API_KEY"].

SendGrid

Add the gem

gem 'sendgrid-ruby'

And set ENV["SENDGRID_API_KEY"]. The API key requires only the Suppressions permission.

Advanced

For more control over services, set them by hand.

Mailkick.services = [
  Mailkick::Service::SendGridV2.new(api_key: "API_KEY"),
  Mailkick::Service::Mailchimp.new(api_key: "API_KEY", list_id: "LIST_ID")
]

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

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

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:

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

To get started with development and testing:

git clone https://github.com/ankane/mailkick.git
cd mailkick
bundle install
bundle exec rake test