mailkick 0.4.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8256980737a3ffda9fce00c4117b05566bf89728f39869e3c5f8afd8a0419728
-  data.tar.gz: dc8887bf9b238bdc3031e7f1b0aa3ba42a36f371494f62583b319b84dab70162
+  metadata.gz: e84a6786c23946b6e27a67a14d75c01da5cde231928d19c65edd2b591de9a153
+  data.tar.gz: 1a944d065c7bf4c164db038aabe0073b3759e96a232ec22b29e86cf746ffc02f
 SHA512:
-  metadata.gz: 670b60804614ab81daba07cbc20fdde047386b6ea704f66ce4934737b9211b16e34683ad469f318683195aa7036d19615ba4a0363352c0979ec6a40b2467f009
-  data.tar.gz: b5acb8496859d172360fb59ff06a7406831b79837264758eb9f6ba88c47ff3b731404b7a75bf08c59539553ff8ab44901785485e996c69063bdb086973a70977
+  metadata.gz: 3ed9f0315dc5c60ed5b2cc524fd13763566b6126bafceb665dbddcdc2a182f4408a370e267fdcc8ab97cbe616684c7ff5ab91b0fe717d39a65deac854cd3b958
+  data.tar.gz: 82c2c1d7a1d0077eb60df59a9d672039b17750462a435afdef19125e26f3c122600a2a8f394c06a3119a64c773d4a6ef7a1f61dc5081dca587735eda80c4a9c3

data/CHANGELOG.md

@@ -1,16 +1,38 @@
-## 0.4.0
+## 1.0.1 (2021-06-20)
+
+- Fixed error message when process out-opts not configured
+
+## 1.0.0 (2021-06-03)
+
+- Switched from opt-outs to subscriptions
+- Dropped support for Ruby < 2.6 and Rails < 5.2
+
+## 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
+## 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
@@ -18,68 +40,68 @@
 - Use `smtp_settings[:domain]` for Mailgun
 - 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-2019 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,197 +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.created_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:
 
-```ruby
-mailkick_user email_key: :email_address
-```
+- `mailkick_user` to `has_subscriptions`
+- `User.not_opted_out` to `User.subscribed(list)`
+- `opt_in` to `subscribe(list)`
+- `opt_out` to `unsubscribe(list)`
 
-Unsubscribe
+3. Add a user and list to `mailkick_unsubscribe_url`
 
 ```ruby
-user.opt_out
+mailkick_unsubscribe_url(user, list)
 ```
 
-Resubscribe
+4. Migrate data for each of your lists
 
 ```ruby
-user.opt_in
+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
 ```
 
-Access the opt-out model directly
+5. Drop the `mailkick_opt_outs` table
 
 ```ruby
-Mailkick::OptOut.all
+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)
@@ -221,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
+```