getresponse 0.4 → 0.5

data/README.rdoc

@@ -113,6 +113,11 @@ Get campaign messages
   messages = campaign.messages
   newsletters = campaign.messages(:type => "newsletter")
 
+Get all messages
+
+  # with connection
+  connection.messages.all
+
 Get message contents
 
   # with message
@@ -135,4 +140,51 @@ Get/set campaign's postal address
   # campaign_one - existing campaign
   # campaign_two - existing campaign
   postal_address = campaign_one.postal_address
-  campaign_two.postal_address = postal_address
+  campaign_two.postal_address = postal_address
+
+
+To get contact openned message list with dates
+
+  # contact - existing contact
+  @contact.opens
+
+Get subscriptions statistics
+
+  # campaign - existing campaign
+  campaign.subscription_statistics
+  campaign.subscription_statistics(:created_on => {:at => Date.today})
+  campaign.subscription_statistics(:created_on => {:from => "2011-01-01", :to => "2011-12-30"})
+
+Get confirmation message bodies
+
+  # connection - existing connection
+  connection.confirmation_bodies.all
+  connection.confirmation_bodies.all(:language_code => {:equals => "en"})
+
+Get confirmation message subjects
+
+  # connection - existing connection
+  connection.confirmation_subjects.all
+  connection.confirmation_subjects.all(:language_code => {:equals => "en"})
+
+Get deleted contacts
+
+  contact_proxy.deleted
+  contact_proxy.deleted(:reason => "bounce")
+  campaign.deleted
+
+Get single field form by id
+
+  from_field_proxy.find("from_field_id")
+
+Get single confirmation body by id
+
+  confirmation_body_proxy.find("confirmation_body_id")
+
+Get single confirmation subject by id
+
+  confirmation_subject_proxy.find("confirmation_subject_id")
+
+Create new campaign
+
+  connection.campaigns.create(new_campaign_attributes)

data/lib/get_response.rb

@@ -24,6 +24,7 @@ class SymbolOperator
 
 
   def evaluate(value)
+    warn "[DEPRECATION] evaluation of GetResponse operators is deprecated."
     { field.to_s => { gr_operator => value } }
   end
 
@@ -56,4 +57,9 @@ GetResponse.autoload :Domain, "get_response/domain"
 GetResponse.autoload :DomainProxy, "get_response/domain_proxy"
 GetResponse.autoload :MessageProxy, "get_response/message_proxy"
 GetResponse.autoload :Newsletter, "get_response/newsletter"
-GetResponse.autoload :FollowUp, "get_response/follow_up"
+GetResponse.autoload :FollowUp, "get_response/follow_up"
+GetResponse.autoload :ConfirmationBody, "get_response/confirmation_body"
+GetResponse.autoload :ConfirmationBodyProxy, "get_response/confirmation_body_proxy"
+GetResponse.autoload :ConfirmationSubject, "get_response/confirmation_subject"
+GetResponse.autoload :ConfirmationSubjectProxy, "get_response/confirmation_subject_proxy"
+GetResponse.autoload :Conditions, "get_response/conditions"

data/lib/get_response/campaign.rb

@@ -3,6 +3,8 @@ module GetResponse
   # GetResponse email campaign
   class Campaign
     attr_reader :id, :name, :from_name, :from_email, :reply_to_email, :created_on
+    attr_reader :from_field, :reply_to_field, :confirmation_body, :confirmation_subject
+    attr_accessor :description, :language_code
 
 
     def initialize(params, connection)
@@ -25,6 +27,15 @@ module GetResponse
     end
 
 
+    # Get contacts deleted from this campaign
+    #
+    # @return [Array]
+    def deleted_contacts
+      @contact_proxy = ContactProxy.new(@connection)
+      @contact_proxy.deleted(:campaigns => [@id])
+    end
+
+
     # Get domain assigned to this campaign.
     #
     # returns:: GetResponse::Domain
@@ -84,6 +95,99 @@ module GetResponse
       result if result["updated"].to_i == 1
     end
 
