sespool 0.1.0

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2013 YOURNAME
+
+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,36 @@
+# Sespool [![Build Status](https://travis-ci.org/ags/sespool.png?branch=master)](https://travis-ci.org/ags/sespool)
+
+Bounce parser for Amazon SES SNS notifications. Currently only supports JSON.
+
+## Usage
+
+```ruby
+>> bounce = Sespool::Bounce.new("raw sns json request body")
+>> bounce.type
+=> 'Transient'
+>> bounce.bounced_recipients.first.email_address
+=> 'foo@example.com'
+>> bounce.mail.message_id
+=> '123-456-789'
+```
+
+## Example Integration
+
+In a Rails app, you might want to setup your SES SNS bounces be be handled
+by something like the following:
+
+```ruby
+class SnsController < ApplicationController
+
+  def bounce_notification
+    # parse the SNS bounce JSON
+    bounce = Sespool::Bounce.new(request.raw_post)
+
+    # do something with it, probably persist it
+    EmailBounce.create_from_sns_message(bounce)
+
+    render nothing: true, status: 204
+  end
+
+end
+```

data/Rakefile

@@ -0,0 +1,9 @@
+#!/usr/bin/env rake
+require 'rubygems'
+require 'bundler/setup'
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/sespool.rb

@@ -0,0 +1,4 @@
+require_relative 'sespool/bounce'
+
+module Sespool
+end

data/lib/sespool/bounce.rb

@@ -0,0 +1,63 @@
+require 'json'
+require 'time'
+
+module Sespool
+  class Bounce
+
+    def initialize(raw_data)
+      message = JSON.parse(JSON.parse(raw_data).fetch('Message'))
+      @_mail_data = message.fetch('mail')
+      @_bounce_data = message.fetch('bounce')
+    end
+
+    def type
+      @_bounce_data.fetch('bounceType')
+    end
+
+    def sub_type
+      @_bounce_data.fetch('bounceSubType')
+    end
+
+    def reporting_mta
+      @_bounce_data.fetch('reportingMTA')
+    end
+
+    def feedback_id
+      @_bounce_data.fetch('feedbackId')
+    end
+
+    def timestamp
+      Time.parse(@_bounce_data.fetch('timestamp'))
+    end
+
+    def bounced_recipients
+      @_bounced_recipients ||= @_bounce_data.fetch('bouncedRecipients').map { |recipient|
+        Recipient.new(
+          recipient.fetch('emailAddress'),
+          recipient.fetch('status'),
+          recipient.fetch('diagnosticCode'),
+          recipient.fetch('action')
+        )
+      }
+    end
+
+    def mail
+      @_mail ||= Mail.new(
+        @_mail_data.fetch('timestamp'),
+        @_mail_data.fetch('source'),
+        @_mail_data.fetch('messageId'),
+        @_mail_data.fetch('destination')
+      )
+    end
+
+    class Recipient < Struct.new(:email_address, :status, :diagnostic_code, :action)
+    end
+
+    class Mail < Struct.new(:raw_timestamp, :source, :message_id, :destination)
+      def timestamp
+        Time.parse(raw_timestamp)
+      end
+    end
+
+  end
+end

data/lib/sespool/version.rb

@@ -0,0 +1,3 @@
+module Sespool
+  VERSION = '0.1.0'
+end

data/spec/fixtures/fixture_a.json

@@ -0,0 +1,11 @@
+{
+  "Type" : "Notification",
+  "MessageId" : "1a509979-dede-56ab-9jbf-d36983a66cba",
+  "TopicArn" : "arn:aws:sns:us-east-1:535280530538:email_bounces",
+  "Message" : "{\"notificationType\":\"Bounce\",\"bounce\":{\"bounceSubType\":\"General\",\"bounceType\":\"Transient\",\"reportingMTA\":\"dsn; aws-ses-mta-svc-iad-1a-i-e6e8e98c.us-east-1.amazon.com\",\"bouncedRecipients\":[{\"emailAddress\":\"foo@example.com\",\"status\":\"4.4.7\",\"diagnosticCode\":\"smtp; 550 4.4.7 Message expired: unable to deliver in 840 minutes.<421 4.4.0 Unable to lookup DNS for example.com>\",\"action\":\"failed\"}],\"timestamp\":\"2013-05-17T16:26:31.000Z\",\"feedbackId\":\"0000013eb3506972-88979901-bf0e-31e4-b280-c390f3ef4cd7-000000\"},\"mail\":{\"timestamp\":\"2013-05-17T02:02:43.000Z\",\"source\":\"The sender <sender@example.com>\",\"messageId\":\"0000013eb0399348-00ca18d9-5995-4898-17a6-26f5ea0dbea3-000000\",\"destination\":[\"foo@example.com\",\"bar@example.com\"]}}",
+  "Timestamp" : "2013-05-17T16:26:32.155Z",
+  "SignatureVersion" : "1",
+  "Signature" : "qZl8NLEsr6R0g60V3D8WfWOcJmSahLAwHAIMaPgjBQMBuDmQB8mfaKrHTjnA4UWYVePc2xUfP3R1lmIPNQJ5Ug/qRZivrcumJkuMkOk3+KKFwD0hduTltQ8XhMgXFhLGC7qQ6XM3mKilrYvukz8Erk6E4JXOQEtCG0sp18R1g4M=",
+  "SigningCertURL" : "https://sns.us-east-1.amazonaws.com/SimpleNotificationService-f3ecfb7224c7233fe72b5f29f86de52f.pem",
+  "UnsubscribeURL" : "https://sns.us-east-1.amazonaws.com/?Action=Unsubscribe&SubscriptionArn=arn:aws:sns:us-east-1:545230530538:email_bounces:72f38fee-9106-4423-9fd8-b93631723137"
+}

