Class: Interspire::API

Inherits:
Object
  • Object
show all
Defined in:
lib/interspire/api.rb

Overview

TODO: The methods expecting a list ID should also accept a ContactList object.

Instance Method Summary collapse

Constructor Details

#initialize(api_url, user, token) ⇒ Inter::API

Returns An instance of the Interspire API for the given parameters.

Parameters:

  • api_url (String) —

    The XML API of your Interspire installation; ex. example.com/xml.php

  • user (String) —

    The Interspire user’s login name.

  • token (String) —

    The Interspire user’s API token.



16
17
18
19
20
 
# File 'lib/interspire/api.rb', line 16

def initialize(api_url, user, token)
  @api_url = api_url
  @user    = user
  @token   = token
end

Instance Method Details

#add_subscriber(list_id, email, confirmed = false, format = 'html', custom_fields = {}) ⇒ Integer

Returns the subscriber’s ID upon success.

Parameters:

  • list_id (Integer) —

    The id of the contact list.

  • email (String) —

    The subscriber’s email address.

  • confirmed (boolean) (defaults to: false) —

    (optional) true if the subscriber should be set as confirmed; defaults to false.

  • format (String) (defaults to: 'html') —

    (optional) The email format; either html or text; defaults to html.

  • custom_fields (Hash) (defaults to: {}) —

    (optional) Any custom fields for the subscriber (e.g. => ‘Banana’, 2 => ‘Hamster’)

Returns:

  • (Integer) —

    Returns the subscriber’s ID upon success.



29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
 
# File 'lib/interspire/api.rb', line 29

def add_subscriber(list_id, email, confirmed = false, format = 'html', custom_fields = {})
  custom_fields_xml = custom_fields.map do |key, value|
    output = "<item><fieldid>#{key}</fieldid>"
    if value.is_a? Array
      value.each{|v| output << "<value>#{v}</value>"}
    else
      output << "<value>#{value}</value>"
    end
    output << "</item>"
  end.join
  
  xml = %Q[
    <xmlrequest>
      <username>#{@user}</username>
      <usertoken>#{@token}</usertoken>
      <requesttype>subscribers</requesttype>
      <requestmethod>AddSubscriberToList</requestmethod>
      <details>
        <emailaddress>#{email}</emailaddress>
        <mailinglist>#{list_id}</mailinglist>
        <format>#{format}</format>
        <confirmed>#{confirmed}</confirmed>
        <customfields>
          #{custom_fields_xml}
        </customfields>
      </details>
    </xmlrequest>
  ]

  response = get_response(xml)

  if success?(response)
    response.xpath('response/data').first.content.to_i
  else
    error!(response)
  end
end

#authenticated? ⇒ boolean

Returns true if the user is authenticated.

Returns:

  • (boolean) —

    Returns true if the user is authenticated.



68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
 
# File 'lib/interspire/api.rb', line 68

def authenticated?
  xml = %Q[
    <xmlrequest>
      <username>#{@user}</username>
      <usertoken>#{@token}</usertoken>
      <requesttype>authentication</requesttype>
      <requestmethod>xmlapitest</requestmethod>
      <details>
      </details>
    </xmlrequest>
  ]

  response = get_response(xml)
  success?(response)
end

#delete_subscriber(list_id, email) ⇒ boolean

Returns true upon success or raises an InterspireException on failure.

Parameters:

  • list_id (Integer) —

    The id of the contact list.

  • email (String) —

    The subscriber’s email address.

Returns:



88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
 
# File 'lib/interspire/api.rb', line 88

def delete_subscriber(list_id, email)
  xml = %Q[
    <xmlrequest>
      <username>#{@user}</username>
      <usertoken>#{@token}</usertoken>
      <requesttype>subscribers</requesttype>
      <requestmethod>DeleteSubscriber</requestmethod>
      <details>
        <list>#{list_id}</list>
        <emailaddress>#{email}</emailaddress>
      </details>
    </xmlrequest>
  ]

  response = get_response(xml)
  success?(response) ? true : error!(response)
end

#get_lists ⇒ Array

Returns An Array of ContactList objects.

Returns:



107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
 
# File 'lib/interspire/api.rb', line 107

