emarsys 0.1.0

data/lib/emarsys/data_objects/condition.rb

@@ -0,0 +1,20 @@
+module Emarsys
+
+  # Methods for the Condition API
+  #
+  #
+  class Condition < DataObject
+    class << self
+
+      # List conditions
+      #
+      # @return [Hash] List of conditions
+      # @example
+      #   Emarsys::Condition.collection
+      def collection
+        get 'condition', {}
+      end
+    end
+
+  end
+end

data/lib/emarsys/data_objects/contact.rb

@@ -0,0 +1,121 @@
+module Emarsys
+
+  # Methods for the Contact API
+  #
+  #
+  class Contact < DataObject
+    class << self
+
+      # Create a new contact. The given params are transformed to emarsys ids.
+      #
+      # @param key_id [Integer, String] internal id of key field
+      # @param key_value [Integer, String] value of interal id field
+      # @param params [Hash] Contact information to create
+      # @return [Hash] internal id of the contact
+      # @example
+      #   Emarsys::Contact.create('app_id', 23, {:firstname => "Jon", :lastname => "Doe"})
+      #   Emarsys::Contact.create('3', 'john.doe@example.com', {'1' => "Jon", '2' => "Doe"})
+      def create(key_id, key_value, params = {})
+        transformed_key_id = transform_key_id(key_id)
+        post "contact", params.merge!({'key_id' => transformed_key_id, transformed_key_id => key_value})
+      end
+
+      # Get the interal emarsys id of a contact. The given params are transformed to emarsys ids.
+      #
+      # @param key_id [Integer, String] internal id of key field
+      # @param key_value [Integer, String] value of interal id field
+      # @return [Hash] internal emarsys id of the contact
+      # @example
+      #   Emarsys::Contact.emarsys_id('email', 'john.dow@example.com')
+      #   Emarsys::Contact.emarsys_id(1, 'John')
+      def emarsys_id(key_id, key_value)
+        get "contact/#{transform_key_id(key_id).to_s}=#{key_value.to_s}", {}
+      end
+
+      # Update a contact. The given params are transformed to emarsys ids.
+      #
+      # @param key_id [Integer, String] internal id of key field
+      # @param key_value [Integer, String] value of interal id field
+      # @param params [Hash] Contact information to update
+      # @return [Hash] internal id of the contact
+      # @example
+      #   Emarsys::Contact.update('app_id', 23, {:firstname => "Jon", :lastname => "Doe"})
+      #   Emarsys::Contact.update('3', 'john.doe@example.com', {'1' => "Jon", '2' => "Doe"})
+      def update(key_id, key_value, params = {})
+        transformed_key_id = transform_key_id(key_id)
+        put "contact", params.merge!({'key_id' => transformed_key_id, transformed_key_id => key_value})
+      end
+
+      # Batch creation of contacts.
+      #
+      # @param key_id [Integer, String] internal id of key field
+      # @param params [Hash] Contact information of each new contact
+      # @example
+      #   Emarsys::Contact.create_batch(
+      #     'email', {:app_id => 1, :firstname => "Jon", :lastname => "Doe"},
+      #              {:app_id => 2, :firstname => "Jane", :lastname => "Doe"}
+      #   )
+      #
+      # TODO params should be parameterized with field mappings
+      def create_batch(key_id, params = [])
+        post "contact", {'key_id' => transform_key_id(key_id), 'contacts' => params}
+      end
+
+      # Batch update of contacts.
+      #
+      # @param key_id [Integer, String] internal id of key field
+      # @param params [Hash] Contact information of each new contact
+      # @example
+      #   Emarsys::Contact.update_batch(
+      #     'email', {:app_id => 1, :firstname => "Jon", :lastname => "Doe"},
+      #              {:app_id => 2, :firstname => "Jane", :lastname => "Doe"}
+      #   )
+      #
+      # TODO params should be parameterized with field mappings
+      def update_batch(key_id, params = [])
+        put "contact", {'key_id' => transform_key_id(key_id), 'contacts' => params}
+      end
+
+      # Get list of emails send to a contact
+      #
+      # @param contact_ids_array [array] Array of contact ids
+      # @return [Hash] result data
+      # @example
+      #   Emarsys::Contact.contact_history([1,2,3]
+      def contact_history(contact_ids_array)
+        post "contact/getcontacthistory", {'contacts' => contact_ids_array}
+      end
+
+      # Get contact data by custom search
+      #
+      # @param key_id [Integer, String] Array of contact ids
+      # @param key_values [array] Array of key field values
+      # @param fields [array] requested fields. If empty, all are considered
+      # @return [Hash] result data
+      # @example
+      #   Emarsys::Contact.search('3', ['john.doe@example.com'], [1,2,3]
+      #
+      # TODO transform fields to numeric fields
+      def search(key_id, key_values = [], fields = [])
+        post "contact/getdata", {'keyId' => key_id, 'keyValues' => key_values, 'fields' => fields}
+      end
+
+      # Exports the selected fields of contacts whoch registered in the specified time range
+      #
+      # @param params [hash] hash of parameters according to emarsys API
+      # @return [Hash] result data
+      # @example
+      #   Emarsys::Contact.export_registrations(distribution_method: 'local', time_range: ["2013-01-01","2013-12-31"], contact_fields: [1,2,3])
+      def export_registrations(params = {})
+        post "contact/getregistrations", params
+      end
+
+      # @private
+      def transform_key_id(key_id)
+        matching_attributes = Emarsys::FieldMapping::ATTRIBUTES.find{|elem| elem[:identifier] == key_id.to_s}
+        matching_attributes.nil? ? key_id : matching_attributes[:id]
+      end
+
+    end
+  end
+end

