campaigning 0.15.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,53 @@
1
+ gem "soap4r", "~> 1.5.0"
2
+ require File.expand_path(File.dirname(__FILE__)) + '/template.rb'
3
+ require File.expand_path(File.dirname(__FILE__)) + '/client.rb'
4
+ require File.expand_path(File.dirname(__FILE__)) + '/campaign.rb'
5
+ require File.expand_path(File.dirname(__FILE__)) + '/subscriber.rb'
6
+ require File.expand_path(File.dirname(__FILE__)) + '/list.rb'
7
+ require File.expand_path(File.dirname(__FILE__)) + '/module_mixin.rb'
8
+
9
+ module Campaigning
10
+ include ModuleMixin
11
+
12
+ ##
13
+ #Gets the server system time for your time zone.
14
+ #This is handy for when you are syncing your {Campaign Monitor}[http://www.campaignmonitor.com] lists with some other in-house list,
15
+ #allowing you accurately determine the time on our server when you carry out the synchronization.
16
+ #
17
+ #Aviable _opts_ arguments are:
18
+ # * :apiKey - optional API key to use to make request. Will use CAMPAIGN_MONITOR_API_KEY if not set.
19
+ def self.system_date(opts={})
20
+ response = @@soap.getSystemDate(:apiKey => opts[:apiKey] || CAMPAIGN_MONITOR_API_KEY)
21
+ dateTime = handle_response response.user_GetSystemDateResult
22
+ end
23
+
24
+ ##
25
+ #This method returns an Array of Strings representing all the available timezones.
26
+ #
27
+ #Aviable _opts_ arguments are:
28
+ # * :apiKey - optional API key to use to make request. Will use CAMPAIGN_MONITOR_API_KEY if not set.
29
+ def self.timezones(opts={})
30
+ handle_response @@soap.getTimezones(:apiKey => opts[:apiKey] || CAMPAIGN_MONITOR_API_KEY).user_GetTimezonesResult
31
+ end
32
+
33
+ ##
34
+ #This method returns an Array of Strings representing all the available countries.
35
+ #
36
+ #Aviable _opts_ arguments are:
37
+ # * :apiKey - optional API key to use to make request. Will use CAMPAIGN_MONITOR_API_KEY if not set.
38
+ def self.countries(opts={})
39
+ response = @@soap.getCountries(:apiKey => opts[:apiKey] || CAMPAIGN_MONITOR_API_KEY)
40
+ dateTime = handle_response response.user_GetCountriesResult
41
+ end
42
+
43
+ ##
44
+ #This method turns the API debug mode to :on and :off, which will display at the console all SOAP requests made to the API server.
45
+ #
46
+ def self.set_debug_mode(option)
47
+ option == :on ? @@soap.wiredump_dev = STDERR : @@soap.wiredump_dev = false
48
+ end
49
+
50
+ def self.set_endpoint_url(endpoint_url)
51
+ @@soap = Campaigning::ApiSoap.new(endpoint_url)
52
+ end
53
+ end
@@ -0,0 +1,335 @@
1
+ # Client is defined in default.rb which is automatically generated.
2
+ # In this file we add additional methods to the Client class.
3
+ require File.expand_path(File.dirname(__FILE__)) + '/module_mixin'
4
+
5
+ module Campaigning
6
+ class Client
7
+ include ModuleMixin
8
+ attr_accessor :clientID
9
+ attr_accessor :name
10
+
11
+ def initialize(clientID = nil, name = nil, opts={})
12
+ @apiKey = opts[:apiKey] || CAMPAIGN_MONITOR_API_KEY
13
+ @clientID = clientID
14
+ @name = name
15
+ end
16
+
17
+ #Gets a list of all templates for a client.
18
+ #
19
+ #*Return*:
20
+ #
21
+ #*Success*: Upon a successful call, this method will return a collection of Campaigning::Template objects.
22
+ #
23
+ #*Error*: An Exception containing the cause of the error will be raised.
24
+ def templates
25
+ response = @@soap.getClientTemplates(:apiKey => @apiKey, :clientID => @clientID)
26
+ templates = handle_response response.client_GetTemplatesResult
27
+ templates.collect {|template| Template.new(template.templateID, template.name, template.previewURL, template.screenshotURL, :apiKey=> @apiKey)}
28
+ end
29
+
30
+
31
+ #Gets a list of all subscriber lists for a client.
32
+ #
33
+ #*Return*:
34
+ #
35
+ #*Success*: Upon a successful call, this method will return a collection of Campaigning::List objects.
36
+ #
37
+ #*Error*: An Exception containing the cause of the error will be raised.
38
+ def lists
39
+ response = @@soap.getClientLists(:apiKey => @apiKey, :clientID => @clientID)
40
+ lists = handle_response response.client_GetListsResult
41
+ lists.collect {|list| List.new(list.listID, list.name, :apiKey=> @apiKey)}
42
+ end
43
+
44
+ #This method find a List by a given name
45
+ #
46
+ #*Return*:
47
+ #
48
+ #*Success*:
49
+ #
50
+ #List FOUND: If it found any client with the given name it will return a Campaigning::List object containing the found list.
51
+ #
52
+ #List NOT FOUND: If it doesn't found a list with the given name it will return +nil+ .
53
+ #
54
+ #*Error*: An Exception containing the cause of the error will be raised.
55
+ def find_list_by_name(list_name)
56
+ lists.find {|list| list_name == list.name}
57
+ end
58
+
59
+ #This method find a Client by a given name
60
+ #
61
+ #Aviable _opts_ arguments are:
62
+ # * :apiKey - optional API key to use to make request. Will use CAMPAIGN_MONITOR_API_KEY if not set.
63
+ #
64
+ #*Return*:
65
+ #
66
+ #Client FOUND: If it found any client with the given name it will return a Campaigning::Client object containing the found client.
67
+ #
68
+ #Client NOT FOUND: If it doesn't found a client with the given name it will return +nil+ .
69
+ #
70
+ #*Error*: An Exception containing the cause of the error will be raised.
71
+ #-- TODO: Refactor this method and increase performance?
72
+ #-- TODO: Tha campaign monitor permit two users with the same name, what to do?
73
+ def self.find_by_name(name, opts={})
74
+ client_list = Client.get_all_clients(opts)
75
+ client_found = client_list.find {|client| name == client.name}
76
+ Client.new(client_found.clientID, client_found.name, :apiKey=> opts[:apiKey]) if client_found
77
+ end
78
+
79
+ #Gets all clients for a given user (CAMPAIGN_MONITOR_API_KEY).
80
+ #
81
+ #Aviable _opts_ arguments are:
82
+ # * :apiKey - optional API key to use to make request. Will use CAMPAIGN_MONITOR_API_KEY if not set.
83
+ #
84
+ #*Return*:
85
+ #
86
+ #*Success*: Upon a successful call, this method will return a collection of Campaigning::Client objects.
87
+ #
88
+ #*Error*: An Exception containing the cause of the error will be raised.
89
+ def self.get_all_clients(opts={})
90
+ response = @@soap.getClients(:apiKey => opts[:apiKey] || CAMPAIGN_MONITOR_API_KEY)
91
+ clients = handle_response response.user_GetClientsResult
92
+ clients.collect {|client| Client.new(client.clientID, client.name, :apiKey=> opts[:apiKey])}
93
+ end
94
+
95
+ #This method creates a brand new client with no access to the application.
96
+ #By default a new client has no direct access to the application. Access and billing settings (if needed) must be set by
97
+ #means of a subsequent call to Campaigning::Client#update_access_and_billing!.
98
+ #
99
+ #Available _params_ argument are:
100
+ # * :companyName - The client company name.
101
+ # * :contactName - The personal name of the principle contact for this client.
102
+ # * :emailAddress - An email address to which this client will be sent application-related emails.
103
+ # * :country - This client's country. A valid country list is available in http://www.campaignmonitor.com/api/countries/ or by
104
+ # using the API procedure Campaigning.countries
105
+ # * :timezone - Client timezone for tracking and reporting data. A valid timezone list is available here or by using the API
106
+ # procedure Campaigning.timezones.
107
+ # * :apiKey - optional API key to use to make request. Will use CAMPAIGN_MONITOR_API_KEY if not set.
108
+ #
109
+ #*Return*:
110
+ #
111
+ #*Success*: Upon a successful call, this method will return a Campaigning::Client object representing the newly created client.
112
+ #
113
+ #*Error*: An Exception containing the cause of the error will be raised.
114
+ def self.create!(params)
115
+ response = @@soap.createClient(
116
+ :apiKey => params[:apiKey] || CAMPAIGN_MONITOR_API_KEY,
117
+ :companyName => params[:companyName],
118
+ :contactName => params[:contactName],
119
+ :emailAddress => params[:emailAddress],
120
+ :country => params[:country],
121
+ :timezone => params[:timezone]
122
+ )
123
+ Client.new( handle_response(response.client_CreateResult), params[:companyName], :apiKey=> params[:apiKey] )
124
+ end
125
+
126
+ #Deletes a client from your account.
127
+ #
128
+ #*Return*:
129
+ #
130
+ #*Success*: Upon a successful call, this method will return a Campaigning::Result object wich consists of a +code+ and +message+ fields
131
+ #containing a successful message.
132
+ #
133
+ #*Error*: An Exception containing the cause of the error will be raised.
134
+ def delete!
135
+ response = Client.delete!(@clientID, :apiKey=> @apiKey)
136
+ self.clientID, self.name = nil
137
+ response
138
+ end
139
+
140
+ #Deletes a client from your account.
141
+ #
142
+ #Aviable _opts_ arguments are:
143
+ # * :apiKey - optional API key to use to make request. Will use CAMPAIGN_MONITOR_API_KEY if not set.
144
+ #
145
+ #*Return*:
146
+ #
147
+ #*Success*: Upon a successful call, this method will return a Campaigning::Result object wich consists of a +code+ and +message+ fields
148
+ #containing a successful message.
149
+ #
150
+ #*Error*: An Exception containing the cause of the error will be raised.
151
+ def self.delete!(client_id, opts={})
152
+ response = @@soap.deleteClient(:apiKey => opts[:apiKey] || CAMPAIGN_MONITOR_API_KEY, :clientID => client_id)
153
+ handle_response response.client_DeleteResult
154
+ end
155
+
156
+ #Gets a list of all subscriber segments for a client.
157
+ #
158
+ #*Return*:
159
+ #
160
+ #*Success*: Upon a successful call, this method will return a collection of Campaigning::List objects, each of which consists of the ListID
161
+ #for the parent list and Segment Name for each segment for a client.
162
+ #
163
+ #*Error*: An Exception containing the cause of the error will be raised.
164
+ def segments # TODO: Verify the type return for this method.
165
+ response = @@soap.getClientSegments(:apiKey => @apiKey, :clientID => @clientID )
166
+ handle_response response.client_GetSegmentsResult
167
+ end
168
+
169
+ #This method finds campaigns by a given subject, since the subject isn't unique, it returns an collection of
170
+ #Campaigning::Campaign object.
171
+ #
172
+ #*Return*:
173
+ #
174
+ #*Success*: Upon a successful call, this method will return a collection of Campaigning::Campaign objects.
175
+ #
176
+ #Campaign FOUND: If it found any campaign with the given subject it will return a collection of Campaigning::Campaign that match the criteria.
177
+ #
178
+ #Campaign NOT FOUND: If it doesn't found a campaign with the given subject it will return an empty array.
179
+ #
180
+ #*Error*: An Exception containing the cause of the error will be raised.
181
+ def find_campaigns_by_subject(subject)#-- TODO: Refactor this method
182
+ arr = []
183
+ #return campaigns.find {|campaign| subject == campaign.subject} if params[:single]
184
+ campaigns.each { |campaign| arr << campaign if campaign.subject == subject }
185
+ arr
186
+ end
187
+
188
+ #Gets a list of all campaigns that have been sent for a client.
189
+ #
190
+ #*Return*:
191
+ #
192
+ #*Success*: Upon a successful call, this method will return a collection of Campaigning::Campaign objects.
193
+ #
194
+ #*Error*: An Exception containing the cause of the error will be raised.
195
+ def campaigns
196
+ response = @@soap.getClientCampaigns(:apiKey => @apiKey, :clientID => @clientID )
197
+ campaign_list = handle_response response.client_GetCampaignsResult
198
+ campaign_list.collect do |campaign|
199
+ Campaign.new(campaign.campaignID, campaign.subject, campaign.name, campaign.sentDate, campaign.totalRecipients, :apiKey=> @apiKey)
200
+ end
201
+ end
202
+
203
+ #This method gets the complete account and billing details for a particular client.
204
+ #
205
+ #Example of usage:
206
+ # client_details = client_obj.details
207
+ # basic_details = client_details.basicDetails
208
+ # access_and_billing_details = client_details.accessAndBilling
209
+ # puts "Basic details:"
210
+ # puts "Client ID: #{basic_details.clientID}\n
211
+ # Company: #{basic_details.companyName}\n
212
+ # Contact: #{basic_details.contactName}\n
213
+ # Country: #{basic_details.country}\n
214
+ # Timezone: #{basic_details.timezone}"
215
+ #
216
+ # puts "Access and Billing Details:"
217
+ # puts "Username: #{access_and_billing_details.username}\n
218
+ # Password: #{access_and_billing_details.password}\n
219
+ # Billing Type: #{access_and_billing_details.billingType}\n
220
+ # Currency: #{access_and_billing_details.currency}\n
221
+ # Delivery Fee: #{access_and_billing_details.deliveryFee}\n
222
+ # Cost per Recipient: #{access_and_billing_details.costPerRecipient}\n
223
+ # Design and Span test Fee: #{access_and_billing_details.designAndSpamTestFee}\n
224
+ # Access Level: #{access_and_billing_details.accessLevel}"
225
+ #
226
+ #*Return*:
227
+ #
228
+ #*Success*: A successful call to this method will return a ClientDetail object, comprised of ClientBasicDetails
229
+ #and ClientAccessAndBilling.
230
+ #
231
+ #*Error*: An Exception containing the cause of the error will be raised.
232
+ def details
233
+ response = @@soap.getClientDetail(:apiKey => @apiKey, :clientID => @clientID )
234
+ handle_response response.client_GetDetailResult
235
+ end
236
+
237
+ #Gets all subscribers in the client-wide suppression list.
238
+ #
239
+ #*Return*:
240
+ #
241
+ #*Success*: Upon a successful call, this method will return a collection of Subscriber objects.
242
+ #
243
+ #*Error*: An Exception containing the cause of the error will be raised.
244
+ def suppression_list
245
+ response = @@soap.getClientSuppressionList(:apiKey => @apiKey, :clientID => @clientID )
246
+ handle_response response.client_GetSuppressionListResult
247
+ end
248
+
249
+ #Update the access and billing settings of an existing client, leaving the basic details untouched.
250
+ #
251
+ #Here's a list of all the parameters you'll need to pass to the Campaigning::Client#update_access_and_billing! method. Only the :+access_level+ parameter
252
+ #is required for all calls. The relevance and necessity of the other parameters depends on the chosen AccessLevel (and BillingType),
253
+ #and will be fully described along with each parameter.
254
+ #
255
+ #Available _params_ argument are:
256
+ # * :accessLevel - An integer describing the client's ability to access different areas of the application. Influences the significance
257
+ # and requirements of the following parameters. See http://www.campaignmonitor.com/api/method/client-updateaccessandbilling/#accesslevels
258
+ # for a full description of available levels.
259
+ # * :username - Client login username. Not required and ignored if AccessLevel is set to 0.
260
+ # * :password - Client login password. Not required and ignored if AccessLevel is set to 0.
261
+ # * :billingType - Client billing type, only required if :accessLevel is set to allow the client to create and send campaigns
262
+ # * :currency - Billing currency for this client, only required if :billingType is set to either ClientPaysAtStandardRate or
263
+ # ClientPaysWithMarkup. See full details: http://www.campaignmonitor.com/api/method/client-updateaccessandbilling/#currencies.
264
+ # * :deliveryFee - Flat rate delivery fee to be charged to the client for each campaign sent, expressed in the chosen currency's
265
+ # major unit, but without the currency symbol (for example, sending "6.5" means "$6.50" if USD is used). Only
266
+ # required if BillingType is set to ClientPaysWithMarkup, in which case it should be at least equal to the standard rate.
267
+ # Further detail is available at http://help.campaignmonitor.com/topic.aspx?t=118.
268
+ # * :costPerRecipient - Additional cost added to the campaign for each email address the campaign is sent to, expressed in the chosen
269
+ # currency's minor unit (for example, sending "1.5" means 1.5 cents per email address if USD is used). Only required
270
+ # if BillingType is set to ClientPaysWithMarkup, in which case it should be at least equal to the standard cost/recipient
271
+ # rate. Further detail is available at http://help.campaignmonitor.com/topic.aspx?t=118.
272
+ # * :designAndSpamTestFee - Expressed in the chosen currency's major unit (for example, sending "10" means "$10" if USD is used). Only required
273
+ # if BillingType is set to ClientPaysWithMarkup and client has access to design and spam tests, in which case the fee
274
+ # should be equal to or higher than the standard rate (identical to the standard DeliveryFee for that currency).
275
+ #
276
+ #
277
+ #
278
+ #Please note that for reasons of security there is no way to set a client's credit card details via the API. It will have to be done in the application.
279
+ #
280
+ #*Return*:
281
+ #
282
+ #*Success*: Upon a successful call, this method will return a Campaigning::Result object wich consists of a +code+ and +message+ fields
283
+ #containing a successful message.
284
+ #
285
+ #*Error*: An Exception containing the cause of the error will be raised.
286
+ def update_access_and_billing!(params)
287
+ response = @@soap.updateClientAccessAndBilling(
288
+ :apiKey => @apiKey,
289
+ :clientID => @clientID,
290
+ :accessLevel => params[:accessLevel],
291
+ :username => params.fetch(:username, ""),
292
+ :password => params.fetch(:password, ""),
293
+ :billingType => params.fetch(:billingType, ""),
294
+ :currency => params.fetch(:currency, ""),
295
+ :deliveryFee => params.fetch(:deliveryFee, ""),
296
+ :costPerRecipient => params.fetch(:costPerRecipient, ""),
297
+ :designAndSpamTestFee => params.fetch(:designAndSpamTestFee, "")
298
+ )
299
+ handle_response response.client_UpdateAccessAndBillingResult
300
+ end
301
+
302
+ #Updates the basic details of an existing client.
303
+ #If you wish to change only some details, the others must be included as they currently are. Please note that the client's existing
304
+ #access and billing details will remain unchanged by a call to this method.
305
+ #
306
+ #Available _params_ argument are:
307
+ # * :companyName - The client company name.
308
+ # * :contactName - The personal name of the principle contact for this client.
309
+ # * :emailAddress - An email address to which this client will be sent application-related emails.
310
+ # * :country - This client's country.
311
+ # * :timezone - Client timezone for tracking and reporting data. Valid timezone strings are obtainable by means of the
312
+ # API procedure Campaigning.timezones.
313
+ #
314
+ #*Return*:
315
+ #
316
+ #*Success*: Upon a successful call, this method will return a Campaigning::Result object wich consists of a +code+ and +message+ fields
317
+ #containing a successful message.
318
+ #
319
+ #*Error*: An Exception containing the cause of the error will be raised.
320
+ def update_basics!(params)
321
+ response = @@soap.updateClientBasics(
322
+ :apiKey => @apiKey,
323
+ :clientID => @clientID,
324
+ :companyName => params[:companyName],
325
+ :contactName => params[:contactName],
326
+ :emailAddress => params[:emailAddress],
327
+ :country => params[:country],
328
+ :timezone => params[:timezone]
329
+ )
330
+ handle_response response.client_UpdateBasicsResult
331
+ end
332
+
333
+
334
+ end
335
+ end
@@ -0,0 +1,276 @@
1
+ # Campaign is defined in soap/default.rb which is automatically generated.
2
+ # In this file we add additional methods to the Campaign class.
3
+ require File.expand_path(File.dirname(__FILE__)) + '/module_mixin'
4
+
5
+ module Campaigning
6
+ class List
7
+ include ModuleMixin
8
+ attr_accessor :listID
9
+ attr_accessor :name
10
+
11
+ def initialize(listID = nil, name = nil, opts={})
12
+ @apiKey = opts[:apiKey] || CAMPAIGN_MONITOR_API_KEY
13
+ @listID = listID
14
+ @name = name
15
+ end
16
+
17
+ #Creates a brand new subscriber list
18
+ #
19
+ #Available _params_ argument are:
20
+ # * :clientID - The ID of the client who will owner of the list.
21
+ # * :title - The list title. Must be unique for this client.
22
+ # * :unsubscribePage - The URL to which subscribers will be directed when unsubscribing from the list.
23
+ # If left blank or omitted a generic unsubscribe page is used.
24
+ # * :confirmOptIn - Either true or false depending on whether the list requires email confirmation or not. Please see
25
+ # the help documentation for more details of what this means.
26
+ # * :confirmationSuccessPage - Successful email confirmations will be redirected to this URL. Ignored if ConfirmOptIn
27
+ # is false. If left blank or omitted a generic confirmation page is used.
28
+ # * :apiKey - optional API key to use to make request. Will use CAMPAIGN_MONITOR_API_KEY if not set.
29
+ #*Return*:
30
+ #
31
+ #*Success*: Upon a successful call, this method will return a Campaigning::List object representing the newly created list.
32
+ #
33
+ #*Error*: An Exception containing the cause of the error will be raised.
34
+ def self.create!(params)
35
+ response = @@soap.createList(
36
+ :apiKey => params[:apiKey] || CAMPAIGN_MONITOR_API_KEY,
37
+ :clientID => params[:clientID],
38
+ :title => params[:title],
39
+ :unsubscribePage => params.fetch(:unsubscribePage, ""),
40
+ :confirmOptIn => params[:confirmOptIn],
41
+ :confirmationSuccessPage => params.fetch(:confirmationSuccessPage, "")
42
+ )
43
+ new_list_id = handle_response response.list_CreateResult
44
+ List.new(new_list_id, params[:title], :apiKey=> params[:apiKey])
45
+ end
46
+
47
+ #Creates a new custom field for a list
48
+ #
49
+ #Available _params_ argument are:
50
+ # * :fieldName - The Name for the new Custom Field. This will be used to generate the custom fields Key.
51
+ # * :dataType - The Data Type for the new Custom Field. This must be one of Text, Number, MultiSelectOne, or MultiSelectMany
52
+ # * :options - The available options for a multi-valued custom field. Options should be an Array of Strings, like: %w[Brazil Ireland England].
53
+ # You can't pass this field for Text and Number custom fields
54
+ #
55
+ #*Return*:
56
+ #
57
+ #*Success*: Upon a successful call, this method will return a Campaigning::Result object wich consists of a +code+ and +message+ fields
58
+ #containing a successful message.
59
+ #
60
+ #*Error*: An Exception containing the cause of the error will be raised.
61
+ def create_custom_field!(params)
62
+ response = @@soap.createListCustomField(
63
+ :apiKey => @apiKey,
64
+ :listID => @listID,
65
+ :fieldName => params[:fieldName],
66
+ :dataType => params[:dataType],
67
+ :options => params.fetch(:options, "")
68
+ )
69
+ handle_response response.list_CreateCustomFieldResult
70
+ end
71
+
72
+ #Deletes a list
73
+ #
74
+ #*Return*:
75
+ #
76
+ #*Success*: Upon a successful call, this method will return a Campaigning::Result object wich consists of a +code+ and +message+ fields
77
+ #containing a successful message.
78
+ #
79
+ #*Error*: An Exception containing the cause of the error will be raised.
80
+ def delete!
81
+ List.delete!(@listID, :apiKey=> @apiKey)
82
+ self.listID, self.name = nil, nil
83
+ end
84
+
85
+ #Deletes a list
86
+ #
87
+ #Aviable _opts_ arguments are:
88
+ # * :apiKey - optional API key to use to make request. Will use CAMPAIGN_MONITOR_API_KEY if not set.
89
+ #
90
+ #*Return*:
91
+ #
92
+ #*Success*: Upon a successful call, this method will return a Campaigning::Result object wich consists of a +code+ and +message+ fields
93
+ #containing a successful message.
94
+ #
95
+ #*Error*: An Exception containing the cause of the error will be raised.
96
+ def self.delete!(list_id, opts={})
97
+ response = @@soap.deleteList(:apiKey => opts[:apiKey] || CAMPAIGN_MONITOR_API_KEY, :listID => list_id)
98
+ handle_response response.list_DeleteResult
99
+ end
100
+
101
+ #Gets statistics for a subscriber list
102
+ #
103
+ #*Return*:
104
+ #
105
+ #*Success*: A successful call to List.GetStats will return a ListStatistics object, consisting of TotalActiveSubscribers,
106
+ #NewActiveSubscribersToday, NewActiveSubscribersYesterday, NewActiveSubscribersThisWeek, NewActiveSubscribersThisMonth,
107
+ #NewActiveSubscribersThisYear, TotalUnsubscribes, UnsubscribesToday, UnsubscribesYesterday, UnsubscribesThisWeek,
108
+ #UnsubscribesThisMonth, UnsubscribesThisYear, TotalDeleted, DeletedToday, DeletedYesterday, DeletedThisWeek, DeletedThisMonth,
109
+ #DeletedThisYear, TotalBounces, BouncesToday, BouncesYesterday, BouncesThisWeek, BouncesThisMonth and BouncesThisYear.
110
+ #
111
+ #*Error*: An Exception containing the cause of the error will be raised.
112
+ def stats
113
+ List.stats(@listID, :apiKey=> @apiKey)
114
+ end
115
+
116
+
117
+ #Gets statistics for a subscriber list
118
+ #
119
+ #*Return*:
120
+ #
121
+ #*Success*: A successful call to List.GetStats will return a ListStatistics object, consisting of TotalActiveSubscribers,
122
+ #NewActiveSubscribersToday, NewActiveSubscribersYesterday, NewActiveSubscribersThisWeek, NewActiveSubscribersThisMonth,
123
+ #NewActiveSubscribersThisYear, TotalUnsubscribes, UnsubscribesToday, UnsubscribesYesterday, UnsubscribesThisWeek,
124
+ #UnsubscribesThisMonth, UnsubscribesThisYear, TotalDeleted, DeletedToday, DeletedYesterday, DeletedThisWeek, DeletedThisMonth,
125
+ #DeletedThisYear, TotalBounces, BouncesToday, BouncesYesterday, BouncesThisWeek, BouncesThisMonth and BouncesThisYear.
126
+ #
127
+ #*Error*: An Exception containing the cause of the error will be raised.
128
+ def self.stats(list_id, opts={})
129
+ response = @@soap.getListStats(:apiKey => opts[:apiKey] || CAMPAIGN_MONITOR_API_KEY, :listID => list_id)
130
+ handle_response response.list_GetStatsResult
131
+ end
132
+
133
+
134
+ #Deletes a custom field from a list
135
+ #
136
+ #*Return*:
137
+ #
138
+ #*Success*: Upon a successful call, this method will return a Campaigning::Result object wich consists of a +code+ and +message+ fields
139
+ #containing a successful message.
140
+ #
141
+ #*Error*: An Exception containing the cause of the error will be raised.
142
+ def delete_custom_field!(key)
143
+ response = @@soap.deleteListCustomField(:apiKey => @apiKey, :listID => @listID, :key => '['+key+']')
144
+ handle_response response.list_DeleteCustomFieldResult
145
+ end
146
+
147
+ #Gets all the Custom Fields available for a list
148
+ #
149
+ #*Return*:
150
+ #
151
+ #*Success*: Upon a successful call, this method will return a collection of Campaigning::ListCustomField complex types. The individual ListCustomField
152
+ #record consists of a +fieldName+, +key+, +dataType+ and a +fieldOptions+ containing a list of possible options for multi-valued custom fields.
153
+ #
154
+ #*Error*: An Exception containing the cause of the error will be raised.
155
+ def custom_fields
156
+ response = @@soap.getListCustomFields(:apiKey => @apiKey, :listID => @listID)
157
+ handle_response response.list_GetCustomFieldsResult
158
+ end
159
+
160
+ #Gets a list's configuration detail
161
+ #
162
+ #*Return*:
163
+ #
164
+ #*Success*: A successful call to this method will return a Campaigning::ListDetail object, consisting of +listID+, +title+, +unsubscribePage+, +confirmOptIn+, and
165
+ #+confirmationSuccessPage+ (all as described in Campaigning::List#update and Campaigning::List.create).
166
+ #
167
+ #*Error*: An Exception containing the cause of the error will be raised.
168
+ def details
169
+ response = @@soap.getListDetail(:apiKey => @apiKey, :listID => @listID)
170
+ handle_response response.list_GetDetailResult
171
+ end
172
+
173
+ #Gets a list of all active subscribers for a list.
174
+ #
175
+ #*Return*:
176
+ #
177
+ #*Success*: Upon a successful call, this method will return a collection of Campaigning::Subscriber objects.
178
+ #
179
+ #*Error*: An Exception containing the cause of the error will be raised.
180
+ def get_all_active_subscribers
181
+ find_active_subscribers(DateTime.new(y=1911,m=1,d=01, h=01,min=00,s=00))
182
+ end
183
+
184
+ #Gets a list of all active subscribers for a list that have been joined since the specified date.
185
+ #The +joined_at+ param has to be a DateTime object, like:
186
+ #
187
+ # list.find_active_subscribers(DateTime.new(y=2009,m=4,d=01, h=01,min=00,s=00))
188
+ #
189
+ #*Return*:
190
+ #
191
+ #*Success*: Upon a successful call, this method will return a collection of Campaigning::Subscriber objects.
192
+ #
193
+ #*Error*: An Exception containing the cause of the error will be raised.
194
+ def find_active_subscribers(joined_at)
195
+ response = @@soap.getSubscribers(
196
+ :apiKey => @apiKey,
197
+ :listID => @listID,
198
+ :date =>joined_at.strftime('%Y-%m-%d %H:%M:%S')
199
+ )
200
+ handle_response response.subscribers_GetActiveResult
201
+ end
202
+
203
+ #Gets a list of all subscribers for a list that have unsubscribed since the specified date.
204
+ #The +unjoined_at+ param has to be a DateTime object, like:
205
+ #
206
+ # list.find_unsubscribed(DateTime.new(y=2009,m=4,d=01, h=01,min=00,s=00))
207
+ #
208
+ #*Return*:
209
+ #
210
+ #*Success*: Upon a successful call, this method will return a collection of Campaigning::Subscriber objects. In this case
211
+ #every returned object will contain the value "Unsubscribed" in the +state+ field.
212
+ #
213
+ #*Error*: An Exception containing the cause of the error will be raised.
214
+ def find_unsubscribed(unjoined_at)
215
+ response = @@soap.getUnsubscribed(
216
+ :apiKey => @apiKey,
217
+ :listID => @listID,
218
+ :date => unjoined_at.strftime('%Y-%m-%d %H:%M:%S') # TODO: Move that to a helper method
219
+ )
220
+ handle_response response.subscribers_GetUnsubscribedResult
221
+ end
222
+
223
+ #This method returns all of a particular subscribers details, including email address, name, active/inactive
224
+ #status and all custom field data. If a subscriber with that email address does not exist in that list, a +nil+ value is returned.
225
+ #
226
+ #*Return*:
227
+ #*Success*: Upon a successful call, this method will return a collection of Campaigning::Subscriber objects. In this case
228
+ #every returned object will contain the value "Unsubscribed" in the +state+ field.
229
+ #
230
+ #*Error*: An Exception containing the cause of the error will be raised.
231
+ def find_single_subscriber(email_address) # TODO: Create a mehod to handle with custom fields returned like (names from "State Name" to "state_name")
232
+ response = @@soap.getSingleSubscriber(
233
+ :apiKey => @apiKey,
234
+ :listID => @listID,
235
+ :emailAddress => email_address
236
+ )
237
+ handle_response response.subscribers_GetSingleSubscriberResult
238
+ end
239
+
240
+ #Update a subscriber list’s details
241
+ #
242
+ #Available _params_ argument are:
243
+ # * :title - The list title, as it will be shown in the application and through the API.
244
+ # * :unsubscribePage - The URL to which subscribers will be directed when unsubscribing from the list.
245
+ # If left blank or omitted a generic unsubscribe page is used.
246
+ # * :confirmOptIn - Either true or false depending on whether the list requires email confirmation or not. Please see
247
+ # the help documentation for more details of what this means.
248
+ # * :confirmationSuccessPage - Successful email confirmations will be redirected to this URL. Ignored if ConfirmOptIn
249
+ # is false. If left blank or omitted a generic confirmation page is used.
250
+ #
251
+ #*Return*:
252
+ #
253
+ #*Success*: Upon a successful call, this method will return a Campaigning::Result object wich consists of a +code+ and +message+ fields
254
+ #containing a successful message.
255
+ #
256
+ #*Error*: An Exception containing the cause of the error will be raised.
257
+ def update!(params)
258
+ response = @@soap.updateList(
259
+ :apiKey => @apiKey,
260
+ :listID => @listID,
261
+ :title => params[:title],
262
+ :unsubscribePage => params.fetch(:unsubscribePage, ""),
263
+ :confirmOptIn => params[:confirmOptIn],
264
+ :confirmationSuccessPage => params.fetch(:confirmationSuccessPage, "")
265
+ )
266
+ handle_response response.list_UpdateResult
267
+ end
268
+
269
+ protected
270
+
271
+ def custom_field_options(custom_fields) #:nodoc:
272
+ custom_fields.join("||").to_s
273
+ end
274
+
275
+ end
276
+ end