+
+    # Get contacts subscription stats for this campaign aggregated by date, campaign and contact’s origin.
+    # Example:
+    #
+    #   # get stats for camapaign, any time period
+    #   @campaign.subscription_statistics
+    #
+    #   # get stats for specified date
+    #   @campaign.subscription_statistics(:created_on => {:at => Date.today})
+    #   @campaign.subscription_statistics(:created_on => {:from => "2011-01-01", :to => "2011-12-30"})
+    #
+    # @param conditions [Hash] conditions for statistics query, empty by default
+    # @return [Hash] collection of aggregated statistics
+    def subscription_statistics(conditions = {})
+      @contact_proxy = ContactProxy.new(@connection)
+      @contact_proxy.statistics(conditions.merge(:campaigns => [@id]))
+    end
+
+
+    # Set object (without sending API 'set' request) level from field. If value is not
+    # <tt>GetResponse::FromField</tt> method will try to fetch from field attributes through API.
+    #
+    # @param value [FromField]
+    # @return [GetResponse::FromField]
+    def from_field=(value)
+      if value.instance_of? GetResponse::FromField
+        @from_field = value
+      else
+        @from_field = FromFieldsProxy.new(@connection).find(value)
+      end
+    end
+
+
+    # Set object (without sending API 'set' request) level reply to field. If value is not
+    # <tt>GetResponse::FromField</tt> method will try to fetch from field attributes through API.
+    #
+    # @param value [FromField]
+    # @return [GetResponse::FromField]
+    def reply_to_field=(value)
+      if value.instance_of? GetResponse::FromField
+        @reply_to_field = value
+      else
+        @reply_to_field = FromFieldsProxy.new(@connection).find(value)
+      end
+    end
+
+
+    # Set object (without sending API 'set' request) level confirmation body. If value is not
+    # <tt>GetResponse::ConfirmationBody</tt> instance method will try to fetch attributes through API.
+    #
+    # @param value [GetResponse::ConfirmationBody]
+    # @return [GetResponse::ConfirmationBody]
+    def confirmation_body=(value)
+      if value.instance_of? GetResponse::ConfirmationBody
+        @confirmation_body = value
+      else
+        @confirmation_body = ConfirmationBodyProxy.new(@connection).find(value)
+      end
+    end
+
+
+    # Set object (without sending API 'set' request) level confirmation subject. If value is not
+    # <tt>GetResponse::ConfirmationSubject</tt> instance method will try to fetch attributes through API.
+    #
+    # @param value [GetResponse::ConfirmationSubject]
+    # @return [GetResponse::ConfirmationSubject]
+    def confirmation_subject=(value)
+      if value.instance_of? GetResponse::ConfirmationSubject
+        @confirmation_subject = value
+      else
+        @confirmation_subject = ConfirmationSubjectProxy.new(@connection).find(value)
+      end
+    end
+
+
+    # Saves new campaign.
+    #
+    # @return [GetResponse::Campaign]
+    def save
+      attributes = {
+        "name" => name,
+        "description" => description,
+        "language_code" => language_code,
+        "from_field" => from_field.id,
+        "reply_to_field" => reply_to_field.id,
+        "confirmation_subject" => confirmation_subject.id,
+        "confirmation_body" => confirmation_body.id
+      }
+      save_result = @connection.send_request("add_campaign", attributes)["result"]
+      @id = save_result["CAMPAIGN_ID"]
+      self
+    end
+
   end
 
 end

data/lib/get_response/campaign_proxy.rb

@@ -18,6 +18,23 @@ module GetResponse
       end
     end
 
+
+    # Create new campaign from passed attributes
+    #
+    # @param attrs [Hash]
+    # @return [GetResponse::Campaign]
+    def create(attrs)
+      new_campaign = Campaign.new(attrs, @connection)
+      new_campaign.description = attrs["description"]
+      new_campaign.language_code = attrs["language_code"]
+      new_campaign.reply_to_field = attrs["reply_to_field"]
+      new_campaign.from_field = attrs["from_field"]
+      new_campaign.confirmation_body = attrs["confirmation_body"]
+      new_campaign.confirmation_subject = attrs["confirmation_subject"]
+      new_campaign.save
+      new_campaign
+    end
+
   end
 
 end

data/lib/get_response/conditions.rb