data/lib/emarsys/data_objects/contact_list.rb

@@ -0,0 +1,47 @@
+module Emarsys
+
+  # Methods for the ContactList API
+  #
+  #
+  class ContactList < DataObject
+    class << self
+
+      # List contact lists
+      #
+      # @return [Hash] List of contact_lists
+      # @example
+      #   Emarsys::ContactList.collection
+      def collection
+        get 'contactlist', {}
+      end
+
+      # Create a new contact list
+      #
+      # @param params [Hash] Contact list information to create
+      # @option params [String] :name Name of the list
+      # @option params [String] :description Detailed description of the list
+
+      # @return [Hash] internal id of the contact list
+      # @example
+      #   Emarsys::ContactList.create(key_id: "3", name: 'Test-Liste', description: 'Something')
+      def create(params = {})
+        post "contactlist", params
+      end
+
+      # Add a contacts to a specific contact list
+      #
+      # This cannot be an instance method, because the API does not allow to retrieve a single resource. How crappy is that?
+      def add_contacts(contact_list_id, key_id, external_ids = [])
+        post "contactlist/#{contact_list_id}/add", {'key_id' => key_id, 'external_ids' => external_ids}
+      end
+
+      # Remove contacts from a specific contact list
+      #
+      # This cannot be an instance method, because the API does not allow to retrieve a single resource. How crappy is that?
+      def remove_contacts(contact_list_id, key_id, external_ids = [])
+        post "contactlist/#{contact_list_id}/remove", {'key_id' => key_id, 'external_ids' => external_ids}
+      end
+
+    end
+  end
+end

data/lib/emarsys/data_objects/email.rb

