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:

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

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.
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

Login to your SendGrid account and navigate to "Mail Settings" -> Event Notification.
Turn the module "On".
Set the HTTP POST URL to https:///email_events/sendgrid
Under "Select Actions", choose the event types for which you would like to receive triggers.

That's it!

AWS SES / SNS

Login to the AWS Management Console.
Open up the AWS SNS console.
Click "Create Topic". Set both the the "Topic name" to "email_events" and the "Display name" to "emails". Click "Create topic".
In the "Topic Details", click "Create Subscription". Set the endpoint to https:///email_events/ses.
With your Rails server running, click "Request confirmations" to confirm the subscription at your endpoint.
Open up the AWS SES console.
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.
Click Edit Configuration and set the SNS Topic to "email_events" for Bounces, Complaints, and/or Deliveries.
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.

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.

85x14 / email_events