@@ -0,0 +1,97 @@
+module GetResponse
+
+  # GetResponse API Operators (http://dev.getresponse.com/api-doc/#operators) parsing module.
+  module Conditions
+
+    protected
+
+
+    # Parse whole set of conditions. Method can raise <tt>GetResponseError</tt> exception if any of
+    # passed condition opertors is not on supported operator list.
+    # Example:
+    #
+    #   parse_conditions(:created_on => {:from => "2011-01-01", :to => Time.now}, :count => {'less' => 45, :equals => nil})
+    #   => {:created_on=>{"FROM"=>"2011-01-01", "TO"=>"2011-10-31"}, :count=>{"LESS"=>45}}
+    #
+    # conditions::  Hash, empty by default
+    # returns:: Hash
+    def parse_conditions(conditions = {})
+      parsed_conditions = {}
+      conditions.each_pair do |field, conds|
+        # if conds doesn't look like conditions hash
+        unless conds.respond_to?(:each_pair)
+          parsed_conditions[field] = conds
+          next
+        end
+        conds.each_pair do |operator, value|
+          parsed_conditions[field] ||= {}
+          operator = operator.to_s.upcase
+          parsed_conditions[field].merge! parse_condition(operator, value)
+        end
+      end
+
+      parsed_conditions
+    end
+
+
+    # Parse condition with operator and its value. Method return <tt>Hash</tt> instance with
+    # condition for operator. If value is <tt>nil</tt> empty <tt>Hash</tt> will be returned.
+    # If  operator is not on supported operator list <tt>GetResponseError</tt> will be raised.
+    # Example:
+    #
+    #   parse_condition(:from, 2.days.ago)
+    #   => {"FROM" => "2011-10-28"}
+    #   parse_condition("TO", nil)
+    #   => {}
+    #
+    # operator:: Symbol, String
+    # value:: String, Fixnum, Date, Time
+    # returns:: Hash
+    def parse_condition(operator, value)
+      parsed = case operator
+        when "EQUALS", "NOT_EQUALS", "CONTAINS", "NOT_CONTAINS", "MATCHES"
+          parse_text_conditions(operator, value)
+        when "LESS", "LESS_OR_EQUALS", "EQUALS", "GREATER_OR_EQUALS", "GREATER"
+          parse_text_conditions(operator, value)
+        when "FROM", "TO", "AT"
+          parse_date_conditions(operator, value)
+        else
+          raise GetResponse::GetResponseError.new("Bad operator: #{operator}")
+      end
+
+      parsed.delete_if { |k, v| v.nil? }
+    end
+
+
+    # Parse datetime operators.
+    # Example:
+    #
+    #   parse_date_conditions(:from => "2011-10-01")
+    #   => {"FROM" => "2011-10-01"}
+    #   parse_date_conditions(:to => 2.days.ago)
+    #   => {"TO" => "2011-10-28"}
+    #
+    # operator::  String
+    # value:: String, Date, Time
+    # returns:: Hash
+    def parse_date_conditions(operator, value)
+      if value.respond_to?(:strftime)
+        {operator => value.strftime("%Y-%m-%d")}
+      else
+        {operator => value}
+      end
+    end
+
+
+    # Parse text operators.
+    #
+    # operator::  String
+    # value:: String
+    # returns:: Hash
+    def parse_text_conditions(operator, value)
+      {operator => value}
+    end
+
+  end
+
+end

data/lib/get_response/confirmation_body.rb

@@ -0,0 +1,18 @@
+module GetResponse
+
+  # GetResponse confirmation body. It can be used in campaign settings.
+  class ConfirmationBody
+
+    attr_reader :id, :plain, :html, :language_code
+
+
+    def initialize(attributes)
+      @id = attributes["id"]
+      @plain = attributes["plain"]
+      @html = attributes["html"]
+      @language_code = attributes["language_code"]
+    end
+
+  end
+
+end

data/lib/get_response/confirmation_body_proxy.rb