@@ -0,0 +1,133 @@
+module Emarsys
+
+  # Methods for the Email API
+  #
+  #
+  class Email < DataObject
+    class << self
+
+      # List email campaigns
+      #
+      # @param params [Hash] Optional filter for the emails
+      # @option params [String] :status filter by status
+      # @option params [String] :contactlist filter by contactlist
+      # @return [Hash] List of emails
+      # @example
+      #   Emarsys::Email.collection
+      #   Emarsys::Email.collection(:status => 3)
+      #   Emarsys::Email.collection(:contactlist => 5)
+      def collection(params = {})
+        get 'email', params
+      end
+
+      # Get Email attirbutes of a specific email
+      #
+      # @param id [Integer, String] The internal id of an email
+      # @return [Hash] Attributes hash
+      # @example
+      #   Emarsys::Email.resource(1)
+      def resource(id)
+        get "email/#{id}", {}
+      end
+
+      # Create a new email campaign
+      #
+      # @param params [Hash] Email information to create
+      # @option params [String] :name Name of the email campagin
+      # @option params [String] :language Language Code
+      # @option params [String] :fromemail sets the from-header email
+      # @option params [String] :fromname sets the from-header name
+      # @option params [String] :subject Subject of the email
+      # @option params [Integer] :email_category associated Email-Category-Id
+      # @option params [Integer] :segment associated Segment-id
+      # @option params [Integer] :contactlist associated Contactlist-id
+      # @option params [String] :html_source
+      # @option params [String] :text_source
+      # @option params [Integer] :unsubscribe (optional)
+      # @option params [Integer] :browse (optional)
+      # @return [Hash] internal id of the campaign
+      # @example
+      #   Emarsys::Email.create(
+      #     name: 'Test', language: 'de', fromemail: 'john.doe@example.com', fromname: 'John Doe',
+      #     subject: 'Test Subject', :email_category: 3, segment: 1121, contactlist: 0,
+      #     html_source: '<h1>Test</h1>', text_source: 'Test'
+      #   )
+      def create(params = {})
+        post "email", params
+      end
+
+      # Launches an email
+      #
+      # @param id [Integer, String] Internal email id
+      # @param params [hash] Optional launch parmeters
+      # @option params [Datetime] :schedule launch time
+      # @option params [String] :timezone
+      # @return [Hash] Result data
+      # @example
+      #   Emarsys::Email.launch(1)
+      def launch(id, params = {})
+        post "email/#{id}/launch", params
+      end
+
+      # Preview an email
+      #
+      # @param id [Integer, String] Internal email id
+      # @param version [String] 'html' or 'text' version
+      # @return [Hash] Result data
+      # @example
+      #   Emarsys::Email.preview(1)
+      def preview(id, version = 'html')
+        post "email/#{id}/preview", {:version => version}
+      end
+
+      # View response summary of an email
+      #
+      # @param id [Integer, String] Internal email id
+      # @return [Hash] Result data
+      # @example
+      #   Emarsys::Email.response_summary(1)
+      def response_summary(id)
+        get "email/#{id}/responsesummary", {}
+      end
+
+      # Instruct emarsys to send a test mail
+      #
+      # @param id [Integer, String] Internal email id
+      # @param params [hash] recipient parmeters
+      # @option params [String] :recipientlist email_addresses separated by ';'
+      # @option params [Integer] :segment_id custom segement id
+      # @option params [Integer] :contactlist_id custom contactlist id
+      # Only one of the three parameters must be sent.
+      #
+      # @return [Hash] Result data
+      # @example
+      #   Emarsys::Email.send_test_mail(1, {:recipientlist => 'john.doe@example.com;jane.doe@example.com'})
+      def send_test_mail(id, params = {})
+        post "email/#{id}/sendtestmail", params
+      end
+
+      # Returns the delivery status of an email
+      #
+      # @param id [Integer, String] Internal email id
+      # @param params [hash] recipient parmeters
+      # @option params [String] 'lastId'
+      # @option params [Integer] 'launchId'
+      # @return [Hash] Result data
+      # @example
+      #   Emarsys::Email.delivery_status(1)
+      def delivery_status(id, params = {})
+        post "email/#{id}/getdeliverystatus", params
+      end
+
+      # TODO POST /getlaunchesofemail
+      def email_launches(id)
+        raise "Not implemented yet"
+      end
+
+      # TODO POST /getresponses
+      def export_responses(params = {})
+        raise "Not implemented yet"
+      end
+    end
+  end
+end

data/lib/emarsys/data_objects/email_category.rb

@@ -0,0 +1,20 @@
+module Emarsys
+
+  # Methods for the EmailCategory API
+  #
+  #
+  class EmailCategory < DataObject
+    class << self
+
+      # List email categories
+      #
+      # @return [Hash] List of email_categories
+      # @example
+      #   Emarsys::EmailCategory.collection
+      def collection
+        get 'emailcategory', {}
+      end
+
+    end
+  end
+end

