mailkick 0.1.4 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 0bf0541ba51746a50f8a286d7acd0bed58660b4b
-  data.tar.gz: 796d78becdc4f302b06dd1eb7bf44df154fd9e6f
+SHA256:
+  metadata.gz: e84a6786c23946b6e27a67a14d75c01da5cde231928d19c65edd2b591de9a153
+  data.tar.gz: 1a944d065c7bf4c164db038aabe0073b3759e96a232ec22b29e86cf746ffc02f
 SHA512:
-  metadata.gz: da32468a31c92c6e674eb1b397827d155c01bd918ade637c9145702b92c35ebb39c916eee01c680efad85ac1b2d298ad2b4b9bb2033bd1d04dfab67baca8e58c
-  data.tar.gz: 11cbb1e1b2cce5d3763cb11517892d010240ad24e467ff3a2f9b9d8f1d69a1320ab8efd777093edaf328ba1241495bf2f50303d39e82b5333e35dd49b8b130bd
+  metadata.gz: 3ed9f0315dc5c60ed5b2cc524fd13763566b6126bafceb665dbddcdc2a182f4408a370e267fdcc8ab97cbe616684c7ff5ab91b0fe717d39a65deac854cd3b958
+  data.tar.gz: 82c2c1d7a1d0077eb60df59a9d672039b17750462a435afdef19125e26f3c122600a2a8f394c06a3119a64c773d4a6ef7a1f61dc5081dca587735eda80c4a9c3

data/CHANGELOG.md

@@ -1,46 +1,107 @@
-## 0.1.4
+## 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 (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 (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 Action Mailer < 4.2
+
+## 0.2.1 (2017-10-30)
+
+- Fixed errors with Rails 5+
+- Fixed errors with the latest version of Gibbon
+
+## 0.2.0 (2017-05-01)
+
+- Added support for Rails 5.1
+
+## 0.1.6 (2017-01-10)
+
+- Fixed error with frozen strings
+
+## 0.1.5 (2016-12-06)
+
+- Use `safely`
+- Only discover services if not manually set
+- Added `mount` option
+
+## 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,16 @@
 # Mailkick
 
-:bullettrain_side: 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://github.com/ankane/mailkick/workflows/build/badge.svg?branch=master)](https://github.com/ankane/mailkick/actions)
+
 ## Installation
 
 Add this line to your application’s Gemfile:
@@ -17,205 +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
-rake db:migrate
+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.
-
-To customize the view, run:
+Unsubscribe from a list
 
-```sh
-rails generate mailkick:views
+```ruby
+user.unsubscribe("sales")
 ```
 
-which copies the view into `app/views/mailkick`.
-
-## Sending Emails
+Check if subscribed
 
-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 < ActiveRecord::Base
-  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)
 
-#### Sendgrid
+  opt_outs.each do |opt_out|
+    subscriber = subscribers[opt_out[:email]]
+    next unless subscriber
 
-Add the gem
+    subscriber.mailkick_subscriptions.each do |subscription|
+      subscription.destroy if subscription.created_at < opt_out[:time]
+    end
+  end
+end
+```
+
+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'
+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 [beta]
+And set `ENV["MANDRILL_APIKEY"]`.
 
-You may want to split your emails into multiple categories, like sale emails and order reminders.
+#### Postmark
 
-Set the list in the mailer.
+Add the gem
 
 ```ruby
-class UserMailer < ActionMailer::Base
+gem 'postmark'
+```
 
-  def order_reminder(user)
-    headers[:mailkick_list] = "order_reminders"
-    # ...
-  end
+And set `ENV["POSTMARK_API_KEY"]`.
 
-end
-```
+#### SendGrid
 
-Pass the `list` option to methods.
+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
-
-More great gems for email
+## Upgrading
 
-- [Roadie](https://github.com/Mange/roadie) - inline CSS
-- [Letter Opener](https://github.com/ryanb/letter_opener) - preview email in development
+### 1.0
 
-## TODO
+Mailkick 1.0 stores subscriptions instead of opt-outs. To migrate:
 
-- Make it easy to customize controller
-- Subscribe to events
+1. Add a table to store subscriptions
 
-## Reference
+```sh
+rails generate mailkick:install
+rails db:migrate
+```
 
-Change how the user is determined
+2. Change the following methods in your code:
 
-```ruby
-Mailkick.user_method = proc {|email| User.where(email: email).first }
-```
+- `mailkick_user` to `has_subscriptions`
+- `User.not_opted_out` to `User.subscribed(list)`
+- `opt_in` to `subscribe(list)`
+- `opt_out` to `unsubscribe(list)`
 
-Use a different email field
+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)
@@ -228,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
+```

data/app/controllers/mailkick/subscriptions_controller.rb

@@ -1,42 +1,51 @@
 module Mailkick
   class SubscriptionsController < ActionController::Base
-    before_filter :set_email
+    protect_from_forgery with: :exception
+
+    before_action :set_subscription
 
     def show
     end
 
     def unsubscribe