@@ -0,0 +1,47 @@
+module GetResponse
+
+  # Proxy class for confirmation body operations.
+  class ConfirmationBodyProxy
+
+    include Conditions
+
+
+    def initialize(connection)
+      @connection = connection
+    end
+
+
+    # Get list of available bodies for confirmation messages. They can be used in campaign settings.
+    # Example:
+    #
+    #   @proxy.all
+    #   @proxy.all(:language_code => {:equals => "pl"})
+    #
+    # @param conditions [Hash] conditions passed to query, empty by default
+    # @return [Array] collection of <tt>ConfirmationBody</tt> objects returned by API query
+    def all(conditions = {})
+      conditions = parse_conditions(conditions)
+
+      response = @connection.send_request("get_confirmation_bodies", conditions)["result"]
+      response.inject([]) do |bodies, resp|
+        bodies << ConfirmationBody.new(resp[1].merge("id" => resp[0]))
+      end
+    end
+
+
+    # Get single confirmation body based on its <tt>id</tt>. Method can raise
+    #<tt>GetResposne::GetResponseError</tt> exception if no confirmation body is found.
+    #
+    # @param body_id [String]
+    # @return [GetResponse::ConfirmationBody]
+    def find(body_id)
+      params = {"confirmation_body" => body_id}
+      resp = @connection.send_request("get_confirmation_body", params)["result"]
+      raise GetResponseError.new "Confirmation body with id '#{body_id}' not found." if resp.empty?
+      body_attrs = resp.values[0].merge("id" => resp.keys.first)
+      ConfirmationBody.new body_attrs
+    end
+
+  end
+
+end

data/lib/get_response/confirmation_subject.rb

@@ -0,0 +1,17 @@
+module GetResponse
+
+  # GetResponse confirmation subject. It can be used in campaign settings.
+  class ConfirmationSubject
+
+    attr_reader :id, :content, :language_code
+
+
+    def initialize(attributes)
+      @id = attributes["id"]
+      @content = attributes["content"]
+      @language_code = attributes["language_code"]
+    end
+
+  end
+
+end

data/lib/get_response/confirmation_subject_proxy.rb

@@ -0,0 +1,46 @@
+module GetResponse
+
+  # Proxy class for confirmation subjects operations.
+  class ConfirmationSubjectProxy
+
+    include Conditions
+
+
+    def initialize(connection)
+      @connection = connection
+    end
+
+
+    # Get list of available subjects for confirmation messages. They can be used in campaign settings.
+    # Example:
+    #
+    #   @proxy.all
+    #   @proxy.all(:language_code => {:equals => "pl"})
+    #
+    # @param conditions [Hash] conditions passed to query, empty by default
+    # @return [Array] collection of <tt>ConfirmationSubject</tt> objects returned by API query
+    def all(conditions = {})
+      conditions = parse_conditions(conditions)
+      response = @connection.send_request("get_confirmation_subjects", conditions)["result"]
+      response.inject([]) do |bodies, resp|
+        bodies << ConfirmationSubject.new(resp[1].merge("id" => resp[0]))
+      end
+    end
+
+
+    # Get single confirmation subject based on its <tt>id</tt>. Method can raise
+    #<tt>GetResposne::GetResponseError</tt> exception if no confirmation subject is found.
+    #
+    # @param subject_id [String]
+    # @return [GetResponse::ConfirmationSubject]
+    def find(subject_id)
+      params = {"confirmation_subject" => subject_id}
+      resp = @connection.send_request("get_confirmation_subject", params)["result"]
+      raise GetResponseError.new "Confirmation subject with id '#{subject_id}' not found." if resp.empty?
+      subject_attrs = resp.values[0].merge("id" => resp.keys.first)
+      ConfirmationSubject.new subject_attrs
+    end
+
+  end
+
+end

data/lib/get_response/connection.rb

@@ -47,6 +47,30 @@ module GetResponse
     end
 
 
