mailkick 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 716fa3a1fdcc00415b50a343d0d38eb434bece3f
+  data.tar.gz: 35649c58e33998450e8494620619720aa02b9448
+SHA512:
+  metadata.gz: fe3729d2ec69f27b1216ad302770560b826363b23ded849b694694e321e33938cea3d9bff5926d47b488b891fe19af1e53ffc3becfdcf360c65d6877475c7555
+  data.tar.gz: 1ba653ab1c80211110aa177179f16e020a01361c2c4ec48fbb7e7399d303d5165de8fe38628aee2181c585d98359407d6499796644ceb998c543ca62e4093e10

data/.gitignore

@@ -0,0 +1,22 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+## 0.0.1
+
+- First release

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in mailkick.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Andrew Kane
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,159 @@
+# Mailkick
+
+:bullettrain_side: Email subscriptions made easy
+
+- Add one-click unsubscribe links to your emails
+- Fetch bounces and spam reports from your email service
+
+Gracefully handles email address changes
+
+:postbox: Check out [Ahoy Email](https://github.com/ankane/ahoy_email) for analytics
+
+## Installation
+
+Add this line to your application’s Gemfile:
+
+```ruby
+gem 'mailkick'
+```
+
+And run the generator. This creates a model to store opt-outs.
+
+```sh
+rails generate mailkick:install
+rake db:migrate
+```
+
+## How It Works
+
+Add an unsubscribe link to your emails.
+
+#### Text
+
+```erb
+Unsubscribe: <%= mailkick_unsubscribe_url %>
+```
+
+#### HTML
+
+```erb
+<%= 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:
+
+```sh
+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 the method to your user model.
+
+```ruby
+class User < ActiveRecord::Base
+  mailkick_user
+end
+```
+
+Get all users who have not unsubscribed
+
+```ruby
+User.subscribed
+```
+
+Check one user
+
+```ruby
+user.subscribed?
+```
+
+Unsubscribe
+
+```ruby
+user.unsubscribe
+```
+
+Subscribe
+
+```ruby
+user.subscribe
+```
+
+## Bounces and Spam Reports
+
+Pull bounces, spam reports, and unsubscribes from your email service.
+
+```ruby
+Mailkick.fetch_opt_outs
+```
+
+#### Sendgrid
+
+Add the gem
+
+```ruby
+gem 'sendgrid_toolkit'
+```
+
+Be sure `ENV["SENDGRID_USERNAME"]` and `ENV["SENDGRID_PASSWORD"]` are set.
+
+#### Mandrill [broken]
+
+```ruby
+gem 'mandrill-api'
+```
+
+Be sure `ENV["MANDRILL_APIKEY"]` is set.
+
+#### Other
+
+Send a pull request.
+
+### Advanced
+
+For more control over the services, set them by hand.
+
+```ruby
+Mailkick.services = [
+  Mailkick::Service::Sendgrid.new(api_key: "API_KEY"),
+  Mailkick::Service::Mandrill.new(api_key: "API_KEY")
+]
+```
+
+## Multiple Lists
+
+Coming soon
+
+## Bonus
+
+More great gems for email
+
+- [Roadie](https://github.com/Mange/roadie) - inline CSS
+
+## Reference
+
+Change how the user is determined
+
+```ruby
+Mailkick.user_method = proc {|email| User.where(email: email).first }
+```
+
+## 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

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+

data/app/controllers/mailkick/subscriptions_controller.rb

@@ -0,0 +1,67 @@
+module Mailkick
+  class SubscriptionsController < ActionController::Base
+    before_filter :set_email
+
+    def show
+    end
+
+    def unsubscribe
+      if subscribed?
+        Mailkick::OptOut.create! do |o|
+          o.email = @email
+          o.user = @user
+          o.reason = "unsubscribe"
+        end
+      end
+
+      redirect_to subscription_path(params[:id])
+    end
+
+    def subscribe
+      Mailkick::OptOut.where(email: @email, active: true).each do |opt_out|
+        opt_out.active = false
+        opt_out.save!
+      end
+      if @user and @user.respond_to?(:subscribe)
+        @user.subscribe
+      end
+
+      redirect_to subscription_path(params[:id])
+    end
+
+    protected
+
+    def set_email
+      verifier = ActiveSupport::MessageVerifier.new(Mailkick.secret_token)
+      begin
+        @email, user_id, user_type = 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
+      rescue ActiveSupport::MessageVerifier::InvalidSignature
+        render text: "Subscription not found", status: :bad_request
+      end
+    end
+
+    def subscribed?
+      if @user and @user.respond_to?(:subscribed?)
+        @user.subscribed?
+      else
+        Mailkick::OptOut.where(email: @email, active: true).empty?
+      end
+    end
+    helper_method :subscribed?
+
+    def subscribe_url
+      subscribe_subscription_path(params[:id])
+    end
+    helper_method :subscribe_url
+
+    def unsubscribe_url
+      unsubscribe_subscription_path(params[:id])
+    end
+    helper_method :unsubscribe_url
+
+  end
+end

data/app/helpers/mailkick/url_helper.rb

@@ -0,0 +1,15 @@
+module Mailkick
+  module UrlHelper
+
+    def mailkick_unsubscribe_url
+      Mailkick::Engine.routes.url_helpers.url_for(
+        Rails.application.config.action_mailer.default_url_options.merge(
+          controller: "mailkick/subscriptions",
+          action: "unsubscribe",
+          id: "{{MAILKICK_TOKEN}}"
+        )
+      )
+    end
+
+  end
+end

data/app/models/mailkick/opt_out.rb

@@ -0,0 +1,7 @@
+module Mailkick
+  class OptOut < ActiveRecord::Base
+    self.table_name = "mailkick_opt_outs"
+
+    belongs_to :user, polymorphic: true
+  end
+end

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

@@ -0,0 +1,36 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Subscriptions</title>
+
+    <style>
+      body {
+        padding: 20px;
+        font-family: "Helvetica Neue", Arial, Helvetica, sans-serif;
+        font-size: 14px;
+        line-height: 1.4;
+      }
+
+      a {
+        color: blue;
+      }
+
+      .container {
+        max-width: 500px;
+        margin-left: auto;
+        margin-right: auto;
+      }
+    </style>
+  </head>
+  <body>
+    <div class="container">
+      <% if subscribed? %>
+        <p>You are subscribed.</p>
+        <p><%= link_to "Unsubscribe", unsubscribe_url %></p>
+      <% else %>
+        <p>You are unsubscribed.</p>
+        <p><%= link_to "Resubscribe", subscribe_url %></p>
+      <% end %>
+    </div>
+  </body>
+</html>

data/config/routes.rb

@@ -0,0 +1,10 @@
+Rails.application.routes.draw do
+  mount Mailkick::Engine => "/mailkick"
+end
+
+Mailkick::Engine.routes.draw do
+  resources :subscriptions, only: [:show] do
+    get :unsubscribe, on: :member
+    get :subscribe, on: :member
+  end
+end

data/lib/generators/mailkick/install_generator.rb

@@ -0,0 +1,30 @@
+# 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
+
+      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
+      end
+
+      def copy_migration
+        migration_template "install.rb", "db/migrate/install_mailkick.rb"
+      end
+
+    end
+  end
+end

data/lib/generators/mailkick/templates/install.rb

@@ -0,0 +1,15 @@
+class <%= migration_class_name %> < ActiveRecord::Migration
+  def change
+    create_table :mailkick_opt_outs do |t|
+      t.string :email
+      t.integer :user_id
+      t.string :user_type
+      t.boolean :active, null: false, default: true
+      t.string :reason
+      t.timestamps
+    end
+
+    add_index :mailkick_opt_outs, :email
+    add_index :mailkick_opt_outs, [:user_id, :user_type]
+  end
+end

data/lib/generators/mailkick/views_generator.rb

@@ -0,0 +1,14 @@
+require "rails/generators"
+
+module Mailkick
+  module Generators
+    class ViewsGenerator < Rails::Generators::Base
+      source_root File.expand_path("../../../../app/views", __FILE__)
+
+      def copy_initializer_file
+        directory "mailkick", "app/views/mailkick"
+      end
+
+    end
+  end
+end

data/lib/mailkick/engine.rb

@@ -0,0 +1,13 @@
+module Mailkick
+  class Engine < ::Rails::Engine
+    isolate_namespace Mailkick
+
+    initializer "mailkick" do |app|
+      Mailkick.discover_services
+      Mailkick.secret_token = app.config.try(:secret_key_base) || app.config.try(:secret_token)
+      ActiveSupport.on_load :action_mailer do
+        helper Mailkick::UrlHelper
+      end
+    end
+  end
+end

data/lib/mailkick/mailer.rb

@@ -0,0 +1,19 @@
+module Mailkick
+  module Mailer
+
+    def self.included(base)
+      base.class_eval do
+        alias_method_chain :mail, :mailkick
+      end
+    end
+
+    def mail_with_mailkick(headers = {}, &block)
+      message = mail_without_mailkick(headers, &block)
+
+      Mailkick::Processor.new(message).process
+
+      message
+    end
+
+  end
+end

data/lib/mailkick/model.rb

@@ -0,0 +1,40 @@
+module Mailkick
+  module Model
+
+    def mailkick_user(options = {})
+      class_eval do
+        scope :subscribed, proc{ joins(sanitize_sql_array(["LEFT JOIN mailkick_opt_outs ON #{table_name}.email = mailkick_opt_outs.email OR (#{table_name}.id = mailkick_opt_outs.user_id AND mailkick_opt_outs.user_type = ?)", name])).where("active != ?", true) }
+
+        def opt_outs
+          Mailkick::OptOut.where("email = ? OR (user_id = ? AND user_type = ?)", email, id, self.class.name)
+        end
+
+        def subscribed?
+          opt_outs.where(active: true).empty?
+        end
+
+        def subscribe
+          opt_outs.where(active: true).each do |opt_out|
+            opt_out.active = false
+            opt_out.save!
+          end
+          true
+        end
+
+        def unsubscribe
+          if subscribed?
+            OptOut.create! do |o|
+              o.email = email
+              o.user = self
+              o.reason = "unsubscribe"
+              o.save!
+            end
+          end
+          true
+        end
+
+      end
+    end
+
+  end
+end

data/lib/mailkick/processor.rb

@@ -0,0 +1,23 @@
+module Mailkick
+  class Processor
+    attr_reader :message
+
+    def initialize(message)
+      @message = message
+    end
+
+    def process
+      email = message.to.first
+      user = Mailkick.user_method.call(email) if Mailkick.user_method
+
+      verifier = ActiveSupport::MessageVerifier.new(Mailkick.secret_token)
+      token = verifier.generate([email, user.try(:id), user.try(:class).try(:name)])
+
+      parts = message.parts.any? ? message.parts : [message]
+      parts.each do |part|
+        part.body.raw_source.gsub!(/%7B%7BMAILKICK_TOKEN%7D%7D/, token)
+      end
+    end
+
+  end
+end

data/lib/mailkick/service/mandrill.rb

@@ -0,0 +1,25 @@
+# https://mandrillapp.com/api/docs/index.ruby.html
+
+module Mailkick
+  class Service
+    class Mandrill < Mailkick::Service
+
+      def initialize(options = {})
+        require "mandrill"
+        @mandrill = ::Mandrill::API.new(options[:api_key] || ENV["MANDRILL_APIKEY"])
+      end
+
+      def opt_outs
+        # @mandrill.rejects.list.map do |record|
+        #   record
+        # end
+        []
+      end
+
+      def self.discoverable?
+        !!(defined?(::Mandrill::API) && ENV["MANDRILL_APIKEY"])
+      end
+
+    end
+  end
+end

data/lib/mailkick/service/sendgrid.rb

@@ -0,0 +1,46 @@
+# https://github.com/freerobby/sendgrid_toolkit
+
+module Mailkick
+  class Service
+    class Sendgrid < Mailkick::Service
+
+      def initialize(options = {})
+        @api_user = options[:api_user] || ENV["SENDGRID_USERNAME"]
+        @api_key = options[:api_key] || ENV["SENDGRID_PASSWORD"]
+      end
+
+      def opt_outs
+        unsubscribes + spam_reports + bounces
+      end
+
+      def unsubscribes
+        fetch(::SendgridToolkit::Unsubscribes, "unsubscribe")
+      end
+
+      def spam_reports
+        fetch(::SendgridToolkit::SpamReports, "spam")
+      end
+
+      def bounces
+        fetch(::SendgridToolkit::Bounces, "bounce")
+      end
+
+      def self.discoverable?
+        !!(defined?(::SendgridToolkit) && ENV["SENDGRID_USERNAME"] && ENV["SENDGRID_PASSWORD"])
+      end
+
+      protected
+
+      def fetch(klass, reason)
+        klass.new(@api_user, @api_key).retrieve_with_timestamps.map do |record|
+          {
+            email: record["email"],
+            time: record["created"],
+            reason: reason
+          }
+        end
+      end
+
+    end
+  end
+end

data/lib/mailkick/service.rb

@@ -0,0 +1,24 @@
+module Mailkick
+  class Service
+
+    def fetch_opt_outs
+      opt_outs.each do |api_data|
+        email = api_data[:email]
+        time = api_data[:time]
+
+        opt_out = Mailkick::OptOut.where(email: email).order("updated_at desc").first
+        if !opt_out or (time > opt_out.updated_at and !opt_out.active)
+          Mailkick::OptOut.create! do |o|
+            o.email = email
+            o.user = Mailkick.user_method if Mailkick.user_method.call(email)
+            o.reason = api_data[:reason]
+            o.created_at = time
+            o.updated_at = time
+          end
+        end
+      end
+      true
+    end
+
+  end
+end

data/lib/mailkick/version.rb

@@ -0,0 +1,3 @@
+module Mailkick
+  VERSION = "0.0.1"
+end

data/lib/mailkick.rb

@@ -0,0 +1,32 @@
+require "mailkick/version"
+require "mailkick/engine"
+require "mailkick/processor"
+require "mailkick/mailer"
+require "mailkick/model"
+require "mailkick/service"
+require "mailkick/service/mandrill"
+require "mailkick/service/sendgrid"
+
+module Mailkick
+  mattr_accessor :services, :user_method, :secret_token
+  self.services = []
+  self.user_method = proc{|email| User.where(email: email).first rescue nil }
+
+  def self.fetch_opt_outs
+    services.each do |service|
+      service.fetch_opt_outs
+    end
+  end
+
+  def self.discover_services
+    Service.subclasses.each do |service|
+      if service.discoverable?
+        services << service.new
+      end
+    end
+  end
+
+end
+
+ActionMailer::Base.send :include, Mailkick::Mailer
+ActiveRecord::Base.send(:extend, Mailkick::Model) if defined?(ActiveRecord)

data/mailkick.gemspec

@@ -0,0 +1,23 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'mailkick/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "mailkick"
+  spec.version       = Mailkick::VERSION
+  spec.authors       = ["Andrew Kane"]
+  spec.email         = ["andrew@chartkick.com"]
+  spec.summary       = %q{Email subscriptions made easy}
+  spec.description   = %q{Email subscriptions made easy}
+  spec.homepage      = "https://github.com/ankane/mailkick"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.6"
+  spec.add_development_dependency "rake"
+end

metadata

@@ -0,0 +1,96 @@
+--- !ruby/object:Gem::Specification
+name: mailkick
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Andrew Kane
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-05-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Email subscriptions made easy
+email:
+- andrew@chartkick.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- CHANGELOG.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- app/controllers/mailkick/subscriptions_controller.rb
+- app/helpers/mailkick/url_helper.rb
+- app/models/mailkick/opt_out.rb
+- app/views/mailkick/subscriptions/show.html.erb
+- config/routes.rb
+- lib/generators/mailkick/install_generator.rb
+- lib/generators/mailkick/templates/install.rb
+- lib/generators/mailkick/views_generator.rb
+- lib/mailkick.rb
+- lib/mailkick/engine.rb
+- lib/mailkick/mailer.rb
+- lib/mailkick/model.rb
+- lib/mailkick/processor.rb
+- lib/mailkick/service.rb
+- lib/mailkick/service/mandrill.rb
+- lib/mailkick/service/sendgrid.rb
+- lib/mailkick/version.rb
+- mailkick.gemspec
+homepage: https://github.com/ankane/mailkick
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Email subscriptions made easy
+test_files: []