-      Mailkick.opt_out(@options)
+      subscription.delete_all
+
+      Mailkick::Legacy.opt_out(legacy_options) if Mailkick::Legacy.opt_outs?
+
       redirect_to subscription_path(params[:id])
     end
 
     def subscribe
-      Mailkick.opt_in(@options)
+      subscription.first_or_create!
+
+      Mailkick::Legacy.opt_in(legacy_options) if Mailkick::Legacy.opt_outs?
+
       redirect_to subscription_path(params[:id])
     end
 
     protected
 
-    def set_email
-      verifier = ActiveSupport::MessageVerifier.new(Mailkick.secret_token)
-      begin
-        @email, user_id, user_type, @list = verifier.verify(params[:id])
-        if user_type
-          # on the unprobabilistic chance user_type is compromised, not much damage
-          @user = user_type.constantize.find(user_id)
-        end
-        @options = {
-          email: @email,
-          user: @user,
-          list: @list
-        }
-      rescue ActiveSupport::MessageVerifier::InvalidSignature
-        render text: "Subscription not found", status: :bad_request
-      end
+    def set_subscription
+      @email, @subscriber_id, @subscriber_type, @list = Mailkick.message_verifier.verify(params[:id])
+    rescue ActiveSupport::MessageVerifier::InvalidSignature
+      render plain: "Subscription not found", status: :bad_request
     end
 
+    def subscription
+      Mailkick::Subscription.where(
+        subscriber_id: @subscriber_id,
+        subscriber_type: @subscriber_type,
+        list: @list
+      )
+    end
+
+    def subscribed?
+      subscription.exists?
+    end
+    helper_method :subscribed?
+
     def opted_out?
-      Mailkick.opted_out?(@options)
+      !subscribed?
     end
     helper_method :opted_out?
 
@@ -49,5 +58,17 @@ module Mailkick
       unsubscribe_subscription_path(params[:id])
     end
     helper_method :unsubscribe_url
+
+    def legacy_options
+      if @subscriber_type
+        # on the unprobabilistic chance subscriber_type is compromised, not much damage
+        user = @subscriber_type.constantize.find(@subscriber_id)
+      end
+      {
+        email: @email,
+        user: user,
+        list: @list
+      }
+    end
   end
 end

data/app/models/mailkick/opt_out.rb

@@ -2,6 +2,6 @@ module Mailkick
   class OptOut < ActiveRecord::Base
     self.table_name = "mailkick_opt_outs"
 
-    belongs_to :user, polymorphic: true
+    belongs_to :user, polymorphic: true, optional: true
   end
 end

data/app/models/mailkick/subscription.rb

@@ -0,0 +1,9 @@
+module Mailkick
+  class Subscription < ActiveRecord::Base
+    self.table_name = "mailkick_subscriptions"
+
+    belongs_to :subscriber, polymorphic: true
+
+    validates :list, presence: true
+  end
+end

data/app/views/mailkick/subscriptions/show.html.erb

@@ -24,7 +24,7 @@
   </head>
   <body>
     <div class="container">
-      <% if opted_out? %>
+      <% if !subscribed? %>
         <p>You are unsubscribed.</p>
         <p><%= link_to "Resubscribe", subscribe_url %></p>
       <% else %>

data/config/routes.rb

@@ -1,5 +1,7 @@
 Rails.application.routes.draw do
-  mount Mailkick::Engine => "/mailkick"
+  unless respond_to?(:has_named_route?) && has_named_route?("mailkick")
+    mount Mailkick::Engine => "/mailkick" if Mailkick.mount
+  end
 end
 
 Mailkick::Engine.routes.draw do

data/lib/generators/mailkick/install_generator.rb

@@ -1,28 +1,17 @@
-# taken from https://github.com/collectiveidea/audited/blob/master/lib/generators/audited/install_generator.rb
-require "rails/generators"
-require "rails/generators/migration"
-require "active_record"
 require "rails/generators/active_record"
 
 module Mailkick
   module Generators
     class InstallGenerator < Rails::Generators::Base
-      include Rails::Generators::Migration
+      include ActiveRecord::Generators::Migration
+      source_root File.join(__dir__, "templates")
 
-      source_root File.expand_path("../templates", __FILE__)
-
-      # Implement the required interface for Rails::Generators::Migration.
-      def self.next_migration_number(dirname) #:nodoc:
-        next_migration_number = current_migration_number(dirname) + 1
-        if ActiveRecord::Base.timestamped_migrations
-          [Time.now.utc.strftime("%Y%m%d%H%M%S"), "%.14d" % next_migration_number].max
-        else
-          "%.3d" % next_migration_number
-        end
+      def copy_migration
+        migration_template "install.rb", "db/migrate/create_mailkick_subscriptions.rb", migration_version: migration_version
       end
 
-      def copy_migration
-        migration_template "install.rb", "db/migrate/install_mailkick.rb"
+      def migration_version
+        "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]"
       end
     end
   end