def get_lists
  xml = %Q[
    <xmlrequest>
      <username>#{@user}</username>
      <usertoken>#{@token}</usertoken>
      <requesttype>user</requesttype>
      <requestmethod>GetLists</requestmethod>
      <details>
      </details>
    </xmlrequest>
  ]

  response = get_response(xml)

  if success?(response)
    lists = []
    response.xpath('response/data/item').each do |list|
      lists << Interspire::ContactList.new({
        id: list.xpath('listid').first.content,
        name: list.xpath('name').first.content,
        subscribe_count: list.xpath('subscribecount').first.content,
        unsubscribe_count: list.xpath('unsubscribecount').first.content,
        auto_responder_count: list.xpath('autorespondercount').first.content,
      })
    end

    lists
  else
    error!(response)
  end
end

#get_subscriber_id(list_id, email) ⇒ Integer

Returns the subscriber’s ID upon success.

Parameters:

  • list_id (Integer) —

    The ID of the contact list.

  • email (String) —

    The subscriber’s email address.

Returns:

  • (Integer) —

    Returns the subscriber’s ID upon success.



199
200
201
202
203
204
205
206
207
 
# File 'lib/interspire/api.rb', line 199

def get_subscriber_id(list_id, email)
  response = check_contact_list(list_id, email)

  if success?(response)
    response.xpath('response/data').first.content.to_i
  else
    error!(response)
  end
end

#get_subscribers(list_id, email = '') ⇒ Hash

Returns A Hash containing a :count key and a :subscribers Array with Subscriber objects.

Parameters:

  • list_id (Integer) —

    The ID of the contact list.

  • email (String) (defaults to: '') —

    The domain (including ‘@’) of subscribers to filter by; ex. ‘@example.com’ would only return subscribers like ‘[email protected]’; defaults to an empty String (returns all subscribers).

Returns:

  • (Hash) —

    A Hash containing a :count key and a :subscribers Array with Subscriber objects.



143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
 
# File 'lib/interspire/api.rb', line 143

def get_subscribers(list_id, email = '')
  xml = %Q[
    <xmlrequest>
      <username>#{@user}</username>
      <usertoken>#{@token}</usertoken>
      <requesttype>subscribers</requesttype>
      <requestmethod>GetSubscribers</requestmethod>
      <details>
        <searchinfo>
          <List>#{list_id}</List>
          <Email>#{email}</Email>
        </searchinfo>
      </details>
    </xmlrequest>
  ]

  response = get_response(xml)

  if success?(response)
    subscribers = {}
    subscribers[:count] = response.xpath('response/data/count').first.content.to_i
    subscribers[:subscribers] = []

    response.xpath('response/data').each do |data|
      data.xpath('subscriberlist/item').each do |item|
        id = item.xpath('subscriberid').first.content.to_i
        email = item.xpath('emailaddress').first.content
        subscribers[:subscribers] << Interspire::Subscriber.new(id, email)
      end
    end

    subscribers
  else
    error!(response)
  end
end

#in_contact_list?(list_id, email) ⇒ boolean

Returns true or false if the email is on the given contact list.

Parameters:

  • list_id (Integer) —

    The ID of the contact list.

  • email (String) —

    The subscriber’s email address.

Returns:

  • (boolean) —

    true or false if the email is on the given contact list.



184
185
186
187
188
189
190
191
192
193
 
# File 'lib/interspire/api.rb', line 184

def in_contact_list?(list_id, email)
  response = check_contact_list(list_id, email)

  if success?(response)
    # The 'data' element will contain the subscriber ID.
    ! response.xpath('response/data').first.content.empty?
  else
    false
  end
end

#update_subscriber_custom_field(subscriber_id, field_id, data) ⇒ boolean

This is an undocumented API function. Refer to the ‘xml_updatesubscriber.php’ attachment on this page: www.interspire.com/support/kb/questions/1217/Email+Marketer+XML+API+usage+and+examples

Parameters:

  • subscriber_id (Integer) —

    The ID of the subscriber.

  • field_id (Integer) —

    The ID of the custom field

  • data (String) —

    The data of the field

Returns:

  • (boolean) —

    Returns true if the field was updated.



217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
 
# File 'lib/interspire/api.rb', line 217

def update_subscriber_custom_field(subscriber_id, field_id, data)
  xml = %Q[
    <xmlrequest>
      <username>#{@user}</username>
      <usertoken>#{@token}</usertoken>
      <requesttype>subscribers</requesttype>
      <requestmethod>SaveSubscriberCustomField</requestmethod>
      <details>
        <subscriberids>
          <id>#{subscriber_id}</id>
        </subscriberids>
        <fieldid>#{field_id}</fieldid>
        <data>#{data}</data>
      </details>
    </xmlrequest>
  ]

  response = get_response(xml)
  success?(response)
end