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
 
# 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 { |key, value| "<item><fieldid>#{key}</fieldid><value>#{value}</value></item>" }.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.



60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
 
# File 'lib/interspire/api.rb', line 60

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:



80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
 
# File 'lib/interspire/api.rb', line 80

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:



99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
 
# File 'lib/interspire/api.rb', line 99

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.



191
192
193
194
195
196
197
198
199
 
# File 'lib/interspire/api.rb', line 191

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.



135
136
137
138
139
140
141
142
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
 
# File 'lib/interspire/api.rb', line 135

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.



176
177
178
179
180
181
182
183
184
185
 
# File 'lib/interspire/api.rb', line 176

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.



209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
 
# File 'lib/interspire/api.rb', line 209

def update_subscriber_custom_field(subscriber_id, field_id, data)
  xml = %Q[
    <xmlrequest>
      <username>#{@username}</username>
      <usertoken>#{@usertoken}</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