data/lib/emarsys/data_objects/email_launch_status.rb

@@ -0,0 +1,38 @@
+module Emarsys
+
+  # Internal helper class for valid email launch status.
+  # Emarsys has no implementation for this data resource.
+  #
+  class EmailLaunchStatus < DataObject
+
+    CODES = [
+      {'0'   => 'Not launched'},
+      {'1'   => 'Launch called via API, launching in Progress'},
+      {'2'   => 'Email launched or scheduled for future launch'},
+      {'10'   => 'Error (details in api_error)'}
+    ]
+
+    class << self
+
+      # List email launch status codes
+      #
+      # @return [Hash] List of email launch status
+      # @example
+      #   Emarsys::EmailLaunchStatus.collection
+      def collection
+        CODES
+      end
+
+      # Get a specific email launch status
+      #
+      # @param [Integer, String] id of the code
+      # @return [Hash] Key-Value-Pair of the launch code
+      # @example
+      #   Emarsys::EmailLaunchStatus.resource('1')
+      def resource(id)
+        CODES.select{|hash| hash.has_key?(id.to_s)}[0]
+      end
+    end
+
+  end
+end

data/lib/emarsys/data_objects/email_status_code.rb

@@ -0,0 +1,39 @@
+module Emarsys
+
+  # Internal helper class for valid email status codes.
+  # Emarsys has no implementation for this data resource.
+  #
+  class EmailStatusCode < DataObject
+
+    CODES = [
+      {'1'   => 'In design'},
+      {'2'   => 'Tested'},
+      {'3'   => 'Launched'},
+      {'4'   => 'Ready to launch'},
+      {'-3'  => 'Deactivated'}
+    ]
+
+    class << self
+
+      # List email status codes
+      #
+      # @return [Hash] List of email status codes
+      # @example
+      #   Emarsys::EmailStatusCode.collection
+      def collection
+        CODES
+      end
+
+      # Get a specific email status codes
+      #
+      # @param [Integer, String] id of the code
+      # @return [Hash] Key-Value-Pair of the status code
+      # @example
+      #   Emarsys::EmailStatusCode.resource('1')
+      def resource(id)
+        CODES.select{|hash| hash.has_key?(id.to_s)}[0]
+      end
+    end
+
+  end
+end

data/lib/emarsys/data_objects/event.rb

@@ -0,0 +1,44 @@
+module Emarsys
+
+  # Methods for the Event API
+  #
+  #
+  class Event < DataObject
+
+    class << self
+
+      # List events
+      #
+      # @return [Hash] List of events
+      # @example
+      #   Emarsys::Event.collection
+      def collection
+        get 'event', {}
+      end
+
+      # Trigger an external event
+      #
+      # @param event_id [Integer, String] The internal emarsys id
+      # @param key_id [Integer, String] The identifer of the key field (e.g. 3 for 'email')
+      # @param external_id [String] The id of the given filed specified with key_id (e.g. 'test@example.com')
+      # @option data [Hash] data hash for transactional mails
+      # @return [Hash] Result data
+      # @example
+      #   Emarsys::Event.trigger(2, 3, 'test@example.com')
+      #   Emarsys::Event.trigger(2, 'user_id', 57687, {:global => {:name => "Special Name"}})
+      def trigger(event_id, key_id, external_id, data = {})
+        transformed_key_id = transform_key_id(key_id)
+        params = {:key_id => transformed_key_id, :external_id => external_id}
+        params.merge!(:data => data) if not data.empty?
+        post "event/#{event_id}/trigger", params
+      end
+
+      # @private
+      def transform_key_id(key_id)
+        matching_attributes = Emarsys::FieldMapping::ATTRIBUTES.find{|elem| elem[:identifier] == key_id.to_s}
+        matching_attributes.nil? ? key_id : matching_attributes[:id]
+      end
+    end
+
+  end
+end