dotmailer 0.0.1 → 0.0.2

data/README.md

@@ -21,31 +21,182 @@ To install as part of a project managed by bundler, add to your Gemfile:
 Usage
 -----
 
-Use the `Dotmailer::Client` class to access the dotMailer REST API.
+Interaction with the dotMailer API is done via a `DotMailer::Account` object, which is initialized with an API username and password:
 
-You must initialize the Client with an API user and password (see [here](http://www.dotmailer.co.uk/api/more_about_api/getting_started_with_the_api.aspx) for instructions on obtaining these):
+    account = DotMailer::Account.new('your-api-username', 'your-api-password')
 
-    client = Dotmailer::Client.new('your-api-username', 'your-api-password')
+All interaction via this object will be for the dotMailer account associated with the API credentials.
+
+For instructions on how to obtain your API username and password, see [here](http://www.dotmailer.co.uk/api/more_about_api/getting_started_with_the_api.aspx).
 
 Data Fields
 -----------
 
 ### List
 
-`Dotmailer::Client#get_data_fields` will return an Array of `Dotmailer::DataField` objects representing the data fields for the global address book:
+`DotMailer::Account#data_fields` will return an Array of `DotMailer::DataField` objects representing the data fields for the account's global address book:
+
+    account = DotMailer::Account.new('your-api-username', 'your-api-password')
 
-    client.get_data_fields
+    account.data_fields
     => [
-         Dotmailer::DataField name: "FIELD1", type: "String", visibility: "Public", default: "",
-         Dotmailer::DataField name: "FIELD2", type: "Numeric", visibility: "Private", default: 0
+         DotMailer::DataField name: "FIELD1", type: "String", visibility: "Public", default: "",
+         DotMailer::DataField name: "FIELD2", type: "Numeric", visibility: "Private", default: 0
        ]
 
+NOTE: The returned data fields are cached in memory for `DotMailer::Account::CACHE_LIFETIME` seconds to avoid unnecessarily hitting the API.
+
 ### Create
 
-`Dotmailer::Client#create_data_field` will attempt to create a new data field. On success it returns true, on failure it raises an exception:
+`DotMailer::Account#create_data_field` will attempt to create a new data field. On failure it raises an exception:
+
+    account = DotMailer::Account.new('your-api-username', 'your-api-password')
+
+    account.create_data_field 'FIELD3', :type => 'String'
+
+    account.create_data_field 'FIELD3', :type => 'String'
+    => DotMailer::InvalidRequest: Field already exists. ERROR_NON_UNIQUE_DATAFIELD
+
+NOTE: successfully creating a data field via this method will invalidate any cached data fields.
+
+Contacts
+--------
+
+### Finding A Contact
+
+There are two ways to find contacts via the API, using a contact's email address or id.
+
+The gem provides two methods for doing so: `DotMailer::Account#find_contact_by_email` and `DotMailer::Account#find_contact_by_id`.
+
+Suppose you have one contact with email john@example.com and id 12345, then:
+
+    account = DotMailer::Account.new('your-api-username', 'your-api-password')
+
+    account.find_contact_by_email 'john@example.com'
+    => DotMailer::Contact id: 12345, email: john@example.com
+
+    account.find_contact_by_email 'sue@example.com'
+    => nil
+
+    account.find_contact_by_id 12345
+    => DotMailer::Contact id: 12345, email: john@example.com
+
+    account.find_contact_by_id 54321
+    => nil
+
+### Finding contacts modified since a particular time
+
+Contacts modified since a particular time can be retrieved by passing a Time object to `DotMailer::Account#find_contacts_modified_since`:
+
+    account = DotMailer::Account.new('your-api-username', 'your-api-password')
+
+    time = Time.parse('1st March 2013 15:30')
+
+    account.find_contacts_modified_since(time)
+    => [
+         DotMailer::Contact id: 123, email: bob@example.com,
+         DotMailer::Contact id: 345, email: sue@example.com
+       ]
+
+### Updating a contact
+
+Contacts can be updated by assigning new values and calling `DotMailer::Contact#save`:
+
+    account = DotMailer::Account.new('your-api-username', 'your-api-password')
+
+    contact = account.find_contact_by_email 'john@example.com'
+    => DotMailer::Contact id: 12345, email: john@example.com, email_type: Html
+
+    contact.email_type
+    => 'Html'
+    contact.email_type = 'PlainText'
+    => 'PlainText
+
+    contact.save
 
-    client.create_data_field 'FIELD3', :type => 'String'
+    contact = DotMailer.find_contact_by_email 'john@example.com'
+    => DotMailer::Contact id: 12345, email: john@example.com, email_type: PlainText
+
+### Resubscribing a contact
+
+The dotMailer API provides a specific endpoint for resubscribing contacts which will initiate the resubscribe process via email, then redirect the contact to a specified URL.
+
+This can be accessed through the `DotMailer::Contact#resubscribe` method:
+
+    contact = DotMailer.find_contact_by_email 'john@example.com'
+    => DotMailer::Contact id: 12345, email: john@example.com, status: Unsubscribed
+
+    contact.subscribed?
+    => false
+    contact.resubscribe 'http://www.example.com/resubscribed'
+
+Then, once the contact has gone through the resubscribe process and been redirected to the specified URL:
+
+    contact = DotMailer.find_contact_by_email 'john@example.com'
+    => DotMailer::Contact id: 12345, email: john@example.com, status: Subscribed
+
+    contact.subscribed?
     => true
 
-    client.create_data_field 'FIELD3', :type => 'String'
-    => Dotmailer::DuplicateDataField
+### Bulk Import
+
+`DotMailer::Account#import_contacts` will start a batch import of contacts into the global address book, and return a `DotMailer::ContactImport` object which has a `status`:
+
+    account = DotMailer::Account.new('your-api-username', 'your-api-password')
+
+    import = account.import_contacts [
+      { 'Email' => 'joe@example.com' },
+      { 'Email' => 'sue@example.com' },
+      { 'Email' => 'bob@example.com' },
+      { 'Email' => 'invalid@email'   }
+    ]
+    => DotMailer::ContactImport contacts: [{"Email"=>"joe@example.com" }, {"Email"=>"sue@example.com" }, {"Email"=>"bob@example.com"}]
+
+    import.finished?
+    => false
+    import.status
+    => "NotFinished"
+
+Then, once the import has finished, you can query the status and get any errors (as a CSV::Table object):
+
+    import.finished?
+    => true
+    import.status
+    => "Finished"
+
+    errors = import.errors
+    => #<CSV::Table>
+    errors.count
+    => 1
+    errors.first
+    => #<CSV::Row "Reason":"Invalid Email" "Email":"invalid@email">
+
+**NOTE** The specified contacts can only have the following keys (case insensitive):
+
+* `id`
+* `email`
+* `optInType`
+* `emailType`
+* Any data field name for the account (i.e. any value in `account.data_fields.map(&:name)`)
+
+If any other key is present in any of the contacts, a `DotMailer::UnknownDataField` error will be raised
+
+Suppressions
+------------
+
+The dotMailer API provides an endpoint for retrieving suppressions since a particular point in time, where a "suppression" is the combination of a contact, a removal date, and a reason for the suppression.
+
+To fetch these suppressions, pass a Time object to `DotMailer::Account#find_suppressions_since`:
+
+    account = DotMailer::Account.new('your-api-username', 'your-api-password')
+
+    time = Time.parse('1st March 2013 15:30')
+
+    suppressions = account.find_suppressions_since(time)
+    => [
+         DotMailer::Suppression reason: Unsubscribed, date_removed: 2013-03-02 14:00:00 UTC,
+         DotMailer::Suppression reason: Unsubscribed, date_removed: 2013-03-04 16:00:00 UTC
+       ]
+
+    suppressions.first.contact
+    => DotMailer::Contact id: 12345, email: john@example.com

data/TODO.md

@@ -0,0 +1,6 @@
+Test against live API
+---------------------
+
+The dotMailer does not have a sandbox mode so we will need to be careful that we do not send mail to real email addresses whilst testing.
+
+We should consider using [VCR](https://github.com/vcr/vcr) to cache HTTP requests from the API.

data/dotmailer.gemspec

@@ -1,10 +1,10 @@
 # -*- encoding: utf-8 -*-
 $:.push File.expand_path("../lib", __FILE__)
-require "dotmailer/version"
+require "dot_mailer/version"
 
 Gem::Specification.new do |s|
   s.name        = "dotmailer"
-  s.version     = Dotmailer::VERSION
+  s.version     = DotMailer::VERSION
   s.authors     = ["Econsultancy"]
   s.email       = ["tech@econsultancy.com"]
   s.homepage    = "https://github.com/econsultancy/dotmailer"
@@ -13,10 +13,11 @@ Gem::Specification.new do |s|
   s.rubyforge_project = "dotmailer"
 
   s.files         = `git ls-files`.split("\n")
-  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.test_files    = `git ls-files -- {spec}/*`.split("\n")
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ["lib"]
 
+  s.add_runtime_dependency 'activesupport'
   s.add_runtime_dependency 'rest-client'
 
   s.add_development_dependency 'rspec'

data/lib/dot_mailer.rb

@@ -0,0 +1,11 @@
+require 'dot_mailer/exceptions'
+require 'dot_mailer/data_field'
+require 'dot_mailer/contact_import'
+require 'dot_mailer/contact'
+require 'dot_mailer/suppression'
+require 'dot_mailer/account'
+require 'dot_mailer/client'
+
+module DotMailer
+  SUBSCRIBED_STATUS = 'Subscribed'
+end

data/lib/dot_mailer/account.rb

@@ -0,0 +1,66 @@
+require 'active_support/core_ext/numeric/time'
+require 'active_support/cache'
+
+module DotMailer
+  class Account
+    CACHE_LIFETIME = 1.minute
+
+    attr_reader :client
+
+    def initialize(api_user, api_pass)
+      self.client = Client.new(api_user, api_pass)
+    end
+
+    def data_fields
+      cache.fetch 'data_fields' do
+        DataField.all self
+      end
+    end
+
+    def create_data_field(name, options = {})
+      DataField.create self, name, options
+
+      cache.delete 'data_fields'
+    end
+
+    def import_contacts(contacts)
+      ContactImport.import self, contacts
+    end
+
+    def find_contact_by_email(email)
+      Contact.find_by_email self, email
+    end
+
+    def find_contact_by_id(id)
+      Contact.find_by_id self, id
+    end
+
+    def find_contacts_modified_since(time)
+      Contact.modified_since(self, time)
+    end
+
+    def find_suppressions_since(time)
+      Suppression.suppressed_since(self, time)
+    end
+
+    def suppress(email)
+      client.post_json '/contacts/unsubscribe', 'Email' => email
+    end
+
+    def to_s
+      "#{self.class.name} client: #{client}"
+    end
+
+    def inspect
+      to_s
+    end
+
+    private
+    attr_writer :client
+
+    def cache
+      # Auto expire content after CACHE_LIFETIME seconds
+      @cache ||= ActiveSupport::Cache::MemoryStore.new :expires_in => CACHE_LIFETIME
+    end
+  end
+end

data/lib/dot_mailer/client.rb

@@ -0,0 +1,108 @@
+# encoding: utf-8
+require 'tempfile'
+require 'cgi'
+require 'json'
+require 'restclient'
+
+module DotMailer
+  class Client
+    def initialize(api_user, api_pass)
+      self.api_user = api_user
+      self.api_pass = api_pass
+    end
+
+    def get(path)
+      rescue_api_errors do
+        endpoint = endpoint_for(path)
+        response = RestClient.get endpoint, :accept => :json
+
+        JSON.parse response
+      end
+    end
+
+    def get_csv(path)
+      rescue_api_errors do
+        endpoint = endpoint_for(path)
+        response = RestClient.get endpoint, :accept => :csv
+
+        # Force the encoding to UTF-8 as that is what the
+        # API returns (otherwise it will be ASCII-8BIT, see
+        # http://bugs.ruby-lang.org/issues/2567)
+        response.force_encoding('UTF-8')
+
+        # Remove the UTF-8 BOM if present
+        response.sub!(/\A\xEF\xBB\xBF/, '')
+
+        CSV.parse response, :headers => true
+      end
+    end
+
+    def post_json(path, params)
+      post path, params.to_json, :content_type => :json
+    end
+
+    # Need to use a Tempfile as the API will not accept CSVs
+    # without filenames
+    def post_csv(path, csv)
+      file = Tempfile.new(['dotmailer-contacts', '.csv'])
+      file.write csv
+      file.rewind
+
+      post path, :csv => file
+    end
+
+    def post(path, data, options = {})
+      rescue_api_errors do
+        endpoint = endpoint_for(path)
+        response = RestClient.post endpoint, data, options.merge(:accept => :json)
+
+        JSON.parse response
+      end
+    end
+
+    def put_json(path, params)
+      put path, params.to_json, :content_type => :json
+    end
+
+    def put(path, data, options = {})
+      rescue_api_errors do
+        endpoint = endpoint_for(path)
+        response = RestClient.put endpoint, data, options.merge(:accept => :json)
+
+        JSON.parse response
+      end
+    end
+
+    def to_s
+      "#{self.class.name} api_user: #{api_user}"
+    end
+
+    def inspect
+      to_s
+    end
+
+    private
+    attr_accessor :api_user, :api_pass
+
+    def rescue_api_errors
+      yield
+    rescue RestClient::BadRequest => e
+      raise InvalidRequest, extract_message_from_exception(e)
+    rescue RestClient::ResourceNotFound => e
+      raise NotFound, extract_message_from_exception(e)
+    end
+
+    def extract_message_from_exception(exception)
+      JSON.parse(exception.http_body)['message']
+    end
+
+    def endpoint_for(path)
+      URI::Generic.build(
+        :scheme   => 'https',
+        :userinfo => "#{CGI.escape(api_user)}:#{CGI.escape(api_pass)}",
+        :host     => 'api.dotmailer.com',
+        :path     => "/v2#{path}"
+      ).to_s
+    end
+  end
+end

data/lib/dot_mailer/contact.rb

@@ -0,0 +1,179 @@
+require 'active_support/core_ext/object/try'
+require 'active_support/core_ext/object/blank'
+require 'time'
+
+require 'dot_mailer/opt_in_type'
+
+module DotMailer
+  class Contact
+    def self.find_by_email(account, email)
+      response = account.client.get("/contacts/#{email}")
+
+      new(account, response)
+    rescue DotMailer::NotFound
+      nil
+    end
+
+    # The API makes no distinction between finding
+    # by email or id, so we just delegate to
+    # Contact.find_by_email
+    def self.find_by_id(account, id)
+      find_by_email account, id
+    end
+
+    def self.modified_since(account, time)
+      response = account.client.get("/contacts/modified-since/#{time.utc.xmlschema}")
+
+      response.map do |attributes|
+        new(account, attributes)
+      end
+    end
+
+    def initialize(account, attributes)
+      self.account    = account
+      self.attributes = attributes
+    end
+
+    def id
+      attributes['id']
+    end
+
+    def email
+      attributes['email']
+    end
+
+    def email=(email)
+      attributes['email'] = email
+    end
+
+    def opt_in_type
+      attributes['optInType']
+    end
+
+    def opt_in_type=(opt_in_type)
+      raise UnknownOptInType, opt_in_type unless OptInType.exists?(opt_in_type)
+
+      attributes['optInType'] = opt_in_type
+    end
+
+    def email_type
+      attributes['emailType']
+    end
+
+    def email_type=(email_type)
+      attributes['emailType'] = email_type
+    end
+
+    def status
+      attributes['status']
+    end
+
+    def to_s
+      %{#{self.class.name} id: #{id}, email: #{email}, opt_in_type: #{opt_in_type}, email_type: #{email_type}, status: #{status}, data_fields: #{data_fields.to_s}}
+    end
+
+    def inspect
+      to_s
+    end
+
+    # A wrapper method for accessing data field values by name, e.g.:
+    #
+    #   contact['FIRSTNAME']
+    #
+    def [](key)
+      if data_fields.has_key?(key)
+        data_fields[key]
+      else
+        raise UnknownDataField, key
+      end
+    end
+
+    # A wrapper method for assigning data field values, e.g.:
+    #
+    #   contact['FIRSTNAME'] = 'Lewis'
+    #
+    def []=(key, value)
+      if data_fields.has_key?(key)
+        data_fields[key] = value
+      else
+        raise UnknownDataField, key
+      end
+    end
+
+    def save
+      client.put_json "/contacts/#{id}", attributes.merge('dataFields' => data_fields_for_api)
+    end
+
+    def subscribed?
+      status == SUBSCRIBED_STATUS
+    end
+
+    def resubscribe(return_url)
+      return false if subscribed?
+
+      client.post_json '/contacts/resubscribe',
+        'UnsubscribedContact' => {
+          'id'    => id,
+          'Email' => email
+        },
+        'ReturnUrlToUseIfChallenged' => return_url
+    end
+
+    private
+    attr_accessor :attributes, :account
+
+    def client
+      account.client
+    end
+
+    # Convert data fields from the API into a flat hash.
+    #
+    # We coerce Date fields from strings into Time objects.
+    #
+    # The API returns data field values in the following format:
+    #
+    #   'dataFields' => [
+    #     { 'key' => 'FIELD1', 'value' => 'some value'},
+    #     { 'key' => 'FIELD2', 'value' => 'some other value'}
+    #   ]
+    #
+    # We convert that here to:
+    #
+    #   { 'FIELD1' => 'some value', 'FIELD2' => 'some other value' }
+    #
+    def data_fields
+      # Some API calls (e.g. modified-since) don't return data fields
+      return [] unless attributes['dataFields'].present?
+
+      @data_fields ||=
+        begin
+          account.data_fields.each_with_object({}) do |data_field, hash|
+            value = attributes['dataFields'].detect { |f| f['key'] == data_field.name }.try(:[], 'value')
+
+            if value.present? && data_field.date?
+              value = Time.parse(value)
+            end
+
+            hash[data_field.name] = value
+          end
+        end
+    end
+
+    # Convert data fields from a flat hash to an API compatible hash:
+    #
+    #   { 'FIELD1' => 'some value', 'FIELD2' => 'some other value' }
+    #
+    # Becomes:
+    #
+    #   [
+    #     { 'key' => 'FIELD1', 'value' => 'some value'},
+    #     { 'key' => 'FIELD2', 'value' => 'some other value'}
+    #   ]
+    #
+    def data_fields_for_api
+      data_fields.map do |key, value|
+        { 'key' => key, 'value' => value.to_s }
+      end
+    end
+  end
+end