+    # Method returns proxy to execute all message related operations.
+    #
+    # returns:: GetResponse::MessageProxy
+    def messages
+      @message_proxy ||= GetResponse::MessageProxy.new(self)
+    end
+
+
+    # Method returnx proxy to execute all confirmation body related operations.
+    #
+    # @return [ConfirmationBodyProxy]
+    def confirmation_bodies
+      @confirmation_body_proxy ||= GetResponse::ConfirmationBodyProxy.new(self)
+    end
+
+
+    # Method returnx proxy to execute all confirmation subject related operations.
+    #
+    # @return [ConfirmationSubjectProxy]
+    def confirmation_subjects
+      @confirmation_subject_proxy ||= GetResponse::ConfirmationSubjectProxy.new(self)
+    end
+
+
     # Send request to JSON-RPC service.
     #
     # method::  String

data/lib/get_response/contact.rb

@@ -2,7 +2,7 @@ module GetResponse
 
   # GetResponse contact
   class Contact
-    attr_accessor :campaign, :name, :email, :cycle_day, :ip, :customs
+    attr_accessor :campaign, :name, :email, :cycle_day, :ip, :customs, :created_on, :deleted_on, :reason
     attr_reader :id
 
 
@@ -14,6 +14,9 @@ module GetResponse
       @ip = params["ip"]
       @customs = parse_customs(params["customs"])
       @id = params["id"]
+      @created_on = params["created_on"]
+      @deleted_on = params["deleted_on"]
+      @reason = params["reason"]
       @connection = connection
     end
 
@@ -64,8 +67,10 @@ module GetResponse
     #
     # net_attrs:: Hash
     def update(new_attrs)
-      new_attrs.each_pair { |key, value| self.send(key + "=", value) }
+      # Don't save immediately changes
+      @lazy_save = true
 
+      new_attrs.each_pair { |key, value| self.send(key + "=", value) }
       self.save
     end
 
@@ -121,6 +126,27 @@ module GetResponse
     end
 
 
+    # List dates when the messages were opened by contact. If a contact opened the same message
+    # multiple times, only the oldest date is listed.
+    # returns:: Hash
+    def opens
+      param = {"contact" => @id}
+      @connection.send_request("get_contact_opens", param)["result"]
+    end
+
+
+    # Set contact name. Method can raise <tt>GetResponseError</tt> exception.
+    #
+    # @param value [String] new name value
+    # @return [String] new name value
+    def name=(value)
+      unless @lazy_save
+        @connection.send_request("set_contact_name", { "contact" => @id, "name" => value })["result"]
+      end
+      @name = value
+    end
+
+
     protected
 
 

data/lib/get_response/contact_proxy.rb

@@ -3,6 +3,8 @@ module GetResponse
   # Proxy class for contact related operations.
   class ContactProxy
 
+    include Conditions
+
     def initialize(connection)
       @connection = connection
     end
@@ -33,6 +35,51 @@ module GetResponse
       contact
     end
 
+
+    # Get contacts subscription stats aggregated by date, campaign and contact’s origin.
+    # Example:
+    #
+    #   # get stats for any camapign, any time period
+    #   @contact_proxy.statistics
+    #
+    #   # get stats for selected camapigns, any time period
+    #   @contact_proxy.statistics(:campaigns => ["cmp1", "cmp2"])
+    #
+    #   # get stats for specified date
+    #   @contact_proxy.statistics(:created_on => {:at => Date.today})
+    #   @contact_proxy.statistics(:created_on => {:from => "2011-01-01", :to => "2011-12-30"})
+    #
+    # @param conditions [Hash] conditions for statistics query, empty by default
+    # @return [Hash] collection of aggregated statistics
+    def statistics(conditions = {})
+      conditions = parse_conditions(conditions)
+
+      @connection.send_request("get_contacts_subscription_stats", conditions)["result"]
+    end
+
+
+    # Get deleted contacts.
+    # Example:
+    #
+    #   # get all deleted contacts
+    #   @contact_proxy.deleted
+    #
+    #   # get contacts deleted through api
+    #   @contact_proxy.deleted(:reason => "api")
+    #
+    #   # get deleted contacts from campaign
+    #   @contact_proxy.deleted(:campaigns => ["campaign_id"])
+    #
+    # @param conditions [Hash]
+    # @return [Array]
+    def deleted(conditions = {})
+      conditions = parse_conditions(conditions)
+      response = @connection.send_request("get_contacts_deleted", conditions)
+      response["result"].inject([]) do |contacts, resp|
+        contacts << Contact.new(resp[1].merge("id" => resp[0]), @connection)
+      end
+    end
+
   end
 
 end

