mailkick 0.3.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7a36d760e07c5d02d2a0a685c4ced2e9075eb0e272f7814b08fd477fd282a9a0
-  data.tar.gz: 6038e41c31a36c14fd7438fc870531773fb6098d0932e72b4d187dc9c51ef634
+  metadata.gz: 2ff139814252a1c4ec153cc81f311dd5d8c1745a4970aaab8cb2164df4d4692d
+  data.tar.gz: 1e4700dc2dbb96dcb09c4c79c00a837de387c8712db72c3bc13150ea94355da2
 SHA512:
-  metadata.gz: f1f4229e0f2191437d1cda0ef791683908cbc9d5a98519ba8fd00f9250b6f64f9aa0f9ec0df8be05c62506bf6d7e407bf610643d7f2faf979c066d8e977f7efc
-  data.tar.gz: b2801fbe7e9bb5de9d3eda275e7b162b68ccf5ff3ad352cb5b4462a3e617edb44cae177652d3c7ecda70f7dd35abc2755cc958219e761510270f32605f7eae91
+  metadata.gz: f28ec4a1bb1fa022ad4bd9a250a45650562db467a7c6d14f0150e5f9c8137cd766376a605c0304092ff7036d2efca22ae95e3d61e5693d40f616205b54aedb72
+  data.tar.gz: 5eb0a1544b00da879c77c2919501c2b21f6c4916e7bc1b710ad271c33ba6cd9cd6607d5d8c06f64380ce825f11187ff841deb21c58cd9ee4a8af3536ff3f594b

data/CHANGELOG.md

@@ -1,79 +1,102 @@
-## 0.3.1
+## 1.0.0 (2021-06-03)
+
+- Switched from opt-outs to subscriptions
+
+## 0.4.3 (2020-11-01)
+
+- Added support for AWS SES
+
+## 0.4.2 (2020-04-06)
+
+- Added support for official SendGrid gem
+- Fixed deprecation warning
+
+## 0.4.1 (2019-10-27)
+
+- Added Postmark support
+
+## 0.4.0 (2019-07-15)
+
+- Fixed error with model methods and `email_key` option
+- Fixed bug with `opted_out` scope
+- Dropped support for Action Mailer 4.2
+
+## 0.3.1 (2018-04-21)
 
 - Fixed `Secret should not be nil` error in Rails 5.2
 - Gracefully handle missing email
 - Added `user` option to `mailkick_unsubscribe_url`
 
-## 0.3.0
+## 0.3.0 (2018-04-20)
 
 - Improved performance
 - Fixed `Subscription not found` for Rails 5.2
 - Use `references` in migration
 - Use `smtp_settings[:domain]` for Mailgun
-- Dropped support for ActionMailer < 4.2
+- Dropped support for Action Mailer < 4.2
 
-## 0.2.1
+## 0.2.1 (2017-10-30)
 
 - Fixed errors with Rails 5+
 - Fixed errors with the latest version of Gibbon
 
-## 0.2.0
+## 0.2.0 (2017-05-01)
 
 - Added support for Rails 5.1
 
-## 0.1.6
+## 0.1.6 (2017-01-10)
 
 - Fixed error with frozen strings
 
-## 0.1.5
+## 0.1.5 (2016-12-06)
 
 - Use `safely`
 - Only discover services if not manually set
 - Added `mount` option
 
-## 0.1.4
+## 0.1.4 (2016-02-20)
 
 - Use `Module#prepend` instead of `alias_method_chain`
 
-## 0.1.3
+## 0.1.3 (2015-06-29)
 
 - Fixed issue with double escaping tokens
 
-## 0.1.2
+## 0.1.2 (2015-06-07)
 
 - Added support for Mailgun
 
-## 0.1.1
+## 0.1.1 (2015-01-31)
 
 - Fixed tokens with `+` in them
 
-## 0.1.0
+## 0.1.0 (2014-08-31)
 
 - Fixed secret token for Rails 4.1
 
-## 0.0.6
+## 0.0.6 (2014-05-09)
 
 - Rails 3 fix
 
-## 0.0.5
+## 0.0.5 (2014-05-05)
 
 - Fixed bug with subscriptions page
 
-## 0.0.4
+## 0.0.4 (2014-05-05)
 
 - Added `email_key` option to `mailkick_user`
 