data/spec/lib/sespool/bounce_spec.rb

@@ -0,0 +1,108 @@
+require './lib/sespool'
+
+def load_fixture(name)
+  File.open('./spec/fixtures/' + name).read
+end
+
+describe Sespool::Bounce do
+  let(:fixture) { load_fixture('fixture_a.json') }
+  subject(:bounce) { Sespool::Bounce.new(fixture) }
+
+  describe "#type" do
+    it "returns the bounce type" do
+      expect(bounce.type).to eq('Transient')
+    end
+  end
+
+  describe "#sub_type" do
+    it "returns the bounce sub type" do
+      expect(bounce.sub_type).to eq('General')
+    end
+  end
+
+  describe "#reporting_mta" do
+    it "returns the bounce reporting MTA" do
+      expect(bounce.reporting_mta).to \
+        eq('dsn; aws-ses-mta-svc-iad-1a-i-e6e8e98c.us-east-1.amazon.com')
+    end
+  end
+
+  describe "#timestamp" do
+    it "returns the bounce timestamp" do
+      expect(bounce.timestamp).to eq(Time.parse('2013-05-17T16:26:31.000Z'))
+    end
+  end
+
+  describe "#feedback_id" do
+    it "returns the bounce feedback id" do
+      expect(bounce.feedback_id).to \
+        eq('0000013eb3506972-88979901-bf0e-31e4-b280-c390f3ef4cd7-000000')
+    end
+  end
+
+  describe "#bounced_recipients" do
+    it "returns a list of bounced recipients" do
+      expect(bounce.bounced_recipients.size).to eq(1)
+    end
+
+    describe "Bounce::Recipient" do
+      subject(:recipient) { bounce.bounced_recipients.first }
+
+      describe "#email_address" do
+        it "returns the recipient email address" do
+          expect(recipient.email_address).to eq('foo@example.com')
+        end
+      end
+
+      describe "#status" do
+        it "returns the recipient status" do
+          expect(recipient.status).to eq('4.4.7')
+        end
+      end
+
+      describe "#diagnostic_code" do
+        it "returns the recipient diagnostic code" do
+          expect(recipient.diagnostic_code).to eq(
+            'smtp; 550 4.4.7 Message expired: unable to deliver in 840 minutes.'\
+            '<421 4.4.0 Unable to lookup DNS for example.com>',
+          )
+        end
+      end
+
+      describe "#action" do
+        it "returns the recipient action" do
+          expect(recipient.action).to eq('failed')
+        end
+      end
+    end
+  end
+
+  describe "#mail" do
+    describe "#timestamp" do
+      it "returns the mail timestamp" do
+        expect(bounce.mail.timestamp).to \
+          eq(Time.parse('2013-05-17T02:02:43.000Z'))
+      end
+    end
+
+    describe "#source" do
+      it "returns the sender" do
+        expect(bounce.mail.source).to eq('The sender <sender@example.com>')
+      end
+    end
+
+    describe "#message_id" do
+      it "returns the message ID" do
+        expect(bounce.mail.message_id).to \
+          eq('0000013eb0399348-00ca18d9-5995-4898-17a6-26f5ea0dbea3-000000')
+      end
+    end
+
+    describe "#destination" do
+      it "returns a list of intended recipients" do
+        expect(bounce.mail.destination).to \
+          eq(['foo@example.com', 'bar@example.com'])
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,105 @@
+--- !ruby/object:Gem::Specification
+name: sespool
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Alex Smith
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-05-30 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Bounce parser for Amazon SES SNS notifications
+email:
+- alex@thatalexguy.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/sespool/bounce.rb
+- lib/sespool/version.rb
+- lib/sespool.rb
+- MIT-LICENSE
+- Rakefile
+- README.md
+- spec/fixtures/fixture_a.json
+- spec/lib/sespool/bounce_spec.rb
+homepage: https://github.com/ags/sespool
+licenses:
+- MIT
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: Bounce parser for Amazon SES SNS notifications
+test_files:
+- spec/fixtures/fixture_a.json
+- spec/lib/sespool/bounce_spec.rb
+has_rdoc: