Class: ETAPI::Session

Inherits:
Object
  • Object
show all
Defined in:
lib/etapi/error.rb,
lib/etapi/calls/list.rb,
lib/etapi/calls/email.rb,
lib/etapi/call_builder.rb,
lib/etapi/exact_target.rb,
lib/etapi/calls/tracking.rb,
lib/etapi/calls/subscriber.rb

Constant Summary collapse

DEFAULTS =

set default options

{
  :api_method           => :xml,
  :use_s4               => false,
  :api_uri_xml          => "https://api.dc1.exacttarget.com/integrate.aspx",
  :api_uri_xml_s4       => "https://api.s4.exacttarget.com/integrate.aspx",
  :use_ssl              => true,
}
ALLOWED_USE_S4_OPTIONS =

allowed options

[true, false]

Instance Method Summary collapse

Constructor Details

#initialize(*args) ⇒ Session

initialize a new exact target instance

Raises:

  • (ArgumentError) 


23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
 
# File 'lib/etapi/exact_target.rb', line 23

def initialize(*args)
  
  # merge options with configuration
  options     = args.extract_options!
  @username   = options[:username]    ||= ETAPI.username
  @password   = options[:password]    ||= ETAPI.password
  @use_s4     = options[:use_s4]      ||= ETAPI.use_s4     ||= DEFAULTS[:use_s4]
  @headers    = {"Content-Type" => "application/x-www-form-urlencoded", "Connection" => "close"}
  
  # check for required options
  raise ArgumentError, "* missing :username *" if @username.blank?
  raise ArgumentError, "* missing :password *" if @password.blank?
  raise ArgumentError, "* invalid :use_s4 | options => [true, false] *" unless ALLOWED_USE_S4_OPTIONS.include?(@use_s4)
  
  @api_uri = @use_s4 ? DEFAULTS[:api_uri_xml_s4] : DEFAULTS[:api_uri_xml]
  
  @api_wsdl = @api_uri if @use_s4
  
  # parse uri
  @api_uri   = URI.parse(@api_uri)
  @api_url   = Net::HTTP.new(@api_uri.host, @api_uri.port)
  
  # check for SSL (disabled)
  @api_url.use_ssl = options[:use_ssl] ||= DEFAULTS[:use_ssl]
  
end

Instance Method Details

#build_call(type, method, *args) ⇒ Object 



5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
 
# File 'lib/etapi/call_builder.rb', line 5

def build_call(type, method, *args)
  
  options         = args.extract_options!
  ignore_parse  = options[:ignore_parse] || false
  
  data = ""
  xml = Builder::XmlMarkup.new(:target => data, :indent => 2)
  xml.instruct!
  xml.exacttarget do
    xml.authorization do
      xml.username @username
      xml.password @password
    end
    xml.system do
      xml.system_name type
      xml.action method
      for parameter in @parameters
        if parameter[0] == "values"
          xml.values do
            parameter[1].each do |key, value|
              eval("xml.#{key.gsub(/\s/, '__')} '#{value}'")
            end
          end
        else
          if parameter[1].is_a?(Hash)
            xml.tag!(parameter[0]) do
              parameter[1].each do |key, value|
                eval("xml.#{key.gsub(/\s/, '__')} '#{value}'")
              end
            end
          else
            eval("xml.#{parameter[0]} '#{parameter[1]}'")
          end
        end
      end
    end
  end
  
  data_encoded = "qf=xml&xml=" + url_encode(data)
  response = @api_url.post(@api_uri.path, data_encoded, @headers.merge('Content-length' => data_encoded.length.to_s))
  check_response(response)
  ignore_parse ? response.read_body : Nokogiri::XML::Document.parse(response.read_body)
  
end

#check_required(required_options) ⇒ Object 



25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
 
# File 'lib/etapi/error.rb', line 25

def check_required(required_options)
  missing_options = []
  
  for option in required_options
    missing_options << ":#{option}" if eval("@#{option}.blank?")
  end
  
  if !missing_options.blank?
    if ETAPI.log?
      ETAPI.log("    Code:    ETAPI\n    Message: missing #{missing_options.join(', ')}")
    elsif ETAPI.raise_errors?
      raise(ArgumentError, "\n\n    Code:    ETAPI\n    Message: missing #{missing_options.join(', ')}\n\n")
    end
    return false
  end
  
  return true
end

#check_response(response) ⇒ Object

Raises:

  • (Error) 


5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
 
# File 'lib/etapi/error.rb', line 5

def check_response(response)
  
  raise Error.new(-1, 'Network error') if response.class != Net::HTTPOK
  
  response = Nokogiri::XML::Document.parse(response.body)
  
  error_code  = response.xpath("//error")
  error_msg   = response.xpath("//error_description")
  
  if !error_code.blank? && !error_msg.blank?
    if ETAPI.raise_errors?
      raise(RuntimeError, "\n\n    Code:    #{error_code.text.to_i}\n    Message: #{error_msg.text}\n\n")
    else
      ETAPI.log("    Code:    #{error_code.text.to_i}\n    Message: #{error_msg.text}") if ETAPI.log?
      return false
    end
  end
  
end

#email_retrieve_body(*args) ⇒ Object 



5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
 
# File 'lib/etapi/calls/email.rb', line 5

def email_retrieve_body(*args)
  
  # options
  options         = args.extract_options!
  @email_id       = options[:email_id]
  
  # check for required options
  required_options = ["email_id"]
  return false unless check_required(required_options)
  
  # merge parameters and values
  type        = "email"
  method      = "retrieve"
  @parameters = {
    "search_type"   => "emailid",
    "sub_action"    => "htmlemail",
    "search_value"  => @email_id,
    "search_value2" => "",
    "search_value3" => "",
  }
  
  response = build_call(type, method)
  response.xpath("//htmlbody").text rescue false
  
end

#list_retrieve_subscribers(*args) ⇒ Object 



5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
 
# File 'lib/etapi/calls/list.rb', line 5

def list_retrieve_subscribers(*args)
  
  # options
  options         = args.extract_options!
  @list_id        = options[:list_id]
  
  # check for required options
  required_options = ["list_id"]
  return false unless check_required(required_options)
  
  # merge parameters and values
  @parameters = {
    "search_type"   => "listid",
    "search_value"  => @list_id
  }
  
  response = build_call("list", "retrieve_sub", {:parse_response => false})
  Hash.from_xml(response)['exacttarget']['system']['list']['subscribers'].first[1] rescue false
  
end

#subscriber_add(*args) ⇒ Object 



5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
 
# File 'lib/etapi/calls/subscriber.rb', line 5

def subscriber_add(*args)
  
  # options
  options           = args.extract_options!
  @list_id          = options[:list_id] ||= nil
  @email            = options[:email]
  @values           = options[:values] ||= {}
  @account_id       = options[:account_id]
  
  # check for required options
  required_options = ["email", "list_id"]
  return false unless check_required(required_options)
  
  # update options
  @values.merge!({"Email Address" => @email, "status" => "active"})
  
  # merge parameters and values
  @parameters = {
    "search_type"   => "listid",
    "search_value"  => @list_id,
    "search_value2" => "",
    "values"        => @values
  }
  
  response = build_call("subscriber", "add")
  response.xpath("//subscriber_description").text.to_i rescue false
  
end

#subscriber_delete(*args) ⇒ Object 



85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
 
# File 'lib/etapi/calls/subscriber.rb', line 85

def subscriber_delete(*args)
  
  # options
  options         = args.extract_options!
  @subscriber_id  = options[:subscriber_id]
  
  # check for required options
  required_options = ["subscriber_id"]
  return false unless check_required(required_options)
  
  # merge parameters and values
  @parameters = {
    "search_type"   => "subid",
    "search_value"  => @subscriber_id,
    "search_value2" => ""
  }
  
  response = build_call("subscriber", "delete")
  response.xpath("//subscriber_info").text.blank? ? false : true rescue false
  
end

#subscriber_edit(*args) ⇒ Object 



34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
 
# File 'lib/etapi/calls/subscriber.rb', line 34

