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.
- data/.bnsignore +16 -0
- data/.gitignore +5 -0
- data/LICENSE +20 -0
- data/README.rdoc +65 -0
- data/Rakefile +59 -0
- data/VERSION.yml +4 -0
- data/campaigning.gemspec +77 -0
- data/lib/campaigning.rb +1 -0
- data/lib/campaigning/campaign.rb +218 -0
- data/lib/campaigning/campaigning.rb +53 -0
- data/lib/campaigning/client.rb +335 -0
- data/lib/campaigning/list.rb +276 -0
- data/lib/campaigning/module_mixin.rb +31 -0
- data/lib/campaigning/soap/generated/default.rb +1715 -0
- data/lib/campaigning/soap/generated/defaultDriver.rb +413 -0
- data/lib/campaigning/soap/generated/defaultMappingRegistry.rb +1526 -0
- data/lib/campaigning/subscriber.rb +158 -0
- data/lib/campaigning/template.rb +124 -0
- data/sample/campaign_sample.rb +116 -0
- data/sample/campaigning_sample.rb +25 -0
- data/sample/client_sample.rb +139 -0
- data/sample/list_sample.rb +159 -0
- data/sample/subscriber_sample.rb +88 -0
- data/test/campaign_test.rb +102 -0
- data/test/campaigning_test.rb +34 -0
- data/test/client_test.rb +130 -0
- data/test/list_test.rb +113 -0
- data/test/subscriber_test.rb +55 -0
- data/test/template_test.rb +62 -0
- data/test/test_helper.rb +10 -0
- metadata +100 -0
@@ -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
|