email_events 1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: a50ec61b9cc483e32fa321362664ece0aa435628
+  data.tar.gz: 281031a6d100071fae7ddb5d4e8dce6332d6d3c0
+SHA512:
+  metadata.gz: d251a256c1798791572a0742f91412b307af47dd35f20b792c14bdf795b9f8407a36cae3f0dde09f43391401aa13ffcb19fcf4628d97f8c2352f86041aa79a53
+  data.tar.gz: 6d4f20aa9df67859b13c308c5b5bbea116616b2d88d48bc9a3bae582627aede91da7b87ce6b8b3509934e685668a49597c8190b206263f0fe6aadf6b5a4cdb12

data/.gitignore

@@ -0,0 +1,10 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+/.idea/

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Coupa Software Inc
+
+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,136 @@
+# EmailEvents
+
+EmailEvents handles incoming events for your emails: bounces, drops, delivery, link clicks, and replies. It aims to do
+this in a provider agnostic way.  Currently supports Sengrid and AWS.
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'email_events'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install email_events
+    
+Then install the migration for tracking sent emails:
+    
+    $ rails g email_events:install
+    
+### Rails configuration
+
+1. Setup your action_mailer smtp settings as usual. Email_events will detect whether your using Sendgrid SES based on the
+smtp address, but you can also set the adapter in an initializer -- eg. `EmailEvents.provider = :sendgrid`.
+
+2. **Important**: Set `config.action_mailer.smtp_settings[:return_response] = true`. This is necessary to get the email
+provider's unique ids back for tracking events against the original email.
+
+    
+### Sendgrid
+
+1. Login to your SendGrid account and navigate to "Mail Settings" -> Event Notification.
+
+2. Turn the module "On".
+
+3. Set the HTTP POST URL to https://<yourdomain>/email_events/sendgrid
+
+4. Under "Select Actions", choose the event types for which you would like to receive triggers.
+
+That's it!
+
+### AWS SES / SNS    
+
+1. Login to the AWS Management Console.
+
+2. Open up the AWS SNS console.
+
+3. Click "Create Topic".  Set both the the "Topic name" to "email_events" and the "Display name" to "emails". Click "Create topic".
+
+4. In the "Topic Details", click "Create Subscription".  Set the endpoint to https://<yourdomain>/email_events/ses.
+
+5. With your Rails server running, click "Request confirmations" to confirm the subscription at your endpoint.
+
+6. Open up the AWS SES console.
+
+7. Under either "Domains" or "Email Addresses" (depending on whether you want event triggers for an entire domain or individual
+senders), click on a domain or email adress, then click "Details" and expand the "Notifications" tab.
+
+8. Click Edit Configuration and set the SNS Topic to "email_events" for Bounces, Complaints, and/or Deliveries.
+
+9. At the moment, you need to mount the sns_endpoint gem engine which email_events uses (yes, a nice-to-have would be for
+ email_events to just act as an engine itself).  Put `mount SnsEndpoint::Core => '/email_events/ses'` in your routes.rb.
+
+## Usage
+
+### Basic
+
+Simply add an `on_event` handler to your mailer to start handling email events.  Eg.:
+
+```
+class MyMailer < ActionMailer::Base
+  on_event :handle_event
+
+  ...
+  
+  
+  def handle_event(event_data, email_data)
+    if event_data.event_type == :bounce
+      my_bounce_notification_method(email_data.to)
+    end     
+  end
+end
+```
+
+### Supported Event Types
+
+- For Sendgrid: :delivered, :bounce, :dropped, :deferred, :processed, :click, :open, :spamreport, :group_unsubscribe, :group_resubscribe
+- For AWS: :delivered, :bounce, :spamreport
+
+### Advanced
+
+You can track custom JSON data along with the original email message.  This data will then be available to you in the event
+handler:
+
+```
+class MyMailer < ActionMailer::Base
+  on_event :handle_event
+  track_data :custom_metadata
+
+  ...
+  
+  def custom_metadata
+    {
+      my_data: true
+    }
+  end
+  
+  def handle_event(event_data, email_data)
+    my_data = email_data.data[:my_data] 
+    ...
+  end
+end
+```
+
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/85x14/email_events.
+
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/circle.yml