def subscriber_edit(*args)
  
  # options
  options         = args.extract_options!
  @subscriber_id  = options[:subscriber_id]
  @values         = options[:values] ||= {}
  @account_id     = options[:account_id] ||= ""
  
  # check for required options
  required_options = ["subscriber_id"]
  return false unless check_required(required_options)
  
  # merge parameters and values
  @parameters = {
    "search_type"   => "subid",
    "search_value"  => @subscriber_id,
    "search_value2" => "",
    "values"        => @values
  }
  
  response = build_call("subscriber", "edit")
  response.xpath("//subscriber_description").text == @subscriber_id.to_s rescue false
  
end

#subscriber_edit_from_list(*args) ⇒ Object 



59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
 
# File 'lib/etapi/calls/subscriber.rb', line 59

def subscriber_edit_from_list(*args)
  
  # options
  options         = args.extract_options!
  @list_id        = options[:list_id]
  @email          = options[:email]
  @values         = options[:values] ||= {}
  @account_id     = options[:account_id] ||= ""
  
  # check for required options
  required_options = ["list_id", "email"]
  return false unless check_required(required_options)
  
  # merge parameters and values
  @parameters = {
    "search_type"   => "listid",
    "search_value"  => @list_id,
    "search_value2" => @email,
    "values"        => @values
  }
  
  response = build_call("subscriber", "edit")
  response.xpath("//subscriber_description").text.blank? && response.xpath("//subscriber_info").text.blank? ? false : true rescue false
  
end

#subscriber_remove_from_list(*args) ⇒ Object 



107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
 
# File 'lib/etapi/calls/subscriber.rb', line 107

def subscriber_remove_from_list(*args)
  
  # options
  options         = args.extract_options!
  @list_id        = options[:list_id]
  @email          = options[:email]
  
  # check for required options
  required_options = ["list_id", "email"]
  return false unless check_required(required_options)
  
  # merge parameters and values
  @parameters = {
    "search_type"   => "listid",
    "search_value"  => @list_id,
    "search_value2" => @email
  }
  
  response = build_call("subscriber", "delete")
  response.xpath("//subscriber_info").text.blank? ? false : true rescue false
  
end

#subscriber_retrieve(*args) ⇒ Object 



153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
 
# File 'lib/etapi/calls/subscriber.rb', line 153

def subscriber_retrieve(*args)
  
  # options
  options         = args.extract_options!
  @subscriber_id  = options[:subscriber_id]
  @account_id     = options[:account_id] ||= ""
  
  # check for required options
  required_options = ["subscriber_id"]
  return false unless check_required(required_options)
  
  # merge parameters and values
  @parameters = {
    "search_type"   => "subid",
    "search_value"  => @subscriber_id,
    "search_value2" => ""
  }
  
  response = build_call("subscriber", "retrieve", {:ignore_parse => true})
  Hash.from_xml(response)['exacttarget']['system']['subscriber'].first rescue false
  
end

#subscriber_unsubscribe_master(*args) ⇒ Object 



130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
 
# File 'lib/etapi/calls/subscriber.rb', line 130

def subscriber_unsubscribe_master(*args)
  
  # options
  options         = args.extract_options!
  @email          = options[:email]
  
  # check for required options
  required_options = ["email"]
  return false unless check_required(required_options)
  
  # merge parameters and values
  @parameters = {
    "search_type"   => "emailaddress",
    "search_value"  => {
      "emailaddress" => @email
    }
  }
  
  response = build_call("subscriber", "masterunsub")
  response.xpath("//emailaddress").text == @email ? true : false rescue false
  
end

#tracking_retrieve(*args) ⇒ Object 



5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
 
# File 'lib/etapi/calls/tracking.rb', line 5

def tracking_retrieve(*args)
  
  # options
  options         = args.extract_options!
  @job_id         = options[:job_id]
  
  # check for required options
  required_options = ["job_id"]
  return false unless check_required(required_options)
  
  # merge parameters and values
  type        = "tracking"
  method      = "retrieve"
  @parameters = {
    "search_type"   => "jobID",
    "sub_action"    => "summary",
    "search_value"  => @job_id,
    "search_value2" => ""
  }
  
  response = build_call(type, method, {:parse_response => false})
  Hash.from_xml(response)['exacttarget']['system']['tracking']['emailSummary'] rescue false
  
end