hominid 2.0.1 → 2.0.2

Sign up to get free protection for your applications and to get access to all the features.
Files changed (14) hide show
  1. data/README.textile +48 -91
  2. data/Rakefile +0 -1
  3. data/VERSION +1 -1
  4. data/hominid.gemspec +3 -8
  5. data/lib/hominid.rb +13 -28
  6. data/lib/hominid/base.rb +59 -53
  7. data/lib/hominid/campaign.rb +637 -147
  8. data/lib/hominid/helper.rb +80 -30
  9. data/lib/hominid/list.rb +357 -103
  10. data/lib/hominid/security.rb +46 -0
  11. metadata +5 -16
  12. data/hominid.yml.tpl +0 -25
  13. data/lib/hominid/webhook.rb +0 -131
  14. data/tasks/rails/hominid.rake +0 -22
data/lib/hominid/campaign.rb CHANGED
@@ -1,172 +1,662 @@
1
1
  module Hominid
2
-
3
- class Campaign < Base
4
-
5
- # Campaign related methods
6
- # --------------------------------
7
-
8
- attr_reader :campaign_id
9
- attr_reader :attributes
10
-
11
- def initialize(*args)
12
- options = args.last.is_a?(Hash) ? args.last : {}
13
- raise StandardError.new('Please provide a Campaign ID.') unless options[:id]
14
- @campaign_id = options.delete(:id)
15
- @attributes = options.delete(:attributes)
16
- super(options)
2
+ module Campaign
3
+
4
+ # CAMPAIGN RELATED METHODS
5
+
6
+ def campaigns(filters = {}, start = 0, limit = 25)
7
+ # Get all the campaigns for this account.
8
+ #
9
+ # Parameters:
10
+ # filters (Hash) = A hash of filters to apply to query. See the Mailchimp API documentation for more info.
11
+ # start (Integer) = Control paging of results.
12
+ # limit (Integer) = Number of campaigns to return. Upper limit set at 1000.
13
+ #
14
+ # Returns:
15
+ # An array of campaigns.
16
+ #
17
+ call("campaigns", filters, start, limit)
17
18
  end
18
-
19
- def self.all
20
- # Get all campaigns for this mailchimp account
21
- new(:id => 0).call("campaigns").to_a.collect { |c| Campaign.new(:id => c.delete('id'), :attributes => c) }
19
+
20
+ def find_campaign_by_id(campaign_id)
21
+ # Find a campaign by id
22
+ #
23
+ # Parameters:
24
+ # campaign_id (String) = The unique ID of the campaign to return.
25
+ #
26
+ # Returns:
27
+ # A single campaign.
28
+ #
29
+ call("campaigns", {:campaign_id => campaign_id}).first
22
30
  end
23
31
 
24
- def self.find_by_list_name(list_name)
25
- new(:id => 0).call("campaigns", {:list_id => List.find_by_name(list_name).list_id}).to_a.collect { |c| Campaign.new(:id=> c.delete('id'), :attributes => c) }
32
+ def find_campaign_by_web_id(campaign_web_id)
33
+ # Find a campaign by web_id
34
+ #
35
+ # Parameters:
36
+ # campaign_web_id (Integer) = The unique ID of the campaign to return.
37
+ #
38
+ # Returns:
39
+ # A single campaign.
40
+ #
41
+ call("campaigns").find {|campaign| campaign["web_id"] == campaign_web_id}
26
42
  end
27
-
28
- def self.find_by_list_id(list_id)
29
- # Find all campaigns for the given list
30
- new(:id => 0).call("campaigns", {:list_id => list_id}).to_a.collect { |c| Campaign.new(:id=> c.delete('id'), :attributes => c) }
43
+
44
+ def find_campaigns_by_title(title)
45
+ # Find a campaign by name
46
+ #
47
+ # Parameters:
48
+ # title (String) = The title of the campaign to return.
49
+ #
50
+ # Returns:
51
+ # An array of campaigns.
52
+ #
53
+ call("campaigns", {:title => title})
31
54
  end