@@ -0,0 +1,4 @@
+machine:
+  ruby:
+    version:
+      2.2.4

data/email_events.gemspec

@@ -0,0 +1,32 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'email_events/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "email_events"
+  spec.version       = EmailEvents::VERSION
+  spec.authors       = ["Kent Mewhort @ Coupa"]
+  spec.email         = ["kent.mewhort@coupa.com"]
+
+  spec.summary       = %q{Email event handling for delivery, bounces, drops, replies, etc.}
+  spec.description   = %q{Supports handling incoming events for SES/SNS or Sendgrid}
+  spec.homepage      = "https://github.com/85x14/email_events"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.required_ruby_version = '~> 2.0'
+  spec.add_dependency "gridhook"
+  spec.add_dependency "sns_endpoint"
+  spec.add_dependency "uuidtools"
+  spec.add_dependency "virtus"
+  spec.add_development_dependency "bundler"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "sqlite3", "~> 1.0"
+  spec.add_development_dependency "combustion", "~> 0.5.0"
+end

data/lib/email_events.rb

@@ -0,0 +1,46 @@
+require "email_events/version"
+require "email_events/mailer"
+require "email_events/railtie"
+
+require "email_events/models/sent_email_data"
+require "email_events/adapters/abstract/initializer"
+require "email_events/adapters/sendgrid/initializer"
+require "email_events/adapters/ses/initializer"
+require "email_events/adapters/abstract/event_data"
+require "email_events/adapters/sendgrid/event_data"
+require "email_events/adapters/ses/event_data"
+require "email_events/adapters/abstract/smtp_response"
+require "email_events/adapters/sendgrid/smtp_response"
+require "email_events/adapters/ses/smtp_response"
+
+require "email_events/services/service"
+require "email_events/services/track_data_in_header"
+require "email_events/services/retrieve_data_from_header"
+require "email_events/services/handle_event"
+require "email_events/services/parse_smtp_response_for_provider_id"
+
+module EmailEvents
+  def self.initialize
+    adapter.const_get('Initializer').initialize unless adapter.nil?
+  end
+
+  def self.adapter
+    # auto-detect the adapter unless it's already been explicitly set
+    @adapter ||= begin
+      adapter_initializer = EmailEvents::Adapters::Abstract::Initializer.descendants.find {|adapter| adapter.load_adapter?}
+      return nil if adapter_initializer.nil?
+
+      adapter_initializer.parent
+    end
+  end
+
+  def self.adapter=(adapter_module)
+    if adapter_module.is_a?(String) || adapter_module.is_a?(Symbol)
+      @adapter = "EmailEvents::Adapters::#{adapter_module.to_s.camelize}".constantize
+    else
+      @adapter = adapter_module
+    end
+  end
+end
+
+

data/lib/email_events/adapters/abstract/event_data.rb

@@ -0,0 +1,30 @@
+module EmailEvents::Adapters
+  module Abstract
+    class EventData
+      [:event_type, :event_timestamp, :recipient, :status_string, :smtp_status_code, :reason,
+       :smtp_message_id, :provider_message_id, :simplified_status, :raw_data].each do |pure_virtual_method|
+        define_method(pure_virtual_method) { raise "Not implemented" }
+      end
+
+      def simplified_status
+        # try to get a specific status based on the smtp status code; however, if the event doesn't have an smtp
+        # status code (eg. bounce events always do, but drop events only do sometimes), supply a generic one
+        return :unable_to_send_email_to_address_provided if smtp_status_code.blank?
+
+        case smtp_status_code
+        when 510, 511, 512
+          :email_address_invalid
+        when 523
+          :email_exceeds_recipients_size_limit
+        when 541
+          :email_rejected_as_spam
+        when 552
+          :recipients_inbox_is_full
+        else
+          :unknown
+        end
+      end
+    end
+  end
+end
+

data/lib/email_events/adapters/abstract/initializer.rb

