https://github.com/ankane/mailkick
Email subscriptions for Rails
https://github.com/ankane/mailkick
Last synced: 3 months ago
JSON representation
Email subscriptions for Rails
- Host: GitHub
- URL: https://github.com/ankane/mailkick
- Owner: ankane
- License: mit
- Created: 2014-05-04T08:40:30.000Z (almost 12 years ago)
- Default Branch: master
- Last Pushed: 2025-10-23T17:20:33.000Z (4 months ago)
- Last Synced: 2025-10-27T10:55:34.335Z (4 months ago)
- Language: Ruby
- Homepage:
- Size: 202 KB
- Stars: 964
- Watchers: 14
- Forks: 78
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
Awesome Lists containing this project
- awesome - ankane/mailkick - Email subscriptions for Rails (others)
- awesome-rails - mailkick - A tool to handle mail unsubscriptions. [:red_circle:](https://rubygems.org/gems/mailkick) (Gems / Articles)
README
# Mailkick
Email subscriptions for Rails
- Add one-click unsubscribe links and headers to your emails
- Fetch bounces and spam reports from your email service
**Mailkick 2.0 was recently released** - see [how to upgrade](#upgrading)
:postbox: Check out [Ahoy Email](https://github.com/ankane/ahoy_email) for analytics
[](https://github.com/ankane/mailkick/actions)
## Installation
Add this line to your application’s Gemfile:
```ruby
gem "mailkick"
```
And run the generator. This creates a table to store subscriptions.
```sh
bundle install
rails generate mailkick:install
rails db:migrate
```
## Getting Started
Add `has_subscriptions` to your user model:
```ruby
class User < ApplicationRecord
has_subscriptions
end
```
Subscribe to a list
```ruby
user.subscribe("sales")
```
Unsubscribe from a list
```ruby
user.unsubscribe("sales")
```
Check if subscribed
```ruby
user.subscribed?("sales")
```
Get subscribers for a list (use this for sending emails)
```ruby
User.subscribed("sales")
```
## Unsubscribe Links
Add an unsubscribe link to your emails. For HTML emails, use:
```erb
<%= link_to "Unsubscribe", mailkick_unsubscribe_url(@user, "sales") %>
```
For text emails, use:
```erb
Unsubscribe: <%= mailkick_unsubscribe_url(@user, "sales") %>
```
When a user unsubscribes, they are taken to a mobile-friendly page and given the option to resubscribe. To customize the view, run:
```sh
rails generate mailkick:views
```
which copies the view into `app/views/mailkick`.
## Unsubscribe Headers
For one-click unsubscribe headers ([RFC 8058](https://datatracker.ietf.org/doc/html/rfc8058)), create `config/initializers/mailkick.rb` with:
```ruby
Mailkick.headers = true
```
Headers will automatically be added to emails that call `mailkick_unsubscribe_url`.
## Bounces and Spam Reports
Fetch bounces, spam reports, and unsubscribes from your email service. Create `config/initializers/mailkick.rb` with a method to handle opt outs.
```ruby
Mailkick.process_opt_outs_method = lambda do |opt_outs|
emails = opt_outs.map { |v| v[:email] }
subscribers = User.includes(:mailkick_subscriptions).where(email: emails).index_by(&:email)
opt_outs.each do |opt_out|
subscriber = subscribers[opt_out[:email]]
next unless subscriber
subscriber.mailkick_subscriptions.each do |subscription|
subscription.destroy if subscription.created_at < opt_out[:time]
end
end
end
```
And run:
```ruby
Mailkick.fetch_opt_outs
```
The following services are supported:
- [AWS SES](#aws-ses)
- [Mailchimp](#mailchimp)
- [Mailgun](#mailgun)
- [Mandrill](#mandrill)
- [Postmark](#postmark)
- [SendGrid](#sendgrid)
#### AWS SES
Add the gem
```ruby
gem "aws-sdk-sesv2"
```
And [configure your AWS credentials](https://github.com/aws/aws-sdk-ruby#configuration). Requires `ses:ListSuppressedDestinations` permission.
If you started using Amazon SES [before November 25, 2019](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/sending-email-suppression-list.html#sending-email-suppression-list-considerations), you have to manually [enable account-level suppression list feature](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_PutAccountSuppressionAttributes.html).
#### Mailchimp
Add the gem
```ruby
gem "gibbon", ">= 2"
```
And set `ENV["MAILCHIMP_API_KEY"]` and `ENV["MAILCHIMP_LIST_ID"]`.
#### Mailgun
Add the gem
```ruby
gem "mailgun-ruby"
```
And set `ENV["MAILGUN_API_KEY"]`.
#### Mandrill
Add the gem
```ruby
gem "mandrill-api"
```
And set `ENV["MANDRILL_API_KEY"]`.
#### Postmark
Add the gem
```ruby
gem "postmark"
```
And set `ENV["POSTMARK_API_KEY"]`.
#### SendGrid
Add the gem
```ruby
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.
```ruby
Mailkick.services = [
Mailkick::Service::SendGrid.new(api_key: "API_KEY"),
Mailkick::Service::Mailchimp.new(api_key: "API_KEY", list_id: "LIST_ID")
]
```
## Reference
Access the subscription model directly
```ruby
Mailkick::Subscription.all
```
Prefix method names with `mailkick_`
```ruby
class User < ApplicationRecord
has_subscriptions prefix: true
end
```
## Upgrading
### 2.0
Unsubscribe links created before version 1.1.1 (released January 2023) will no longer work by default. Determine if this is acceptable for your application (for instance, in the US, links must work [for 30 days](https://www.ftc.gov/business-guidance/resources/can-spam-act-compliance-guide-business) after the message is sent). To restore support, [determine the previous secret token](https://github.com/ankane/mailkick/blob/v1.4.0/lib/mailkick/engine.rb#L13-L22) and create an initializer with:
```ruby
Mailkick.message_verifier.rotate(previous_secret_token, serializer: Marshal)
```
If fetching bounces, spam reports, and unsubscribes from Postmark, the suppressions API is now used and the default stream has been changed to `broadcast`. To use `outbound`, create an initializer with:
```ruby
Mailkick.services = [Mailkick::Service::Postmark.new(api_key: api_key, stream_id: "outbound")]
```
## History
View the [changelog](https://github.com/ankane/mailkick/blob/master/CHANGELOG.md)
## Contributing
Everyone is encouraged to help improve this project. Here are a few ways you can help:
- [Report bugs](https://github.com/ankane/mailkick/issues)
- Fix bugs and [submit pull requests](https://github.com/ankane/mailkick/pulls)
- Write, clarify, or fix documentation
- Suggest or add new features
To get started with development and testing:
```sh
git clone https://github.com/ankane/mailkick.git
cd mailkick
bundle install
bundle exec rake test
```