-## 0.0.3
+## 0.0.3 (2014-05-04)
 
 - Added support for multiple lists
 - Changed `mailkick_user` method names - sorry early adopters :(
 
-## 0.0.2
+## 0.0.2 (2014-05-04)
 
 - Added Mailchimp service
 - Fixed Mandrill service
 - Added `uniq` to `subscribed` scope
 
-## 0.0.1
+## 0.0.1 (2014-05-04)
 
 - First release

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2014 Andrew Kane
+Copyright (c) 2014-2021 Andrew Kane
 
 MIT License
 

data/README.md

@@ -1,14 +1,15 @@
 # Mailkick
 
-Email subscriptions made easy
+Email subscriptions for Rails
 
 - Add one-click unsubscribe links to your emails
 - Fetch bounces and spam reports from your email service
-- Gracefully handles email address changes
+
+**Mailkick 1.0 was recently released** - see [how to upgrade](#upgrading)
 
 :postbox: Check out [Ahoy Email](https://github.com/ankane/ahoy_email) for analytics
 
-[![Build Status](https://travis-ci.org/ankane/mailkick.svg?branch=master)](https://travis-ci.org/ankane/mailkick)
+[![Build Status](https://github.com/ankane/mailkick/workflows/build/badge.svg?branch=master)](https://github.com/ankane/mailkick/actions)
 
 ## Installation
 
@@ -18,191 +19,249 @@ Add this line to your application’s Gemfile:
 gem 'mailkick'
 ```
 
-And run the generator. This creates a model to store opt-outs.
+And run the generator. This creates a table to store subscriptions.
 
 ```sh
+bundle install
 rails generate mailkick:install
 rails db:migrate
 ```
 
-## How It Works
-
-Add an unsubscribe link to your emails.
+## Getting Started
 
-#### Text
+Add `has_subscriptions` to your user model:
 
-```erb
-Unsubscribe: <%= mailkick_unsubscribe_url %>
+```ruby
+class User < ApplicationRecord
+  has_subscriptions
+end
 ```
 
-#### HTML
+Subscribe to a list
 
-```erb
-<%= link_to "Unsubscribe", mailkick_unsubscribe_url %>
+```ruby
+user.subscribe("sales")
 ```
 
-When a user unsubscribes, he or she is taken to a mobile-friendly page and given the option to resubscribe.
+Unsubscribe from a list
 
-To customize the view, run:
-
-```sh
-rails generate mailkick:views
+```ruby
+user.unsubscribe("sales")
 ```
 
-which copies the view into `app/views/mailkick`.
+Check if subscribed
 
-## Sending Emails
-
-Before sending marketing emails, make sure the user has not opted out.
+```ruby
+user.subscribed?("sales")
+```
 
-Add the following method to models with email addresses.
+Get subscribers for a list (use this for sending emails)
 
 ```ruby
-class User < ApplicationRecord
-  mailkick_user
-end
+User.subscribed("sales")
 ```
 
-Get all users who have opted out
+## Unsubscribe Links
 
-```ruby
-User.opted_out
+Add an unsubscribe link to your emails. For HTML emails, use:
+
+```erb
+<%= link_to "Unsubscribe", mailkick_unsubscribe_url(@user, "sales") %>
 ```
 
-And those who have not - send to these people
+For text emails, use:
 
-```ruby
-User.not_opted_out
+```erb
+Unsubscribe: <%= mailkick_unsubscribe_url(@user, "sales") %>
 ```
 
-Check one user
+When a user unsubscribes, they are taken to a mobile-friendly page and given the option to resubscribe. To customize the view, run:
 
-```ruby
-user.opted_out?
+```sh
+rails generate mailkick:views
 ```
 
+which copies the view into `app/views/mailkick`.
+
 ## Bounces and Spam Reports
 
-Fetch bounces, spam reports, and unsubscribes from your email service.
+Fetch bounces, spam reports, and unsubscribes from your email service. Create `config/initializers/mailkick.rb` with a method to handle opt outs.
 
 ```ruby
-Mailkick.fetch_opt_outs
+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.updated_at < opt_out[:time]
+    end
+  end
+end
 ```
 
-#### Sendgrid
-
-Add the gem
+And run:
 
 ```ruby
-gem 'sendgrid_toolkit'
+Mailkick.fetch_opt_outs
 ```
 
-Be sure `ENV["SENDGRID_USERNAME"]` and `ENV["SENDGRID_PASSWORD"]` are set.
+The following services are supported:
 
-#### Mandrill
+- [AWS SES](#aws-ses)
+- [Mailchimp](#mailchimp)
+- [Mailgun](#mailgun)
+- [Mandrill](#mandrill)
+- [Postmark](#postmark)
+- [SendGrid](#sendgrid)
+
+Will gladly accept pull requests for others.
+
+#### AWS SES
+
+Add the gem
 
 ```ruby
-gem 'mandrill-api'
+gem 'aws-sdk-sesv2'
 ```
 
-Be sure `ENV["MANDRILL_APIKEY"]` is set.
+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'
 ```
 
-Be sure `ENV["MAILCHIMP_API_KEY"]` and `ENV["MAILCHIMP_LIST_ID"]` are set.
+And set `ENV["MAILCHIMP_API_KEY"]` and `ENV["MAILCHIMP_LIST_ID"]`.
 
 #### Mailgun
 
+Add the gem
+
 ```ruby
 gem 'mailgun-ruby'
 ```
 
-Be sure `ENV["MAILGUN_API_KEY"]` is set.
+And set `ENV["MAILGUN_API_KEY"]`.
 
-#### Other
-
-Will gladly accept pull requests.
-
-### Advanced
+#### Mandrill
 
-For more control over services, set them by hand.
+Add the gem
 
 ```ruby
-Mailkick.services = [
-  Mailkick::Service::Sendgrid.new(api_key: "API_KEY"),
-  Mailkick::Service::Mandrill.new(api_key: "API_KEY")
-]
+gem 'mandrill-api'
 ```
 
-## Multiple Lists
+And set `ENV["MANDRILL_APIKEY"]`.
+
+#### Postmark
 
-You may want to split your emails into multiple categories, like sale emails and order reminders. Set the list in the url:
+Add the gem
 
 ```ruby
-mailkick_unsubscribe_url(list: "order_reminders")
+gem 'postmark'
 ```
 
-Pass the `list` option to methods.
+And set `ENV["POSTMARK_API_KEY"]`.
+
+#### SendGrid
+
+Add the gem
 
 ```ruby
-User.opted_out(list: "order_reminders")
-User.not_opted_out(list: "order_reminders")
-user.opted_out?(list: "order_reminders")
+gem 'sendgrid-ruby'
 ```
 
-### Opt-In Lists
+And set `ENV["SENDGRID_API_KEY"]`. The API key requires only the `Suppressions` permission.
 
-For opt-in lists, you’ll need to manage the subscribers yourself.
+### Advanced
 
-Check opt-ins against the opt-outs
+For more control over services, set them by hand.
 
 ```ruby
-User.where(send_me_sales: true).not_opted_out(list: "sales")
+Mailkick.services = [
+  Mailkick::Service::SendGridV2.new(api_key: "API_KEY"),
+  Mailkick::Service::Mailchimp.new(api_key: "API_KEY", list_id: "LIST_ID")
+]
 ```
 
-Check one user
+## Reference
+
+Access the subscription model directly
 
 ```ruby
-user.send_me_sales && !user.opted_out?(list: "sales")
+Mailkick::Subscription.all
 ```
 
-## Bonus
+## Upgrading
 
-More great gems for email
+### 1.0
 
-- [Roadie](https://github.com/Mange/roadie) - inline CSS
-- [Letter Opener](https://github.com/ryanb/letter_opener) - preview email in development
+Mailkick 1.0 stores subscriptions instead of opt-outs. To migrate:
 
-## Reference
-
-Change how the user is determined
+1. Add a table to store subscriptions
 
-```ruby
-Mailkick.user_method = ->(email) { User.find_by(email: email) }
+```sh
+rails generate mailkick:install
+rails db:migrate
 ```
 
-Use a different email field
+2. Change the following methods in your code:
+
+- `mailkick_user` to `has_subscriptions`
+- `User.not_opted_out` to `User.subscribed(list)`
+- `opt_in` to `subscribe(list)`
+- `opt_out` to `unsubscribe(list)`
+
+3. Add a user and list to `mailkick_unsubscribe_url`
 
 ```ruby
-mailkick_user email_key: :email_address
+mailkick_unsubscribe_url(user, list)
 ```
 
-Unsubscribe
+4. Migrate data for each of your lists
 
 ```ruby
-user.opt_out
+opted_out_emails = Mailkick::Legacy.opted_out_emails(list: nil)
+opted_out_users = Mailkick::Legacy.opted_out_users(list: nil)
+
+User.find_in_batches do |users|
+  users.reject! { |u| opted_out_emails.include?(u.email) }
+  users.reject! { |u| opted_out_users.include?(u) }
+
+  now = Time.now
+  records =
+    users.map do |user|
+      {
+        subscriber_type: user.class.name,
+        subscriber_id: user.id,
+        list: "sales",
+        created_at: now,
+        updated_at: now
+      }
+    end
+
+  # use create! for Active Record < 6
+  Mailkick::Subscription.insert_all!(records)
+end
 ```
 
-Resubscribe
+5. Drop the `mailkick_opt_outs` table
 
 ```ruby
-user.opt_in
+drop_table :mailkick_opt_outs
 ```
 
+Also, if you use `Mailkick.fetch_opt_outs`, [add a method](#bounces-and-spam-reports) to handle opt outs.
+
 ## History
 
 View the [changelog](https://github.com/ankane/mailkick/blob/master/CHANGELOG.md)
@@ -215,3 +274,12 @@ Everyone is encouraged to help improve this project. Here are a few ways you can
 - 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
+```