@@ -0,0 +1,13 @@
+module EmailEvents::Adapters
+  module Abstract
+    class Initializer
+      def self.load_adapter?
+        raise "Not implemented"
+      end
+
+      def self.initialize
+        raise "Not implemented"
+      end
+    end
+  end
+end

data/lib/email_events/adapters/abstract/smtp_response.rb

@@ -0,0 +1,13 @@
+module EmailEvents::Adapters
+  module Abstract
+    class SmtpResponse
+      def initialize(raw_smtp_response)
+        @raw_smtp_response = raw_smtp_response
+      end
+
+      def provider_message_id
+        raise "Not implemented"
+      end
+    end
+  end
+end

data/lib/email_events/adapters/sendgrid/event_data.rb

@@ -0,0 +1,49 @@
+module EmailEvents::Adapters
+  module Sendgrid
+    class EventData < Abstract::EventData
+      def initialize(sendgrid_data)
+        @sendgrid_data = sendgrid_data
+
+        raise "Unrecognized Sendgrid event type" unless event_type.in?([:delivered, :bounce, :dropped, :deferred, :processed, :click,
+                                                                       :open, :spamreport, :group_unsubscribe, :group_resubscribe])
+      end
+
+      def event_type
+        @sendgrid_data['event'].to_sym
+      end
+
+      def event_timestamp
+        return nil if @sendgrid_data.nil?
+        Time.at @sendgrid_data['timestamp']
+      end
+
+      def recipients
+        return nil if @sendgrid_data.nil?
+        [@sendgrid_data['email']]
+      end
+
+      def smtp_status_code
+        return nil if @sendgrid_data[:status].blank?
+
+        @sendgrid_data[:status].gsub(/\./,'').to_i
+      end
+
+      def reason
+        @sendgrid_data[:reason]
+      end
+
+      def smtp_message_id
+        @sendgrid_data['smtp-id']
+      end
+
+      def provider_message_id
+        return nil if @sendgrid_data['sg_message_id'].nil?
+        @sendgrid_data['sg_message_id'].gsub(/\.filter.*/,'')
+      end
+
+      def raw_data
+        @sendgrid_data
+      end
+    end
+  end
+end

data/lib/email_events/adapters/sendgrid/initializer.rb

@@ -0,0 +1,20 @@
+require 'gridhook'
+
+module EmailEvents::Adapters
+  module Sendgrid
+    class Initializer < Abstract::Initializer
+      def self.load_adapter?
+        smtp_settings = Rails.configuration.action_mailer.smtp_settings
+        smtp_settings.present? && smtp_settings[:address].include?('sendgrid')
+      end
+
+      def self.initialize
+        Gridhook.configure do |config|
+          config.event_receive_path = '/email_events/sendgrid'
+
+          config.event_processor = EmailEvents::Service::HandleEvent
+        end
+      end
+    end
+  end
+end

data/lib/email_events/adapters/sendgrid/smtp_response.rb

@@ -0,0 +1,12 @@
+module EmailEvents::Adapters
+  module Sendgrid
+    class SmtpResponse < Abstract::SmtpResponse
+      def provider_message_id
+        # Status OK
+        return nil unless @raw_smtp_response.status == '250'
+
+        @raw_smtp_response.string.match(/queued as (.+)/)[1]
+      end
+    end
+  end
+end

data/lib/email_events/adapters/ses/event_data.rb

@@ -0,0 +1,62 @@
+module EmailEvents::Adapters
+  module Ses
+    class EventData < Abstract::EventData
+      def initialize(raw_data)
+        @sns_data = JSON.parse raw_data['Message']
+
+        raise "Unrecognized SES event type" if event_type.nil?
+      end
+
+      def event_type
+        case @sns_data['notificationType']
+        when 'Bounce'
+          :bounce
+        when 'Complaint'
+          :spamreport
+        when 'Delivery'
+          :delivered
+        else
+          nil
+        end
+      end
+
+      def event_timestamp
+        Time.parse @sns_data['mail']['timestamp']
+      end
+
+      def recipients
+        @sns_data['mail']['destination']
+      end
+
+      def smtp_status_code
+        # only supported for bounce events
+        return nil unless event_type == :bounce
+
+        status_code_str = @sns_data['bounce']['bouncedRecipients'].last['status']
+        return nil if status_code_str.nil?
+
+        status_code_str.gsub(/\./,'').to_i
+      end
+
+      def reason
+        # only supported for bounce events
+        return nil unless event_type == :bounce
+
+        @sns_data['bounce']['bounceSubType']
+      end
+
+      def smtp_message_id
+        # not supported by SNS
+        nil
+      end
+
+      def provider_message_id
+        @sns_data['mail']['messageId']
+      end
+
+      def raw_data
+        @sns_data
+      end
+    end
+  end
+end