data/lib/get_response/from_fields_proxy.rb

@@ -28,6 +28,20 @@ module GetResponse
       FromField.new(attributes.merge("id" => add_result["FROM_FIELD_ID"]))
     end
 
+
+    # Get single from field. Method can raise <tt>GetResponse::GetResponseError</tt> exception when
+    # form field with passed <tt>from_field_id</tt> is not found.
+    #
+    # @param from_field_id [String]
+    # @return [FormField]
+    def find(from_field_id)
+      params = {"account_from_field" => from_field_id}
+      resp = @connection.send_request("get_account_from_field", params)["result"]
+      raise GetResponseError.new "Form field with id '#{from_field_id}' not found." if resp.empty?
+      from_field_attrs = resp.values[0].merge("id" => resp.keys.first)
+      FromField.new(from_field_attrs)
+    end
+
   end
 
 end

metadata

@@ -1,11 +1,12 @@
 --- !ruby/object:Gem::Specification 
 name: getresponse
 version: !ruby/object:Gem::Version 
+  hash: 1
   prerelease: false
   segments: 
   - 0
-  - 4
-  version: "0.4"
+  - 5
+  version: "0.5"
 platform: ruby
 authors: 
 - Sebastian Nowak
@@ -13,16 +14,18 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-06-12 00:00:00 +02:00
+date: 2012-01-02 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: json
   prerelease: false
   requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
     requirements: 
     - - ~>
       - !ruby/object:Gem::Version 
+        hash: 7
         segments: 
         - 1
         - 4
@@ -33,9 +36,11 @@ dependencies:
   name: json_pure
   prerelease: false
   requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
     requirements: 
     - - ~>
       - !ruby/object:Gem::Version 
+        hash: 7
         segments: 
         - 1
         - 4
@@ -46,9 +51,11 @@ dependencies:
   name: rr
   prerelease: false
   requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
     requirements: 
     - - ~>
       - !ruby/object:Gem::Version 
+        hash: 15
         segments: 
         - 1
         - 0
@@ -64,23 +71,27 @@ extensions: []
 extra_rdoc_files: []
 
 files: 
-- lib/get_response.rb
-- lib/get_response/from_field.rb
-- lib/get_response/domain_proxy.rb
-- lib/get_response/contact_proxy.rb
-- lib/get_response/message_proxy.rb
-- lib/get_response/newsletter.rb
 - lib/get_response/account.rb
-- lib/get_response/contact.rb
-- lib/get_response/campaign_proxy.rb
 - lib/get_response/campaign.rb
-- lib/get_response/message.rb
+- lib/get_response/campaign_proxy.rb
+- lib/get_response/conditions.rb
+- lib/get_response/confirmation_body.rb
+- lib/get_response/confirmation_body_proxy.rb
+- lib/get_response/confirmation_subject.rb
+- lib/get_response/confirmation_subject_proxy.rb
 - lib/get_response/connection.rb
+- lib/get_response/contact.rb
+- lib/get_response/contact_proxy.rb
+- lib/get_response/domain.rb
+- lib/get_response/domain_proxy.rb
 - lib/get_response/follow_up.rb
+- lib/get_response/from_field.rb
 - lib/get_response/from_fields_proxy.rb
-- lib/get_response/domain.rb
 - lib/get_response/get_response_error.rb
-- lib/api.rb
+- lib/get_response/message.rb
+- lib/get_response/message_proxy.rb
+- lib/get_response/newsletter.rb
+- lib/get_response.rb
 - README.rdoc
 has_rdoc: true
 homepage: http://dev.getresponse.com
@@ -92,16 +103,20 @@ rdoc_options: []
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
       segments: 
       - 0
       version: "0"
 required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 17
       segments: 
       - 1
       - 3
@@ -110,7 +125,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.3.6
+rubygems_version: 1.3.7
 signing_key: 
 specification_version: 3
 summary: Ruby wrapper for GetResponse API

data/lib/api.rb

@@ -1 +0,0 @@
-API_KEY='d333e12e5019b6940127e82b499d75a5'