32
-
33
- def self.find_by_title(title)
34
- # Find campaign by title
35
- all.find { |c| c.attributes['title'] =~ /#{title}/ }
55
+
56
+ def find_campaigns_by_list_name(list_name, start = 0, limit = 25)
57
+ # Find campaigns by list name
58
+ #
59
+ # Parameters:
60
+ # list_name (String) = The name of the mailing list to return campaigns for.
61
+ # start (Integer) = Control paging of results.
62
+ # limit (Integer) = Number of campaigns to return. Upper limit set at 1000.
63
+ #
64
+ # Returns:
65
+ # An array of campaigns.
66
+ #
67
+ call("campaigns", {:list_id => find_list_id_by_name(list_name)}, start, limit)
36
68
  end
37
-
38
- def self.find_by_type(type)
39
- # Find campaign by type. Possible choices are:
40
- # 'regular'
41
- # 'plaintext'
42
- # 'absplit'
43
- # 'rss'
44
- # 'inspection'
45
- # 'trans'
46
- # 'auto'
47
- all.find { |campaign| campaign.attributes['type'] =~ /#{type}/ }
69
+
70
+ def find_campaigns_by_list_id(list_id, start = 0, limit = 25)
71
+ # Find campaigns by list id
72
+ #
73
+ # Parameters:
74
+ # list_id (String) = The ID of the mailing list to return campaigns for.
75
+ # start (Integer) = Control paging of results.
76
+ # limit (Integer) = Number of campaigns to return. Upper limit set at 1000.
77
+ #
78
+ # Returns:
79
+ # An array of campaigns.
80
+ #
81
+ call("campaigns", {:list_id => list_id}, start, limit)
48
82
  end
49
-
50
- def self.find_by_web_id(web_id)
51
- # Find campaigns by web_id
52
- all.find { |campaign| campaign.attributes['web_id'] == web_id.to_i }
83
+
84
+ def find_campaigns_by_type(type, start = 0, limit = 25)
85
+ # Find campaigns by type
86
+ #
87
+ # Parameters:
88
+ # type (String) = One of: 'regular', 'plaintext', 'absplit', 'rss', 'inspection', 'trans', 'auto'
89
+ # start (Integer) = Control paging of results.
90
+ # limit (Integer) = Number of campaigns to return. Upper limit set at 1000.
91
+ #
92
+ # Returns:
93
+ # An array of campaigns.
94
+ #
95
+ call("campaigns", {:type => type}, start, limit)
53
96
  end
54
-
55
- def self.find_by_id(id)
56
- # Find campaign by id
57
- all.find { |campaign| (campaign.campaign_id == id.to_s) }
97
+
98
+ def create_campaign(type = 'regular', options = {}, content = {}, segment_options = {}, type_opts = {})
99
+ # Create a new draft campaign to send.
100
+ #
101
+ # Parameters:
102
+ # type (String) = One of "regular", "plaintext", "absplit", "rss", "trans" or "auto".
103
+ # options (Hash) = A hash of options for creating this campaign including:
104
+ # :list_id = (String) The ID of the list to send this campaign to.
105
+ # :subject = (String) The subject of the campaign.
106
+ # :from_email = (String) The email address this campaign will come from.
107
+ # :from_name = (String) The name that this campaign will come from.
108
+ # :to_email = (String) The To: name recipients will see.
109
+ # :template_id = (Integer) The ID of the template to use for this campaign (optional).
110
+ # :folder_id = (Integer) The ID of the folder to file this campaign in (optional).
111
+ # :tracking = (Array) What to track for this campaign (optional).
112
+ # :title = (String) Internal title for this campaign (optional).
113
+ # :authenticate = (Boolean) Set to true to authenticate campaign (optional).
114
+ # :analytics = (Array) Google analytics tags (optional).
115
+ # :auto_footer = (Boolean) Auto-generate the footer (optional)?
116
+ # :inline_css = (Boolean) Inline the CSS styles (optional)?
117
+ # :generate_text = (Boolean) Auto-generate text from HTML email (optional)?
118
+ # content (Hash) = The content for this campaign - use a struct with the following keys:
119
+ # :html (String) = The HTML content of the campaign.
120
+ # :text (String) = The text content of the campaign.
121
+ # :url (String) = A URL to pull content from. This will override other content settings.
122
+ # :archive (String) = To send a Base64 encoded archive file for Mailchimp to import all media from.
123
+ # :archive_type (String) = Only necessary for the "archive" option. Supported formats are: zip, tar.gz,
124
+ # tar.bz2, tar, tgz, tbz. Defaults to zip. (optional)
125
+ # segment_options (Hash) = Segmentation options. See the Mailchimp API documentation for more information.
126
+ # type_opts (Hash) = An array of options for this campaign type. See the Mailchimp API documentation for
127
+ # for more information.
128
+ #
129
+ # Returns:
130
+ # The ID for the created campaign. (String)
131
+ #
132
+ call("campaignCreate", type, options, content, segment_options, type_opts)
133
+ # TODO: Should we return the new campaign instead of the ID returned from the API?
58
134
  end
59
-
60
- def self.find(id_or_web_id)
61
- # Campaign finder method
62
- all = self.all
63
- campaign = self.find_by_id(id_or_web_id.to_s).to_a + self.find_by_web_id(id_or_web_id.to_i).to_a
64
- return campaign.blank? ? nil : campaign.first
135
+
136
+ def folders
137
+ # List all the folders for a user account.
138
+ #
139
+ # Returns:
140
+ # An array of templates for this campaign including:
141
+ # folder_id (Integer) = Folder Id for the given folder, this can be used in the campaigns() function to filter on.
142
+ # name (String) = Name of the given folder.
143
+ #
144
+ call("campaignFolders")
65
145
  end
66
-
67
- def self.create(type = 'regular', options = {}, content = {}, segment_options = {}, type_opts = {})
68
- # Create a new campaign
69
- # The options hash should be structured as follows:
70
- #
71
- # :list_id = (string) The ID of the list to send this campaign to.
72
- # :subject = (string) The subject of the campaign.
73
- # :from_email = (string) The email address this campaign will come from.
74
- # :from_name = (string) The name that this campaign will come from.
75
- # :to_email = (string) The To: name recipients will see.
76
- # :template_id = (integer) The ID of the template to use for this campaign (optional).
77
- # :folder_id = (integer) The ID of the folder to file this campaign in (optional).
78
- # :tracking = (array) What to track for this campaign (optional).
79
- # :title = (string) Internal title for this campaign (optional).
80
- # :authenticate = (boolean) Set to true to authenticate campaign (optional).
81
- # :analytics = (array) Google analytics tags (optional).
82
- # :auto_footer = (boolean) Auto-generate the footer (optional)?
83
- # :inline_css = (boolean) Inline the CSS styles (optional)?
84
- # :generate_text = (boolean) Auto-generate text from HTML email (optional)?
85
- #
86
- # Visit http://www.mailchimp.com/api/1.2/campaigncreate.func.php for more information about creating
87
- # campaigns via the API.
88
- #
89
- new(:id => 0).call("campaignCreate", type, options, content, segment_options, type_opts)
90
- ## TODO: Return the new campaign with the ID returned from the API
146
+
147
+ def templates
148
+ # Retrieve all templates defined for your user account.
149
+ #
150
+ # Returns:
151
+ # An array of templates for this campaign including:
152
+ # id (Integer) = The ID of the template.
153
+ # name (String) = The name of the template.
154
+ # layout (String) = The layout of the template - "basic", "left_column", "right_column", or "postcard".
155
+ # sections (Array) = An associative array of editable sections in the template that can accept custom HTML
156
+ # when sending a campaign.
157
+ #
158
+ call("campaignTemplates")
91
159
  end
92
-
93
- def self.templates
94
- # Get the templates for this account
95
- new(:id => 0).call("campaignTemplates")
160
+
161
+ def campaign_abuse_reports(campaign_id, start = 0, limit = 500, since = "2000-01-01 00:00:00")
162
+ # Get all email addresses that complained about a given campaign.
163
+ #
164
+ # Parameters:
165
+ # campaign_id (String) = The ID of the campaign.
166
+ # start (Integer) = Page number to start at. Defaults to 0.
167
+ # limit (Integer) = Number of results to return. Defaults to 500. Upper limit is 1000.
168
+ # since (DateTime) = Only return email reports since this date. Must be in YYYY-MM-DD HH:II:SS format (GMT).
169
+ #
170
+ # Returns:
171
+ # An array of abuse reports for this list in the format:
172
+ #
173
+ call("campaignAbuseReports", campaign_id, start, limit, since)
96
174
  end
97
-
98
- def add_order(order)
99
- # Attach Ecommerce Order Information to a campaign.
100
- # The order hash should be structured as follows:
101
- #
102
- # :id = (string) the order id
103
- # :email_id = (string) email id of the subscriber (mc_eid query string)
104
- # :total = (double) Show only campaigns with this from_name.
105
- # :shipping = (string) *optional - the total paid for shipping fees.
106
- # :tax = (string) *optional - the total tax paid.
107
- # :store_id = (string) a unique id for the store sending the order in
108
- # :store_name = (string) *optional - A readable name for the store, typicaly the hostname.
109
- # :plugin_id = (string) the MailChimp-assigned Plugin Id. Using 1214 for the moment.
110
- # :items = (array) the individual line items for an order, using the following keys:
111
- #
112
- # :line_num = (integer) *optional - line number of the item on the order
113
- # :product_id = (integer) internal product id
114
- # :product_name = (string) the name for the product_id associated with the item
115
- # :category_id = (integer) internal id for the (main) category associated with product
116
- # :category_name = (string) the category name for the category id
117
- # :qty = (double) the quantity of items ordered
118
- # :cost = (double) the cost of a single item (i.e., not the extended cost of the line)
119
- order = order.merge(:campaign_id => @campaign_id)
175
+
176
+ def advice(campaign_id)
177
+ # Retrieve the text presented in our app for how a campaign performed and any advice we may have for you - best
178
+ # suited for display in customized reports pages. Note: some messages will contain HTML - clean tags as necessary.
179
+ #
180
+ # Parameters:
181
+ # campaign_id (String) = The ID of the campaign.
182
+ #
183
+ # Returns:
184
+ # An array of advice on the campaign's performance including:
185
+ # msg (String) = Advice message.
186
+ # type (String) = One of: negative, positive, or neutral.
187
+ #
188
+ call("campaignAdvice", campaign_id)
189
+ end
190
+
191
+ def add_order(campaign_id, order)
192
+ # Attach Ecommerce Order Information to a Campaign.
193
+ #
194
+ # Parameters:
195
+ # campaign_id (String) = The ID of the campaign.
196
+ # order (Hash) = A hash of order information including:
197
+ # id (String) = The order id
198
+ # email_id (String) = Email id of the subscriber (mc_eid query string)
199
+ # total (Double) = Show only campaigns with this from_name.
200
+ # shipping (String) = The total paid for shipping fees. (optional)
201
+ # tax (String) = The total tax paid. (optional)
202
+ # store_id (String) = A unique id for the store sending the order in
203
+ # store_name (String) = A readable name for the store, typicaly the hostname. (optional)
204
+ # plugin_id (String) = The MailChimp-assigned Plugin Id. Using 1214 for the moment.
205
+ # items (Array) = The individual line items for an order, using the following keys:
206
+ # line_num (Integer) = The line number of the item on the order. (optional)
207
+ # product_id (Integer) = Internal product id.
208
+ # product_name (String) = The name for the product_id associated with the item.
209
+ # category_id (Integer) = Internal id for the (main) category associated with product.
210
+ # category_name (String) = The category name for the category id.
211
+ # qty (Double) = The quantity of items ordered.
212
+ # cost (Double) = The cost of a single item (Ex. Not the extended cost of the line).
213
+ #
214
+ # Returns:
215
+ # True if successful, error code if not.
216
+ #
217
+ order = order.merge(:campaign_id => campaign_id)
120
218
  call("campaignEcommAddOrder", order)
121
219
  end
122
-
123
- def campaign_stats()
124
- # Get the stats of a campaign
125
- call("campaignStats", @campaign_id)
220
+ alias :ecomm_add_order :add_order
221
+
222
+ def analytics(campaign_id)
223
+ # Retrieve the Google Analytics data we've collected for this campaign. Note, requires Google
224
+ # Analytics Add-on to be installed and configured.
225
+ #
226
+ # Parameters:
227
+ # campaign_id (String) = The ID of the campaign.
228
+ #
229
+ # Returns:
230
+ # An array of analytics for the passed campaign including:
231
+ # visits (Integer) = Number of visits.
232
+ # pages (Integer) = Number of page views.
233
+ # new_visits (Integer) = New visits recorded.
234
+ # bounces (Integer) = Vistors who "bounced" from your site.
235
+ # time_on_site (Double) =
236
+ # goal_conversions (Integer) = Number of goals converted.
237
+ # goal_value (Double) = Value of conversion in dollars.
238
+ # revenue (Double) = Revenue generated by campaign.
239
+ # transactions (Integer) = Number of transactions tracked.
240
+ # ecomm_conversions (Integer) = Number Ecommerce transactions tracked.
241
+ # goals (Array) = An array containing goal names and number of conversions.
242
+ #
243
+ call("campaignAnalytics", campaign_id)
126
244
  end
127
-
128
- # Get the HTML & text content for a campaign
129
- # :for_archive = (boolean) default true, true returns the content as it would appear in the archive, false returns the raw HTML/text
130
- def campaign_content(for_archive = true)
131
- # Get the content of a campaign
132
- call("campaignContent", @campaign_id, for_archive)
245
+
246
+ def bounce_messages(campaign_id, start = 0, limit = 25, since = "2000-01-01")
247
+ # Retrieve the full bounce messages for the given campaign. Note that this can return very large amounts
248
+ # of data depending on how large the campaign was and how much cruft the bounce provider returned. Also,
249
+ # messages over 30 days old are subject to being removed.
250
+ #
251
+ # Parameters:
252
+ # campaign_id (String) = The ID of the campaign.
253
+ # start (Integer) = For large data sets, the page number to start at.
254
+ # limit (Integer) = For large data sets, the number of results to return. Upper limit set at 50.
255
+ # since (Date) = Pull only messages since this time - use YYYY-MM-DD format in GMT.
256
+ #
257
+ # Returns:
258
+ # An array of full bounce messages for this campaign including:
259
+ # date (String) = Date/time the bounce was received and processed.
260
+ # email (String) = The email address that bounced.
261
+ # message (String) = The entire bounce message received.
262
+ #
263
+ call("campaignBounceMessages", campaign_id, start, limit, since)
133
264
  end
134
-
135
- def delete_campaign()
136
- # Delete a campaign
137
- call("campaignDelete", @campaign_id)
265
+
266
+ def click_details(campaign_id, url, start = 0, limit = 1000)
267
+ # Return the list of email addresses that clicked on a given url, and how many times they clicked.
268
+ # Note: Requires the AIM module to be installed.
269
+ #
270
+ # Parameters:
271
+ # campaign_id (String) = The ID of the campaign.
272
+ # url (String) = The URL of the link that was clicked on.
273
+ # start (Integer) = For large data sets, the page number to start at.
274
+ # limit (Integer) = For large data sets, the number of results to return. Upper limit set at 15000.
275
+ #
276
+ # Returns:
277
+ # An array of structs containing email addresses and click counts including:
278
+ # email (String) = Email address that opened the campaign.
279
+ # clicks (Integer) = Total number of times the URL was clicked on by this email address.
280
+ #
281
+ call("campaignClickDetailAIM", campaign_id, url, start, limit)
138
282
  end
139
-
140
- def replicate_campaign()
141
- # Replicate a campaign (returns ID of new campaign)
142
- call("campaignReplicate", @campaign_id)
283
+ alias :click_detail_aim :click_details
284
+
285
+ def click_stats(campaign_id)
286
+ # Get an array of the urls being tracked, and their click counts for a given campaign.
287
+ #
288
+ # Parameters:
289
+ # campaign_id (String) = The ID of the campaign.
290
+ #
291
+ # Returns:
292
+ # A struct of URLs and associated statistics including:
293
+ # clicks (Integer) = Number of times the specific link was clicked.
294
+ # unique (Integer) = Number of unique people who clicked on the specific link.
295
+ #
296
+ call("campaignClickStats", campaign_id)
143
297
  end
144
-
145
- def schedule_campaign(time = "#{1.day.from_now}")
146
- # Schedule a campaign
147
- ## TODO: Add support for A/B Split scheduling
148
- call("campaignSchedule", @campaign_id, time)
298
+
299
+ def content(campaign_id, for_archive = true)
300
+ # Get the content (both html and text) for a campaign either as it would appear in the campaign archive
301
+ # or as the raw, original content.
302
+ #
303
+ # Parameters:
304
+ # campaign_id (String) = The ID of the campaign.
305
+ # for_archive (Boolean) = Controls whether we return the Archive version (true) or the Raw version (false),
306
+ # defaults to true.
307
+ #
308
+ # Returns:
309
+ # A struct containing all content for the campaign including:
310
+ # html (String) = The HTML content used for the campgain with merge tags intact.
311
+ # text (String) = The Text content used for the campgain with merge tags intact.
312
+ #
313
+ call("campaignContent", campaign_id, for_archive)
149
314
  end
150
-
151
- def send_now()
152
- # Send a campaign
153
- call("campaignSendNow", @campaign_id)
315
+ alias :campaign_content :content
316
+
317
+ def delete(campaign_id)
318
+ # Delete a campaign.
319
+ #
320
+ # Parameters:
321
+ # campaign_id (String) = The ID of the campaign.
322
+ #
323
+ # Returns:
324
+ # True if successful, error code if not.
325
+ #
326
+ call("campaignDelete", campaign_id)
154
327
  end
155
-
156
- # Send a test of a campaign
157
- def send_test(emails = {})
158
- call("campaignSendTest", @campaign_id, emails)
328
+ alias :delete_campaign :delete
329
+
330
+ def email_domain_performance(campaign_id)
331
+ # Get the top 5 performing email domains for this campaign.
332
+ #
333
+ # Parameters:
334
+ # campaign_id (String) = The ID of the campaign.
335
+ #
336
+ # Returns:
337
+ # An array of email domains and their associated stats including:
338
+ # domain (String) = Domain name or special "Other" to roll-up stats past 5 domains.
339
+ # total_sent (Integer) = Total Email across all domains - this will be the same in every row.
340
+ # emails (Integer) = Number of emails sent to this domain.
341
+ # bounces (Integer) = Number of bounces.
342
+ # opens (Integer) = Number of opens.
343
+ # clicks (Integer) = Number of clicks.
344
+ # unsubs (Integer) = Number of unsubscribes.
345
+ # delivered (Integer) = Number of deliveries.
346
+ # emails_pct (Integer) = Percentage of emails that went to this domain (whole number).
347
+ # bounces_pct (Integer) = Percentage of bounces from this domain (whole number).
348
+ # opens_pct (Integer) = Percentage of opens from this domain (whole number).
349
+ # clicks_pct (Integer) = Percentage of clicks from this domain (whole number).
350
+ # unsubs_pct (Integer) = Percentage of unsubs from this domain (whole number).
351
+ #
352
+ call("campaignEmailDomainPerformance", campaign_id)
159
353
  end
160
-
161
- def update(name, value)
162
- # Update a campaign
163
- call("campaignUpdate", @campaign_id, name, value)
354
+ alias :email_performance :email_domain_performance
355
+
356
+ def email_stats(campaign_id, email)
357
+ # Given a campaign and email address, return the entire click and open history with timestamps, ordered by time.
358
+ # Note: Requires the AIM module to be installed.
359
+ #
360
+ # Parameters:
361
+ # campaign_id (String) = The ID of the campaign.
362
+ # email (String) = The email address to check OR the email "id" returned from listMemberInfo, Webhooks, and Campaigns.
363
+ #
364
+ # Returns:
365
+ # An array of structs containing the actions including:
366
+ # action (String) = The action taken (open or click).
367
+ # timestamp (DateTime) = Time the action occurred.
368
+ # url (String) = For clicks, the URL that was clicked.
369
+ #
370
+ call("campaignEmailStatsAIM", campaign_id, email)
164
371
  end
165
-
166
- def unschedule()
167
- # Unschedule a campaign
168
- call("campaignUnschedule", @campaign_id)
372
+ alias :email_stats_aim :email_stats
373
+
374
+ def email_stats_all(campaign_id, start = 0, limit = 100)
375
+ # Given a campaign and correct paging limits, return the entire click and open history with timestamps, ordered by time,
376
+ # for every user a campaign was delivered to.
377
+ # Note: Requires the AIM module to be installed.
378
+ #
379
+ # Parameters:
380
+ # campaign_id (String) = The ID of the campaign.
381
+ # start (Integer) = For large data sets, the page number to start at.
382
+ # limit (Integer) = For large data sets, the number of results to return. Upper limit set at 1000.
383
+ #
384
+ # Returns:
385
+ # An array of structs containing actions (opens and clicks) for each email, with timestamps including:
386
+ # action (String) = The action taken (open or click).
387
+ # timestamp (DateTime) = Time the action occurred.
388
+ # url (String) = For clicks, the URL that was clicked.
389
+ #
390
+ call("campaignEmailStatsAIMAll", campaign_id, start, limit)
391
+ end
392
+ alias :email_stats_aim_all :email_stats_all
393
+
394
+ def hard_bounces(campaign_id, start = 0, limit = 1000)
395
+ # Get all email addresses with Hard Bounces for a given campaign.
396
+ #
397
+ # Parameters:
398
+ # campaign_id (String) = The ID of the campaign.
399
+ # start (Integer) = For large data sets, the page number to start at.
400
+ # limit (Integer) = For large data sets, the number of results to return. Upper limit set at 15000.
401
+ #
402
+ # Returns:
403
+ # An array of email addresses with Hard Bounces.
404
+ #
405
+ call("campaignHardBounces", campaign_id, start, limit)
406
+ end
407
+
408
+ def not_opened(campaign_id, start = 0, limit = 1000)
409
+ # Retrieve the list of email addresses that did not open a given campaign.
410
+ # Note: Requires the AIM module to be installed.
411
+ #
412
+ # Parameters:
413
+ # campaign_id (String) = The ID of the campaign.
414
+ # start (Integer) = For large data sets, the page number to start at.
415
+ # limit (Integer) = For large data sets, the number of results to return. Upper limit set at 15000.
416
+ #
417
+ # Returns:
418
+ # A list of email addresses that did not open a campaign.
419
+ #
420
+ call("campaignNotOpenedAIM", campaign_id, start, limit)
421
+ end
422
+ alias :not_opened_aim :not_opened
423
+
424
+ def opened(campaign_id, start = 0, limit = 1000)
425
+ # Retrieve the list of email addresses that opened a given campaign with how many times they opened.
426
+ # Note: this AIM function is free and does not actually require the AIM module to be installed.
427
+ #
428
+ # Parameters:
429
+ # campaign_id (String) = The ID of the campaign.
430
+ # start (Integer) = For large data sets, the page number to start at.
431
+ # limit (Integer) = For large data sets, the number of results to return. Upper limit set at 15000.
432
+ #
433
+ # Returns:
434
+ # An array of structs containing email addresses and open counts including:
435
+ # email (String) = Email address that opened the campaign.
436
+ # open_count (Integer) = Total number of times the campaign was opened by this email address.
437
+ #
438
+ call("campaignOpenedAIM", campaign_id, start, limit)
169
439
  end
440
+ alias :opened_aim :opened
441
+
442
+ def orders(campaign_id, start = 0, limit = 100, since = "2001-01-01 00:00:00")
443
+ # Retrieve the Ecommerce Orders.
444
+ #
445
+ # Parameters:
446
+ # campaign_id (String) = The ID of the campaign.
447
+ # start (Integer) = For large data sets, the page number to start at.
448
+ # limit (Integer) = For large data sets, the number of results to return. Upper limit set at 500.
449
+ # since (DateTime) = Pull only messages since this time - use YYYY-MM-DD HH:II:SS format in GMT.
450
+ #
451
+ # Returns:
452
+ # An array of orders and their details for this campaign, including:
453
+ # store_id (String) = The store id generated by the plugin used to uniquely identify a store.
454
+ # store_name (String) = The store name collected by the plugin - often the domain name.
455
+ # order_id (Integer) = The internal order id the store tracked this order by.
456
+ # email (String) = The email address that received this campaign and is associated with this order.
457
+ # order_total (Double) = The order total.
458
+ # tax_total (Double) = The total tax for the order (if collected).
459
+ # ship_total (Double) = The shipping total for the order (if collected).
460
+ # order_date (String) = The date the order was tracked - from the store if possible, otherwise the GMT time received.
461
+ # lines (Array) = Containing details of the order - product, category, quantity, item cost.
462
+ #
463
+ call("campaignEcommOrders", campaign_id, start, limit, since)
464
+ end
465
+ alias :ecomm_orders :orders
466
+
467
+ def pause(campaign_id)
468
+ # Pause an AutoResponder orRSS campaign from sending.
469
+ #
470
+ # Parameters:
471
+ # campaign_id (String) = The ID of the campaign.
472
+ #
473
+ # Returns:
474
+ # True if successful.
475
+ call("campaignPause", campaign_id)
476
+ end
477
+
478
+ def replicate(campaign_id)
479
+ # Replicate a campaign.
480
+ #
481
+ # Parameters:
482
+ # campaign_id (String) = The ID of the campaign.
483
+ #
484
+ # Returns:
485
+ # The ID of the newly created replicated campaign. (String)
486
+ #
487
+ call("campaignReplicate", campaign_id)
488
+ end
489
+ alias :replicate_campaign :replicate
490
+
491
+ def resume(campaign_id)
492
+ # Resume sending an AutoResponder or RSS campaign.
493
+ #
494
+ # Parameters:
495
+ # campaign_id (String) = The ID of the campaign.
496
+ #
497
+ # Returns:
498
+ # True if successful.
499
+ #
500
+ call("campaignResume", campaign_id)
501
+ end
502
+
503
+ def schedule(campaign_id, time = "#{1.day.from_now}", time_b = "")
504
+ # Schedule a campaign to be sent in the future.
505
+ #
506
+ # Parameters:
507
+ # campaign_id (String) = The ID of the campaign.
508
+ # time (DateTime) = The time to schedule the campaign. For A/B Split "schedule" campaigns, the time
509
+ # for Group A - in YYYY-MM-DD HH:II:SS format in GMT.
510
+ # time_b (DateTime) = The time to schedule Group B of an A/B Split "schedule" campaign - in
511
+ # YYYY-MM-DD HH:II:SS format in GMT. (optional)
512
+ #
513
+ # Returns:
514
+ # True if successful.
515
+ #
516
+ call("campaignSchedule", campaign_id, time, time_b)
517
+ end
518
+ alias :schedule_campaign :schedule
519
+
520
+ def send(campaign_id)
521
+ # Send this campaign immediately.
522
+ #
523
+ # Parameters:
524
+ # campaign_id (String) = The ID of the campaign to send.
525
+ #
526
+ # Returns:
527
+ # True if successful.
528
+ call("campaignSendNow", campaign_id)
529
+ end
530
+ alias :send_now :send
531
+
532
+ def send_test(campaign_id, emails = {}, send_type = nil)
533
+ # Send a test of this campaign to the provided email address(es).
534
+ #
535
+ # Parameters:
536
+ # campaign_id (String) = The ID of the campaign.
537
+ # emails (Hash) = A hash of email addresses to receive the test message.
538
+ # send_type (String) = One of 'html', 'text' or nil (send both). Defaults to nil.
539
+ #
540
+ # Returns:
541
+ # True if successful.
542
+ #
543
+ call("campaignSendTest", campaign_id, emails, send_type)
544
+ end
545
+
546
+ def share_report(campaign_id, options = {})
547
+ # Get the URL to a customized VIP Report for the specified campaign and optionally send an email
548
+ # to someone with links to it. Note subsequent calls will overwrite anything already set for the
549
+ # same campign (eg, the password).
550
+ #
551
+ # Parameters:
552
+ # campaign_id (String) = The ID of the campaign.
553
+ # options (Hash) = A hash of parameters which can be used to configure the shared report, including: (optional)
554
+ # header_type (String) = One of "text" or "image". Defaults to 'text'. (optional)
555
+ # header_data (String) = If "header_type" is text, the text to display. If "header_type" is "image"
556
+ # a valid URL to an image file. Note that images will be resized to be no more
557
+ # than 500x150. Defaults to the Accounts Company Name. (optional)
558
+ # secure (Boolean) = Whether to require a password for the shared report. Defaults to "true". (optional)
559
+ # password (String) = If secure is true and a password is not included, we will generate one. It is always returned. (optional)
560
+ # to_email (String) = Email address to share the report with - no value means an email will not be sent. (optional)
561
+ # theme (Array) = An array containing either 3 or 6 character color code values for: "bg_color",
562
+ # "header_color", "current_tab", "current_tab_text", "normal_tab", "normal_tab_text",
563
+ # "hover_tab", "hover_tab_text". (optional)
564
+ # css_url (String) = A link to an external CSS file to be included after our default CSS
565
+ # (http://vip-reports.net/css/vip.css) only if loaded via the "secure_url"
566
+ # - max 255 characters. (optional)
567
+ #
568
+ # Returns:
569
+ # A struct containing details for the shared report including:
570
+ # title (String) = The Title of the Campaign being shared.
571
+ # url (String) = The URL to the shared report.
572
+ # secure_url (String) = The URL to the shared report, including the password (good for loading in an IFRAME).
573
+ # For non-secure reports, this will not be returned.
574
+ # password (String) = If secured, the password for the report, otherwise this field will not be returned.
575
+ #
576
+ call("campaignShareReport", campaign_id, options)
577
+ end
578
+
579
+ def soft_bounces(campaign_id, start = 0, limit = 1000)
580
+ # Get all email addresses with Soft Bounces for a given campaign.
581
+ #
582
+ # Parameters:
583
+ # campaign_id (String) = The ID of the campaign.
584
+ # start (Integer) = For large data sets, the page number to start at.
585
+ # limit (Integer) = For large data sets, the number of results to return. Upper limit set at 15000.
586
+ #
587
+ # Returns:
588
+ # An array of email addresses with Soft Bounces.
589
+ #
590
+ call("campaignSoftBounces", campaign_id, start, limit)
591
+ end
592
+
593
+ def stats(campaign_id)
594
+ # Get all the relevant campaign statistics for this campaign.
595
+ #
596
+ # Parameters:
597
+ # campaign_id (String) = The ID of the campaign.
598
+ #
599
+ # Returns:
600
+ # An array of statistics for this campaign including:
601
+ # syntax_error (Integer) = Number of email addresses in campaign that had syntactical errors.
602
+ # hard_bounces (Integer) = Number of email addresses in campaign that hard bounced.
603
+ # soft_bounces (Integer) = Number of email addresses in campaign that soft bounced.
604
+ # unsubscribes (Integer) = Number of email addresses in campaign that unsubscribed.
605
+ # abuse_reports (Integer) = Number of email addresses in campaign that reported campaign for abuse.
606
+ # forwards (Integer) = Number of times email was forwarded to a friend.
607
+ # forwards_opens (Integer) = Number of times a forwarded email was opened.
608
+ # opens (Integer) = Number of times the campaign was opened.
609
+ # last_open (Date) = Date of the last time the email was opened.
610
+ # unique_opens (Integer) = Number of people who opened the campaign.
611
+ # clicks (Integer) = Number of times a link in the campaign was clicked.
612
+ # unique_clicks (Integer) = Number of unique recipient/click pairs for the campaign.
613
+ # last_click (Date) = Date of the last time a link in the email was clicked.
614
+ # users_who_clicked (Integer) = Number of unique recipients who clicked on a link in the campaign.
615
+ # emails_sent (Integer) = Number of email addresses campaign was sent to.
616
+ #
617
+ call("campaignStats", campaign_id)
618
+ end
619
+ alias :campaign_stats :stats
620
+
621
+ def update(campaign_id, name, value)
622
+ # Update just about any setting for a campaign that has not been sent.
623
+ #
624
+ # Parameters:
625
+ # campaign_id (String) = The ID of the campaign.
626
+ # name (String) = The parameter name.
627
+ # value (Variable) = An appropriate value for the parameter.
628
+ #
629
+ # Returns:
630
+ # True if successful, error code if not.
631
+ #
632
+ call("campaignUpdate", campaign_id, name, value)
633
+ end
634
+
635
+ def unschedule(campaign_id)
636
+ # Unschedule a campaign that is scheduled to be sent in the future.
637
+ #
638
+ # Parameters:
639
+ # campaign_id (String) = The ID of the campaign.
640
+ #
641
+ # Returns:
642
+ # True if successful.
643
+ #
644
+ call("campaignUnschedule", campaign_id)
645
+ end
646
+
647
+ def unsubsribes(campaign_id, start = 0, limit = 1000)
648
+ # Get all unsubscribed email addresses for a given campaign.
649
+ #
650
+ # Parameters:
651
+ # campaign_id (String) = The ID of the campaign.
652
+ # start (Integer) = For large data sets, the page number to start at.
653
+ # limit (Integer) = For large data sets, the number of results to return. Upper limit set at 15000.
654
+ #
655
+ # Returns:
656
+ # An array of email addresses that unsubscribed from this campaign.
657
+ #
658
+ call("campaignUnsubscribes", campaign_id, start, limit)
659
+ end
660
+
170
661
  end
171
- end
172
-
662
+ end