emaildirect 1.0.0

data/.gitignore

@@ -0,0 +1,5 @@
+.DS_Store
+rdoc
+pkg
+*.gem
+example.rb

data/Gemfile

@@ -0,0 +1,3 @@
+source "http://rubygems.org"
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,24 @@
+PATH
+  remote: .
+  specs:
+    emaildirect (1.0.0)
+      hashie
+      httparty
+      json
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    hashie (1.2.0)
+    httparty (0.8.1)
+      multi_json
+      multi_xml
+    json (1.5.3)
+    multi_json (1.0.4)
+    multi_xml (0.4.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  emaildirect!

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2011 Jason Rust
+
+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,83 @@
+# emaildirect
+
+A ruby library which implements the complete functionality of the REST (v5) [Email Direct API](https://docs.emaildirect.com).
+
+## Installation
+
+### Plain ruby
+    gem install emaildirect
+    require 'emaildirect'
+    EmailDirect.api_key 'your_api_key'
+
+### Rails integration
+In your gemfile:
+
+    gem 'emaildirect'
+
+In an initializer:
+
+    EmailDirect.api_key 'your_api_key'
+
+## Examples
+
+### Retrieve a list of all your publications.
+
+    EmailDirect::Publication.all.Publications.each do |pub|
+      puts "#{pub.PublicationID}: #{pub.Name}"
+    end
+
+Results in:
+    
+    1: Publication One
+    2: Publication Two
+
+### Create, then remove a Publication
+
+    response = EmailDirect::Publication.create('Test', :Description => 'Test Publication')
+    sub = EmailDirect::Publication.new(response.publicationID)
+    sub.delete
+
+### ActionMailer integration
+You can use send your ActionMailer email through Email Direct using their Relay Send functionality by setting up a new delivery method in an initalizer:
+
+     ActionMailer::Base.add_delivery_method :emaildirect, EmailDirect::Mailer,
+                                            :category_id => 1,
+                                            :options   => { :Force => true }
+
+And in your ActionMailer class:
+
+    defaults :delivery_method => :emaildirect
+
+or for just a particular message:
+
+    def welcome(user) do
+      mail :to => user.email,
+           :delivery_method => :emaildirect
+    end
+
+### Handling errors
+If the emaildirect API returns an error, an exception will be thrown. For example, if you attempt to create a subscriber with an invalid email address:
+
+    begin
+      response = EmailDirect::Subscriber.create('bademail')
+      rescue EmailDirect::BadRequest => br
+        puts "Bad request error: #{br}"
+        puts "Error Code:    #{br.data.ErrorCode}"
+        puts "Error Message: #{br.data.Message}"
+      rescue Exception => e
+        puts "Error: #{e}"
+    end
+
+Results in:
+
+    Bad request error: The EmailDirect API responded with the following error - 101: Invalid Email Address
+    Error Code:    101
+    Error Message: Invalid Email Address
+
+### Expected input and output
+The best way of finding out the expected input and output of a particular method in a particular class is to read the [API docs](https://docs.emaildirect.com)
+and take a look at the code for that function.
+
+## Credits
+- Jason Rust
+- [createsend-ruby](https://github.com/campaignmonitor/createsend-ruby) library for inspiration on how to write a decent REST API wrapper.

data/Rakefile

@@ -0,0 +1,23 @@
+$LOAD_PATH.unshift File.expand_path("../lib", __FILE__)
+require "bundler/version"
+require "shoulda/tasks"
+require "rake/testtask"
+require "./lib/emaildirect"
+
+Rake::TestTask.new(:test) do |test|
+  test.ruby_opts = ["-rubygems"] if defined? Gem
+  test.libs << "lib" << "test"
+  test.pattern = "test/**/*_test.rb"
+end
+
+desc "Build the gem"
+task :build do
+  system "gem build emaildirect.gemspec"
+end
+
+desc "Build and release the gem"
+task :release => :build do
+  system "gem push emaildirect-#{CreateSend::VERSION}.gem"
+end
+
+task :default => :test

data/emaildirect.gemspec

@@ -0,0 +1,23 @@
+require 'bundler'
+require 'bundler/version'
+
+require File.expand_path('lib/emaildirect/version')
+
+Gem::Specification.new do |s|
+  s.add_runtime_dependency('json')
+  s.add_runtime_dependency('hashie')
+  s.add_runtime_dependency('httparty')
+  s.name = "emaildirect"
+  s.author = "Jason Rust"
+  s.description = %q{Implements the complete functionality of the email direct REST API.}
+  s.email = ["rustyparts@gmail.com"]
+  s.executables = `git ls-files -- bin/*`.split("\n").map{|f| File.basename(f)}
+  s.files = `git ls-files`.split("\n")
+  s.homepage = "http://github.com/jrust/emaildirect/"
+  s.require_paths = ["lib"]
+  s.summary = %q{A library which implements the complete functionality of of the emaildirect REST API (v5).}
+  s.test_files = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.version = EmailDirect::VERSION
+  s.platform = Gem::Platform::RUBY
+  s.required_rubygems_version = Gem::Requirement.new('>= 1.3.6') if s.respond_to? :required_rubygems_version=
+end

data/lib/emaildirect.rb

@@ -0,0 +1,104 @@
+require 'cgi'
+require 'uri'
+require 'httparty'
+require 'hashie'
+Hash.send :include, Hashie::HashExtensions
+
+libdir = File.dirname(__FILE__)
+$LOAD_PATH.unshift(libdir) unless $LOAD_PATH.include?(libdir)
+
+require 'emaildirect/version'
+require 'emaildirect/mailer'
+require 'emaildirect/campaign'
+require 'emaildirect/creative'
+require 'emaildirect/creative_folder'
+require 'emaildirect/database'
+require 'emaildirect/filter'
+require 'emaildirect/image_folder'
+require 'emaildirect/image_file'
+require 'emaildirect/import'
+require 'emaildirect/list'
+require 'emaildirect/relay_send'
+require 'emaildirect/short_url'
+require 'emaildirect/publication'
+require 'emaildirect/source'
+require 'emaildirect/subscriber'
+require 'emaildirect/suppression_list'
+require 'emaildirect/workflow'
+
+module EmailDirect
+  # Just allows callers to do EmailDirect.api_key "..." rather than EmailDirect::EmailDirect.api_key "..." etc
+  class << self
+    def api_key(api_key=nil)
+      r = EmailDirect.api_key api_key
+    end
+    
+    def base_uri(uri)
+      r = EmailDirect.base_uri uri
+    end
+  end
+
+  # Represents a EmailDirect API error and contains specific data about the error.
+  class EmailDirectError < StandardError
+    attr_reader :data, :code
+    def initialize(data)
+      @data = data
+      super "The EmailDirect API responded with the following error - #{@data.ErrorCode}: #{@data.Message}"
+    end
+  end
+
+  class ClientError < StandardError; end
+  class ServerError < StandardError; end
+  class BadRequest < EmailDirectError; end
+  class Unauthorized < StandardError; end
+  class NotFound < ClientError; end
+  class Unavailable < StandardError; end
+
+  class EmailDirect
+    include HTTParty
+    
+    @@base_uri = "https://rest.emaildirect.com/v1/"
+    @@api_key = ""
+    headers({ 
+      'User-Agent' => "emaildirect-rest-#{VERSION}",
+      'Content-Type' => 'application/json; charset=utf-8',
+      'Accept-Encoding' => 'gzip, deflate' })
+    base_uri @@base_uri
+    basic_auth 'x', @@api_key
+
+    # Sets the API key which will be used to make calls to the EmailDirect API.
+    def self.api_key(api_key=nil)
+      return @@api_key unless api_key
+      @@api_key = api_key
+      basic_auth 'x', @@api_key
+    end
+
+    # This call returns an object reflecting the current permissions allowed for the provided API Key
+    def ping
+      response = EmailDirect.get('/Ping')
+      Hashie::Mash.new(response)
+    end
+
+    def self.get(*args); handle_response super end
+    def self.post(*args); handle_response super end
+    def self.put(*args); handle_response super end
+    def self.delete(*args); handle_response super end
+
+    def self.handle_response(response) # :nodoc:
+      case response.code
+      when 400
+        raise BadRequest.new(Hashie::Mash.new response)
+      when 401
+        raise Unauthorized.new
+      when 404
+        raise NotFound.new
+      when 400...500
+        raise ClientError.new response.parsed_response
+      when 500...600
+        raise ServerError.new
+      else
+        response
+      end
+    end
+  end
+end

data/lib/emaildirect/campaign.rb

@@ -0,0 +1,135 @@
+require 'emaildirect'
+require 'json'
+
+module EmailDirect
+  # Represents a campaign and associated functionality
+  class Campaign
+    class << self
+      def active(options = {})
+        response = EmailDirect.get '/Campaigns', :query => options
+        Hashie::Mash.new(response)
+      end
+
+      def drafts(options = {})
+        response = EmailDirect.get '/Campaigns/Drafts', :query => options
+        Hashie::Mash.new(response)
+      end
+
+      def sent(options = {})
+        response = EmailDirect.get '/Campaigns/Sent', :query => options
+        Hashie::Mash.new(response)
+      end
+
+      def sending(options = {})
+        response = EmailDirect.get '/Campaigns/Sending', :query => options
+        Hashie::Mash.new(response)
+      end
+
+      def scheduled(options = {})
+        response = EmailDirect.get '/Campaigns/Scheduled', :query => options
+        Hashie::Mash.new(response)
+      end
+
+      def all(options = {})
+        response = EmailDirect.get '/Campaigns/All', :query => options
+        Hashie::Mash.new(response)
+      end
+
+      def create(name, creative_id, subject, from_name, publication_id, options = {})
+        options.merge! :Name => name, :CreativeID => creative_id, :Subject => subject, :FromName => from_name, :PublicationID => publication_id
+        response = EmailDirect.post '/Campaigns', :body => options.to_json
+        Hashie::Mash.new(response)
+      end
+    end
+
+    attr_reader :campaign_id
+
+    def initialize(campaign_id)
+      @campaign_id = campaign_id
+    end
+
+    def details
+      response = get
+      Hashie::Mash.new(response)
+    end
+
+    def message
+      response = get 'Email'
+      Hashie::Mash.new(response)
+    end
+
+    def links
+      response = get 'Links'
+      Hashie::Mash.new(response)
+    end
+
+    def recipients(options = {})
+      response = get 'Recipients', options
+      Hashie::Mash.new(response)
+    end
+
+    def opens(options = {})
+      response = get 'Opens', options
+      Hashie::Mash.new(response)
+    end
+
+    def clicks(options = {})
+      response = get 'Clicks', options
+      Hashie::Mash.new(response)
+    end
+
+    def removes(options = {})
+      response = get 'Removes', options
+      Hashie::Mash.new(response)
+    end
+
+    def complaints(options = {})
+      response = get 'Complaints', options
+      Hashie::Mash.new(response)
+    end
+
+    def soft_bounces(options = {})
+      response = get 'SoftBounces', options
+      Hashie::Mash.new(response)
+    end
+
+    def hard_bounces(options = {})
+      response = get 'HardBounces', options
+      Hashie::Mash.new(response)
+    end
+
+    def update(name, creative_id, subject, from_name, publication_id, options = {})
+      options.merge! :Name => name, :CreativeID => creative_id, :Subject => subject, :FromName => from_name, :PublicationID => publication_id
+      response = EmailDirect.put uri_for, :body => options.to_json
+      Hashie::Mash.new(response)
+    end
+
+    def schedule(schedule_date)
+      options = { :CampaignID => campaign_id, :ScheduleDate => schedule_date.strftime('%FT%TZ') }
+      response = EmailDirect.post '/Campaigns/Schedule', :body => options.to_json
+      Hashie::Mash.new(response)
+    end
+
+    def cancel
+      response = EmailDirect.post '/Campaigns/Cancel', :body => campaign_id.to_json
+      Hashie::Mash.new(response)
+    end
+
+    def delete
+      response = EmailDirect.delete uri_for, {}
+      Hashie::Mash.new(response)
+    end
+
+    private
+
+    def get(action = nil, options = {})
+      EmailDirect.get uri_for(action), :query => options
+    end
+
+    def uri_for(action = nil)
+      action = "/#{action}" if action
+      "/Campaigns/#{campaign_id}#{action}"
+    end
+  end
+end
+

data/lib/emaildirect/creative.rb

@@ -0,0 +1,54 @@
+require 'emaildirect'
+require 'json'
+
+module EmailDirect
+  # Represents a creative and associated functionality
+  class Creative
+    class << self
+      def all(options = {})
+        response = EmailDirect.get '/Creatives', :query => options
+        Hashie::Mash.new(response)
+      end
+
+      def create(name, options = {})
+        options.merge! :Name => name
+        response = EmailDirect.post '/Creatives', :body => options.to_json
+        Hashie::Mash.new(response)
+      end
+    end
+
+    attr_reader :creative_id
+
+    def initialize(creative_id)
+      @creative_id = creative_id
+    end
+
+    def details
+      response = get
+      Hashie::Mash.new(response)
+    end
+
+    def update(name, options)
+      options.merge! :Name => name
+      response = EmailDirect.put uri_for, :body => options.to_json
+      Hashie::Mash.new(response)
+    end
+
+    def delete
+      response = EmailDirect.delete uri_for, {}
+      Hashie::Mash.new(response)
+    end
+
+    private
+
+    def get(action = nil)
+      EmailDirect.get uri_for(action)
+    end
+
+    def uri_for(action = nil)
+      action = "/#{action}" if action
+      "/Creatives/#{creative_id}#{action}"
+    end
+  end
+end
+