data/lib/email_events/adapters/ses/initializer.rb

@@ -0,0 +1,32 @@
+require 'sns_endpoint'
+require 'net/http'
+
+module EmailEvents::Adapters
+  module Ses
+    class Initializer < Abstract::Initializer
+      def self.load_adapter?
+        smtp_settings = Rails.configuration.action_mailer.smtp_settings
+        smtp_settings.present? && smtp_settings[:address].include?('amazonaws.com')
+      end
+
+      def self.initialize
+        SnsEndpoint.setup do |config|
+          config.topics_list = SnsEndpointTopicListMatcher.new ['email_events']
+          config.message_proc = EmailEvents::Service::HandleEvent
+          config.subscribe_proc = Proc.new do |data|
+            # confirm the subscription
+            confirmation_endpoint = URI.parse(data['SubscribeURL'])
+            Net::HTTP.get confirmation_endpoint
+          end
+        end
+      end
+    end
+
+    class SnsEndpointTopicListMatcher < Array
+      # match any topic ending in the topic name (as opposed to the long ARN topic ID)
+      def include?(arn)
+        self.any? {|topic| arn.end_with? topic}
+      end
+    end
+  end
+end

data/lib/email_events/adapters/ses/smtp_response.rb

@@ -0,0 +1,12 @@
+module EmailEvents::Adapters
+  module Ses
+    class SmtpResponse < Abstract::SmtpResponse
+      def provider_message_id
+        # Status OK
+        return nil unless @raw_smtp_response.status == '250'
+
+        @raw_smtp_response.string.match(/Ok (.+)/)[1]
+      end
+    end
+  end
+end

data/lib/email_events/mailer.rb

@@ -0,0 +1,87 @@
+module EmailEvents
+  module Mailer
+    def self.included(base)
+      base.class_eval do
+        # whether or not to track the email and handle events for the email
+        class_attribute :event_handler
+        # additional metadata to store along the email, which we can pull up again when an event occurs (JSON format)
+        class_attribute :tracked_data_method
+
+        # an alternative class (generally, a subclass) instead of SentEmailData - eg. to perform validations on the
+        # custom tracked_metadata
+        class_attribute :sent_email_data_class
+
+        after_action :__track_data_in_header
+
+        protected
+        def self.on_event(event_handler)
+          self.event_handler = event_handler
+        end
+
+        def self.track_data(tracked_data_method, attrs = {})
+          self.tracked_data_method = tracked_data_method
+          self.sent_email_data_class = attrs[:class] if attrs.has_key? :class
+        end
+
+        def self.__track_data?
+          # track the sent email if there's either an event handler or a custom track data method
+          self.event_handler.present? || self.tracked_data_method.present?
+        end
+
+        def __track_data_in_header
+          return unless self.class.__track_data?
+
+          EmailEvents::Service::TrackDataInHeader.call(
+            mailer: self,
+            sent_email_data_class: sent_email_data_class || EmailEvents::SentEmailData,
+            data: __tracked_data
+          )
+        end
+
+        def __tracked_data
+          return nil if tracked_data_method.nil?
+
+          if tracked_data_method.is_a? Symbol
+            self.send tracked_data_method
+          else
+            tracked_data_method.call
+          end
+        end
+
+        def __handle_event(event_data, email_data)
+          return if event_handler.nil?
+
+          if event_handler.is_a? Symbol
+            self.send event_handler, event_data, email_data
+          else
+            event_handler.call event_data, email_data
+          end
+        end
+
+        # pry into the deliver_mail method so as to intercept the SMTP response and
+        # parse out the provider message id
+        singleton_class.send(:alias_method, :base_deliver_mail, :deliver_mail)
+        def self.deliver_mail(message, &block)
+          response = base_deliver_mail(message, &block)
+
+          # no provider id to parse if no adapter has been set, or not tracking for this mailer
+          return response if EmailEvents.adapter.nil? || !self.__track_data?
+
+          # response won't be the smtp result unless the return_response setting is flagged on
+          # (but allow it for TestMailer in test environments)
+          unless (!Rails.configuration.action_mailer.smtp_settings.nil? && Rails.configuration.action_mailer.smtp_settings[:return_response]) ||
+                 Rails.env.test?
+            raise 'Email events are enabled for this mailer, but you haven\'t turned on return_response = true in your smtp settings'
+          end
+
+          EmailEvents::Service::ParseSmtpResponseForProviderId.call(
+            mail_message: message,
+            raw_response: response,
+            sent_email_data_class: sent_email_data_class || EmailEvents::SentEmailData,
+          )
+          response
+        end
+      end
+    end
+  end
+end

data/lib/email_events/models/sent_email_data.rb

@@ -0,0 +1,21 @@
+require 'active_record'
+
+# == Schema Information
+#
+# Table name: sent_email_data
+#
+#  id            :integer          not null, primary key
+#  uuid          :string
+#  mailer_class  :string
+#  mailer_action :string           not null
+#  to            :string           not null
+#  data          :text
+#  created_at    :datetime
+#  provider_message_id :string
+
+module EmailEvents
+  class SentEmailData < ActiveRecord::Base
+    self.table_name = "sent_email_data"
+    serialize :data
+  end
+end

data/lib/email_events/railtie.rb

@@ -0,0 +1,19 @@
+require 'rails'
+
+module EmailEvents
+  class Railtie < Rails::Railtie
+    initializer 'email_events.initialize', after: :load_config_initializers do
+      ActiveSupport.on_load(:action_mailer) do
+        include EmailEvents::Mailer
+      end
+
+      # Gridhook gets upset when it draws its routes if we haven't setup the event receive path, so always do so here immediately
+      # (even when sendgrid is not used)
+      # TODO: especially if there ever gets to be > 2 adapters, each adapters should ideally be broken out into its own gem
+      Gridhook.config.event_receive_path = '/email_events/null'
+      Gridhook.config.event_processor = Proc.new { raise 'Sendgrid adapter not loaded' }
+
+      EmailEvents.initialize
+    end
+  end
+end

data/lib/email_events/services/handle_event.rb

@@ -0,0 +1,31 @@
+class EmailEvents::Service::HandleEvent < EmailEvents::Service
+  def initialize(raw_response)
+    @raw_response = raw_response
+  end
+
+  def call
+    sent_emails = EmailEvents::Service::RetrieveDataFromHeader.call(event_data: event_data)
+    return if sent_emails.blank?
+
+    # in occasional cases (when there's no UUID), there will be multiple sent_emails that match the event: we
+    # apply the event handling to each one
+    sent_emails.each do |email_data|
+      begin
+        mailer = email_data.mailer_class.constantize.send :new
+        mailer.send :__handle_event, event_data, email_data
+      end
+    end
+
+    # no data to output back to Rack
+    nil
+  end
+
+  private
+  def event_data
+    @event_data ||= event_data_adapter_class.new(@raw_response)
+  end
+
+  def event_data_adapter_class
+    EmailEvents.adapter.const_get('EventData')
+  end
+end

data/lib/email_events/services/parse_smtp_response_for_provider_id.rb

@@ -0,0 +1,29 @@
+class EmailEvents::Service::ParseSmtpResponseForProviderId < EmailEvents::Service
+  include Virtus.model
+  attribute :mail_message
+  attribute :raw_response
+  attribute :sent_email_data_class
+
+  def call
+    # parse the response using the applicable SmtpResponse adapter
+    provider_id = parsed_response.provider_message_id
+    return if provider_id.nil?
+
+    # find our SentEmailData from our own UUID and store the provider id
+    sent_email_data = sent_email_data_class.find_by_uuid(message_uuid)
+    sent_email_data.update_attribute(:provider_message_id, provider_id)
+  end
+
+  private
+  def response_class
+    EmailEvents.adapter.const_get('SmtpResponse')
+  end
+
+  def parsed_response
+    @parsed_response = response_class.new(raw_response)
+  end
+
+  def message_uuid
+    mail_message.message_id.match(/(.+)\@uuid/)[1]
+  end
+end

data/lib/email_events/services/retrieve_data_from_header.rb

@@ -0,0 +1,52 @@
+require 'virtus'
+
+class EmailEvents::Service::RetrieveDataFromHeader < EmailEvents::Service
+  include Virtus.model
+  attribute :event_data, EmailEvents::Adapters::Abstract::EventData
+
+  def call
+    # try to find the SentEmailData by the following methods, listed in order of preference:
+    # 1) the Message-ID (in which we stored our own SentEmailData id in the first place);
+    # 2) the provider_message_id which Sendgrid or SES uses to track emails;
+    # 3) recipient email addresses to which we recently sent out emails
+
+    unless uuid_from_smtp_message_id.blank?
+      sent_email = EmailEvents::SentEmailData.find_by_uuid!(uuid_from_smtp_message_id)
+
+      # if this event gives us our Message-ID and Sendgrid's sg_message_id, we take the opportunity to store
+      # the latter, as other events (foremost, "open" events) don't necessarily provide us with the Message-ID again
+      if sent_email.provider_message_id.blank? && !self.event_data.provider_message_id.blank?
+        sent_email.update_attribute(:provider_message_id, self.event_data.provider_message_id)
+      end
+
+      # the UUID is always associated with just one original message
+      return [sent_email]
+    end
+
+    unless self.event_data.provider_message_id.blank?
+      sent_email = EmailEvents::SentEmailData.where(provider_message_id: self.event_data.provider_message_id).first
+      return [sent_email] unless sent_email.nil?
+    end
+
+    # if the destination mail server has clobbered our tracking data in the message_id, still try to determine
+    # the sent email data based on the sender's email address and any emails sent to it in the last 15 minutes.
+    # We only do this for bounces and drops, as it's safe to assume that a bounce and drop event should apply
+    # to ALL outstanding sent emails -- as opposed to eg. click and open events which are tightly associated with one
+    # sent email)
+    if self.event_data.event_type.in?([:bounce, :dropped])
+      return EmailEvents::SentEmailData.where('created_at > ? AND "to" = ?', self.event_data.event_timestamp-15.minutes, self.event_data.recipients.first)
+    end
+
+    []
+  end
+
+  private
+  def uuid_from_smtp_message_id
+    @uuid ||= begin
+      unless self.event_data.smtp_message_id.blank?
+        matching_data = self.event_data.smtp_message_id.match(/([^\<]+)\@uuid/)
+        matching_data.nil? ? nil : matching_data[1]
+      end
+    end
+  end
+end

data/lib/email_events/services/service.rb

@@ -0,0 +1,10 @@
+# use a Service Objects architecture
+class EmailEvents::Service
+  def self.call(*args, &block)
+    if block_given?
+      new(*args).call(&block)
+    else
+      new(*args).call
+    end
+  end
+end

data/lib/email_events/services/track_data_in_header.rb

@@ -0,0 +1,49 @@
+require 'virtus'
+require 'uuidtools'
+
+class EmailEvents::Service::TrackDataInHeader < EmailEvents::Service
+  include Virtus.model
+  attribute :mailer
+  attribute :sent_email_data_class
+  attribute :data
+
+  def call
+    # a UUID is much more secure identifier to send along in an email header (as opposed to the db primary key,
+    # for which someone could easily guess a valid integer in an attack)
+    uuid = generate_uuid
+
+    data_obj = sent_email_data_class.create!(
+      mailer_class: mailer_class,
+      mailer_action: mailer_action,
+      to: recipient_email,
+      uuid: uuid,
+      data: data
+    )
+
+    # add the uuid to of the SentEmailData to the email Message-ID header for tracking it
+    add_data_uuid_to_email_headers(uuid)
+
+    data_obj
+  end
+
+  private
+  def mailer_class
+    mailer.class.to_s
+  end
+
+  def mailer_action
+    mailer.action_name
+  end
+
+  def recipient_email
+    mailer.headers.to.first
+  end
+
+  def generate_uuid
+    UUIDTools::UUID.random_create.to_s.gsub(/\-/,'')
+  end
+
+  def add_data_uuid_to_email_headers(content)
+    mailer.headers["Message-ID"] = "<#{content}@uuid.email_events>"
+  end
+end

data/lib/email_events/version.rb

@@ -0,0 +1,3 @@
+module EmailEvents
+  VERSION = "1.0"
+end

data/lib/generators/email_events/install_generator.rb

@@ -0,0 +1,18 @@
+require "rails/generators/active_record"
+
+module EmailEvents
+  class InstallGenerator < ::Rails::Generators::Base
+    include ::Rails::Generators::Migration
+    desc "Generates migration for email_events"
+
+    source_paths << File.join(File.dirname(__FILE__), "templates")
+
+    def create_migration_file
+      migration_template "create_sent_email_data.rb", "db/migrate/create_sent_email_data.rb"
+    end
+
+    def self.next_migration_number(dirname)
+      ::ActiveRecord::Generators::Base.next_migration_number(dirname)
+    end
+  end
+end

data/lib/generators/email_events/templates/create_sent_email_data.rb

@@ -0,0 +1,13 @@
+class CreateSentEmailData < ActiveRecord::Migration
+   def change
+     create_table :sent_email_data do |t|
+      t.string :uuid, unique: true
+      t.string :provider_message_id, :string
+      t.string :mailer_class, null: false
+      t.string :mailer_action,  null: false
+      t.string :to, null: false
+      t.text :data
+      t.datetime :created_at
+    end
+  end
+end

metadata

@@ -0,0 +1,199 @@
+--- !ruby/object:Gem::Specification
+name: email_events
+version: !ruby/object:Gem::Version
+  version: '1.0'
+platform: ruby
+authors:
+- Kent Mewhort @ Coupa
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2016-04-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: gridhook
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sns_endpoint
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: uuidtools
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: virtus
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  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'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: combustion
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.5.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.5.0
+description: Supports handling incoming events for SES/SNS or Sendgrid
+email:
+- kent.mewhort@coupa.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- circle.yml
+- email_events.gemspec
+- lib/email_events.rb
+- lib/email_events/adapters/abstract/event_data.rb
+- lib/email_events/adapters/abstract/initializer.rb
+- lib/email_events/adapters/abstract/smtp_response.rb
+- lib/email_events/adapters/sendgrid/event_data.rb
+- lib/email_events/adapters/sendgrid/initializer.rb
+- lib/email_events/adapters/sendgrid/smtp_response.rb
+- lib/email_events/adapters/ses/event_data.rb
+- lib/email_events/adapters/ses/initializer.rb
+- lib/email_events/adapters/ses/smtp_response.rb
+- lib/email_events/mailer.rb
+- lib/email_events/models/sent_email_data.rb
+- lib/email_events/railtie.rb
+- lib/email_events/services/handle_event.rb
+- lib/email_events/services/parse_smtp_response_for_provider_id.rb
+- lib/email_events/services/retrieve_data_from_header.rb
+- lib/email_events/services/service.rb
+- lib/email_events/services/track_data_in_header.rb
+- lib/email_events/version.rb
+- lib/generators/email_events/install_generator.rb
+- lib/generators/email_events/templates/create_sent_email_data.rb
+homepage: https://github.com/85x14/email_events
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - "~>"
+    - !ruby/object:Gem::Version
+      version: '2.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.5.1
+signing_key: 
+specification_version: 4
+summary: Email event handling for delivery, bounces, drops, replies, etc.
+test_files: []