mailchimp-api 2.0.2 → 2.0.7
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +7 -0
- data/lib/mailchimp.rb +23 -13
- data/lib/mailchimp/api.rb +464 -185
- data/lib/mailchimp/errors.rb +13 -1
- metadata +43 -67
checksums.yaml
ADDED
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
---
|
|
2
|
+
SHA256:
|
|
3
|
+
metadata.gz: 1cb06517f9bb19cbb5be945feb067c31717bba7a9a417c0ee62306631dbb78f5
|
|
4
|
+
data.tar.gz: b57ea9451976cb77aad3d54c1d015741008c1d2e238c40cf2ae830c52857db16
|
|
5
|
+
SHA512:
|
|
6
|
+
metadata.gz: 58ee98eec97d5f3f3cc0b2b369534e5058c70646cdd1312a4675d5eca495d969f3e6743a8fead3aa291e73b8d4352923a2e8b73cfacc63dce363b7c29ce2048b
|
|
7
|
+
data.tar.gz: 4da4afd19ce0e199ec37125df7816133550c4081e6530a49a2d761c24c309d475a2bf1d9eb13e9ec1eca496a737405937b157b2dbba1c1e8ef6f9267b6b32671
|
data/lib/mailchimp.rb
CHANGED
|
@@ -14,24 +14,22 @@ module Mailchimp
|
|
|
14
14
|
@host = 'https://api.mailchimp.com'
|
|
15
15
|
@path = '/2.0/'
|
|
16
16
|
@dc = 'us1'
|
|
17
|
+
|
|
18
|
+
unless apikey
|
|
19
|
+
apikey = ENV['MAILCHIMP_APIKEY'] || read_configs
|
|
20
|
+
end
|
|
21
|
+
|
|
22
|
+
raise Error, 'You must provide a MailChimp API key' unless apikey
|
|
23
|
+
|
|
17
24
|
@apikey = apikey
|
|
18
|
-
if @apikey.split('-').length == 2
|
|
25
|
+
if @apikey.split('-').length == 2
|
|
19
26
|
@host = "https://#{@apikey.split('-')[1]}.api.mailchimp.com"
|
|
27
|
+
else
|
|
28
|
+
raise InvalidApiKeyError, 'Your MailChimp API key must contain a suffix subdomain (e.g. "-us8").'
|
|
20
29
|
end
|
|
21
30
|
|
|
22
31
|
@session = Excon.new @host
|
|
23
32
|
@debug = debug
|
|
24
|
-
|
|
25
|
-
if not apikey
|
|
26
|
-
if ENV['MAILCHIMP_APIKEY']
|
|
27
|
-
apikey = ENV['MAILCHIMP_APIKEY']
|
|
28
|
-
else
|
|
29
|
-
apikey = read_configs
|
|
30
|
-
end
|
|
31
|
-
end
|
|
32
|
-
|
|
33
|
-
raise Error, 'You must provide a MailChimp API key' if not apikey
|
|
34
|
-
@apikey = apikey
|
|
35
33
|
end
|
|
36
34
|
|
|
37
35
|
def call(url, params={})
|
|
@@ -143,7 +141,13 @@ module Mailchimp
|
|
|
143
141
|
'Invalid_PagingLimit' => InvalidPagingLimitError,
|
|
144
142
|
'Invalid_PagingStart' => InvalidPagingStartError,
|
|
145
143
|
'Max_Size_Reached' => MaxSizeReachedError,
|
|
146
|
-
'MC_SearchException' => MCSearchExceptionError
|
|
144
|
+
'MC_SearchException' => MCSearchExceptionError,
|
|
145
|
+
'Goal_SaveFailed' => GoalSaveFailedError,
|
|
146
|
+
'Conversation_DoesNotExist' => ConversationDoesNotExistError,
|
|
147
|
+
'Conversation_ReplySaveFailed' => ConversationReplySaveFailedError,
|
|
148
|
+
'File_Not_Found_Exception' => FileNotFoundExceptionError,
|
|
149
|
+
'Folder_Not_Found_Exception' => FolderNotFoundExceptionError,
|
|
150
|
+
'Folder_Exists_Exception' => FolderExistsExceptionError
|
|
147
151
|
}
|
|
148
152
|
|
|
149
153
|
begin
|
|
@@ -176,6 +180,9 @@ module Mailchimp
|
|
|
176
180
|
def mobile()
|
|
177
181
|
Mobile.new self
|
|
178
182
|
end
|
|
183
|
+
def conversations()
|
|
184
|
+
Conversations.new self
|
|
185
|
+
end
|
|
179
186
|
def ecomm()
|
|
180
187
|
Ecomm.new self
|
|
181
188
|
end
|
|
@@ -197,6 +204,9 @@ module Mailchimp
|
|
|
197
204
|
def gallery()
|
|
198
205
|
Gallery.new self
|
|
199
206
|
end
|
|
207
|
+
def goal()
|
|
208
|
+
Goal.new self
|
|
209
|
+
end
|
|
200
210
|
end
|
|
201
211
|
end
|
|
202
212
|
|
data/lib/mailchimp/api.rb
CHANGED
|
@@ -19,7 +19,7 @@ module Mailchimp
|
|
|
19
19
|
end
|
|
20
20
|
|
|
21
21
|
# Delete a campaign, autoresponder, or template folder. Note that this will simply make whatever was in the folder appear unfiled, no other data is removed
|
|
22
|
-
# @param [Int] fid the folder id to delete - retrieve from folders()
|
|
22
|
+
# @param [Int] fid the folder id to delete - retrieve from folders/list()
|
|
23
23
|
# @param [String] type the type of folder to delete - either "campaign", "autoresponder", or "template"
|
|
24
24
|
# @return [Hash] with a single entry:
|
|
25
25
|
# - [Bool] complete whether the call worked. reallistically this will always be true as errors will be thrown otherwise.
|
|
@@ -31,7 +31,7 @@ module Mailchimp
|
|
|
31
31
|
# List all the folders of a certain type
|
|
32
32
|
# @param [String] type the type of folders to return "campaign", "autoresponder", or "template"
|
|
33
33
|
# @return [Array] structs for each folder, including:
|
|
34
|
-
# - [Int] folder_id Folder Id for the given folder, this can be used in the campaigns() function to filter on.
|
|
34
|
+
# - [Int] folder_id Folder Id for the given folder, this can be used in the campaigns/list() function to filter on.
|
|
35
35
|
# - [String] name Name of the given folder
|
|
36
36
|
# - [String] date_created The date/time the folder was created
|
|
37
37
|
# - [String] type The type of the folders being returned, just to make sure you know.
|
|
@@ -42,7 +42,7 @@ module Mailchimp
|
|
|
42
42
|
end
|
|
43
43
|
|
|
44
44
|
# Update the name of a folder for campaigns, autoresponders, or templates
|
|
45
|
-
# @param [Int] fid the folder id to update - retrieve from folders()
|
|
45
|
+
# @param [Int] fid the folder id to update - retrieve from folders/list()
|
|
46
46
|
# @param [String] name a new, unique name for the folder (max 100 bytes)
|
|
47
47
|
# @param [String] type the type of folder to update - one of "campaign", "autoresponder", or "template".
|
|
48
48
|
# @return [Hash] with a single entry:
|
|
@@ -81,7 +81,7 @@ module Mailchimp
|
|
|
81
81
|
end
|
|
82
82
|
|
|
83
83
|
# Pull details for a specific template to help support editing
|
|
84
|
-
# @param [Int] template_id the template id - get from templates()
|
|
84
|
+
# @param [Int] template_id the template id - get from templates/list()
|
|
85
85
|
# @param [String] type optional the template type to load - one of 'user', 'gallery', 'base', defaults to user.
|
|
86
86
|
# @return [Hash] info to be used when editing
|
|
87
87
|
# - [Hash] default_content the default content broken down into the named editable sections for the template - dependant upon template, so not documented
|
|
@@ -97,12 +97,13 @@ module Mailchimp
|
|
|
97
97
|
# @param [Hash] types optional the types of templates to return
|
|
98
98
|
# - [Boolean] user Custom templates for this user account. Defaults to true.
|
|
99
99
|
# - [Boolean] gallery Templates from our Gallery. Note that some templates that require extra configuration are withheld. (eg, the Etsy template). Defaults to false.
|
|
100
|
-
# - [Boolean] base Our "start from scratch" extremely basic templates. Defaults to false.
|
|
100
|
+
# - [Boolean] base Our "start from scratch" extremely basic templates. Defaults to false. As of the 9.0 update, "base" templates are no longer available via the API because they are now all saved Drag & Drop templates.
|
|
101
101
|
# @param [Hash] filters optional options to control how inactive templates are returned, if at all
|
|
102
102
|
# - [String] category optional for Gallery templates only, limit to a specific template category
|
|
103
103
|
# - [String] folder_id user templates, limit to this folder_id
|
|
104
104
|
# - [Boolean] include_inactive user templates are not deleted, only set inactive. defaults to false.
|
|
105
105
|
# - [Boolean] inactive_only only include inactive user templates. defaults to false.
|
|
106
|
+
# - [Boolean] include_drag_and_drop Include templates created and saved using the new Drag & Drop editor. <strong>Note:</strong> You will not be able to edit or create new drag & drop templates via this API. This is useful only for creating a new campaign based on a drag & drop template.
|
|
106
107
|
# @return [Hash] for each type
|
|
107
108
|
# - [Array] user matching user templates, if requested.
|
|
108
109
|
# - [Int] id Id of the template
|
|
@@ -123,15 +124,7 @@ module Mailchimp
|
|
|
123
124
|
# - [String] date_created The date/time the template was created
|
|
124
125
|
# - [Boolean] active whether or not the template is active and available for use.
|
|
125
126
|
# - [Boolean] edit_source Whether or not you are able to edit the source of a template.
|
|
126
|
-
# - [Array] base matching base templates, if requested.
|
|
127
|
-
# - [Int] id Id of the template
|
|
128
|
-
# - [String] name Name of the template
|
|
129
|
-
# - [String] layout General description of the layout of the template
|
|
130
|
-
# - [String] category The category for the template, if there is one.
|
|
131
|
-
# - [String] preview_image If we've generated it, the url of the preview image for the template. We do out best to keep these up to date, but Preview image urls are not guaranteed to be available
|
|
132
|
-
# - [Boolean] active whether or not the template is active and available for use.
|
|
133
|
-
# - [String] date_created The date/time the template was created
|
|
134
|
-
# - [Boolean] edit_source Whether or not you are able to edit the source of a template.
|
|
127
|
+
# - [Array] base matching base templates, if requested. (Will always be empty as of 9.0)
|
|
135
128
|
def list(types=[], filters=[])
|
|
136
129
|
_params = {:types => types, :filters => filters}
|
|
137
130
|
return @master.call 'templates/list', _params
|
|
@@ -225,11 +218,29 @@ module Mailchimp
|
|
|
225
218
|
# - [String] email the email tied to the account used for passwords resets and the ilk
|
|
226
219
|
# - [String] role the role assigned to the account
|
|
227
220
|
# - [String] avatar if available, the url for the login's avatar
|
|
221
|
+
# - [Int] global_user_id the globally unique user id for the user account connected to
|
|
222
|
+
# - [String] dc_unique_id the datacenter unique id for the user account connected to, like helper/account-details
|
|
228
223
|
def logins()
|
|
229
224
|
_params = {}
|
|
230
225
|
return @master.call 'users/logins', _params
|
|
231
226
|
end
|
|
232
227
|
|
|
228
|
+
# Retrieve the profile for the login owning the provided API Key
|
|
229
|
+
# @return [Hash] the current user's details, including:
|
|
230
|
+
# - [Int] id the login id for this login
|
|
231
|
+
# - [String] username the username used to log in
|
|
232
|
+
# - [String] name a display name for the account - empty first/last names will return the username
|
|
233
|
+
# - [String] email the email tied to the account used for passwords resets and the ilk
|
|
234
|
+
# - [String] role the role assigned to the account
|
|
235
|
+
# - [String] avatar if available, the url for the login's avatar
|
|
236
|
+
# - [Int] global_user_id the globally unique user id for the user account connected to
|
|
237
|
+
# - [String] dc_unique_id the datacenter unique id for the user account connected to, like helper/account-details
|
|
238
|
+
# - [String] account_name The name of the account to which the API key belongs
|
|
239
|
+
def profile()
|
|
240
|
+
_params = {}
|
|
241
|
+
return @master.call 'users/profile', _params
|
|
242
|
+
end
|
|
243
|
+
|
|
233
244
|
end
|
|
234
245
|
class Helper
|
|
235
246
|
attr_accessor :master
|
|
@@ -241,7 +252,7 @@ module Mailchimp
|
|
|
241
252
|
# Retrieve lots of account information including payments made, plan info, some account stats, installed modules, contact info, and more. No private information like Credit Card numbers is available.
|
|
242
253
|
# @param [Array] exclude defaults to nothing for backwards compatibility. Allows controlling which extra arrays are returned since they can slow down calls. Valid keys are "modules", "orders", "rewards-credits", "rewards-inspections", "rewards-referrals", "rewards-applied", "integrations". Hint: "rewards-referrals" is typically the culprit. To avoid confusion, if data is excluded, the corresponding key <strong>will not be returned at all</strong>.
|
|
243
254
|
# @return [Hash] containing the details for the account tied to this API Key
|
|
244
|
-
# - [String] username The
|
|
255
|
+
# - [String] username The company name associated with the account
|
|
245
256
|
# - [String] user_id The Account user unique id (for building some links)
|
|
246
257
|
# - [Bool] is_trial Whether the Account is in Trial mode (can only send campaigns to less than 100 emails)
|
|
247
258
|
# - [Bool] is_approved Whether the Account has been approved for purchases
|
|
@@ -385,8 +396,8 @@ module Mailchimp
|
|
|
385
396
|
# - [String] leid the list email id (previously called web_id) for a list-member-info type call. this doesn't change when the email address changes
|
|
386
397
|
# @return [Array] An array of structs with info on the list_id the member is subscribed to.
|
|
387
398
|
# - [String] id the list unique id
|
|
388
|
-
# - [
|
|
389
|
-
# - [
|
|
399
|
+
# - [Int] web_id the id referenced in web interface urls
|
|
400
|
+
# - [String] name the list name
|
|
390
401
|
def lists_for_email(email)
|
|
391
402
|
_params = {:email => email}
|
|
392
403
|
return @master.call 'helper/lists-for-email', _params
|
|
@@ -409,8 +420,7 @@ module Mailchimp
|
|
|
409
420
|
# - [Int] total total campaigns matching
|
|
410
421
|
# - [Array] results matching campaigns and snippets
|
|
411
422
|
# - [String] snippet the matching snippet for the campaign
|
|
412
|
-
# - [Hash] campaign the matching campaign's details - will return same data as single campaign from campaigns()
|
|
413
|
-
# - [Hash] summary if available, the matching campaign's report/summary data, other wise empty
|
|
423
|
+
# - [Hash] campaign the matching campaign's details - will return same data as single campaign from campaigns/list()
|
|
414
424
|
def search_campaigns(query, offset=0, snip_start=nil, snip_end=nil)
|
|
415
425
|
_params = {:query => query, :offset => offset, :snip_start => snip_start, :snip_end => snip_end}
|
|
416
426
|
return @master.call 'helper/search-campaigns', _params
|
|
@@ -418,15 +428,15 @@ module Mailchimp
|
|
|
418
428
|
|
|
419
429
|
# Search account wide or on a specific list using the specified query terms
|
|
420
430
|
# @param [String] query terms to search on, <a href="http://kb.mailchimp.com/article/i-cant-find-a-recipient-on-my-list" target="_blank">just like you do in the app</a>
|
|
421
|
-
# @param [String] id optional the list id to limit the search to. Get by calling lists()
|
|
431
|
+
# @param [String] id optional the list id to limit the search to. Get by calling lists/list()
|
|
422
432
|
# @param [Int] offset optional the paging offset to use if more than 100 records match
|
|
423
433
|
# @return [Hash] An array of both exact matches and partial matches over a full search
|
|
424
|
-
# - [Hash] exact_matches containing the
|
|
425
|
-
#
|
|
426
|
-
#
|
|
434
|
+
# - [Hash] exact_matches containing the exact email address matches and current results
|
|
435
|
+
# - [Int] total total members matching
|
|
436
|
+
# - [Array] members each entry will be struct matching the data format for a single member as returned by lists/member-info()
|
|
427
437
|
# - [Hash] full_search containing the total matches and current results
|
|
428
|
-
#
|
|
429
|
-
#
|
|
438
|
+
# - [Int] total total members matching
|
|
439
|
+
# - [Array] members each entry will be struct matching the data format for a single member as returned by lists/member-info()
|
|
430
440
|
def search_members(query, id=nil, offset=0)
|
|
431
441
|
_params = {:query => query, :id => id, :offset => offset}
|
|
432
442
|
return @master.call 'helper/search-members', _params
|
|
@@ -450,6 +460,78 @@ module Mailchimp
|
|
|
450
460
|
@master = master
|
|
451
461
|
end
|
|
452
462
|
|
|
463
|
+
end
|
|
464
|
+
class Conversations
|
|
465
|
+
attr_accessor :master
|
|
466
|
+
|
|
467
|
+
def initialize(master)
|
|
468
|
+
@master = master
|
|
469
|
+
end
|
|
470
|
+
|
|
471
|
+
# Retrieve conversation metadata, includes message data for the most recent message in the conversation
|
|
472
|
+
# @param [String] list_id optional the list id to connect to. Get by calling lists/list()
|
|
473
|
+
# @param [String] leid optional The member's 'leid', as found by calling lists/member-info()
|
|
474
|
+
# @param [String] campaign_id the campaign id to get content for (can be gathered using campaigns/list())
|
|
475
|
+
# @param [Int] start optional - control paging, start results at this offset, defaults to 0 (1st page of data)
|
|
476
|
+
# @param [Int] limit optional - control paging, number of results to return with each call, defaults to 25 (max=100)
|
|
477
|
+
# @return [Hash] Conversation data and metadata
|
|
478
|
+
# - [Int] count Total number of conversations, irrespective of pagination.
|
|
479
|
+
# - [Array] data An array of structs representing individual conversations
|
|
480
|
+
# - [String] unique_id A string identifying this particular conversation
|
|
481
|
+
# - [Int] message_count The total number of messages in this conversation
|
|
482
|
+
# - [String] campaign_id The unique identifier of the campaign this conversation is associated with (will be null if the campaign has been deleted)
|
|
483
|
+
# - [String] list_id The unique identifier of the list this conversation is associated with
|
|
484
|
+
# - [Int] unread_messages The number of messages in this conversation which have not yet been read.
|
|
485
|
+
# - [String] from_label A label representing the sender of this message.
|
|
486
|
+
# - [String] from_email The email address of the sender of this message.
|
|
487
|
+
# - [String] subject The subject of the message.
|
|
488
|
+
# - [String] timestamp Date the message was either sent or received.
|
|
489
|
+
# - [Hash] last_message The most recent message in the conversation
|
|
490
|
+
# - [String] from_label A label representing the sender of this message.
|
|
491
|
+
# - [String] from_email The email address of the sender of this message.
|
|
492
|
+
# - [String] subject The subject of the message.
|
|
493
|
+
# - [String] message The plain-text content of the message.
|
|
494
|
+
# - [Boolean] read Whether or not this message has been marked as read.
|
|
495
|
+
# - [String] timestamp Date the message was either sent or received.
|
|
496
|
+
def list(list_id=nil, leid=nil, campaign_id=nil, start=0, limit=25)
|
|
497
|
+
_params = {:list_id => list_id, :leid => leid, :campaign_id => campaign_id, :start => start, :limit => limit}
|
|
498
|
+
return @master.call 'conversations/list', _params
|
|
499
|
+
end
|
|
500
|
+
|
|
501
|
+
# Retrieve conversation messages
|
|
502
|
+
# @param [String] conversation_id the unique_id of the conversation to retrieve the messages for, can be obtained by calling converstaions/list().
|
|
503
|
+
# @param [Boolean] mark_as_read optional Whether or not the conversation ought to be marked as read (defaults to false).
|
|
504
|
+
# @param [Int] start optional - control paging, start results at this offset, defaults to 1st page of data (offset 0)
|
|
505
|
+
# @param [Int] limit optional - control paging, number of results to return with each call, defaults to 25 (max=100)
|
|
506
|
+
# @return [Hash] Message data and metadata
|
|
507
|
+
# - [Int] count The number of messages in this conversation, irrespective of paging.
|
|
508
|
+
# - [Array] data An array of structs representing each message in a conversation
|
|
509
|
+
# - [String] from_label A label representing the sender of this message.
|
|
510
|
+
# - [String] from_email The email address of the sender of this message.
|
|
511
|
+
# - [String] subject The subject of the message.
|
|
512
|
+
# - [String] message The plain-text content of the message.
|
|
513
|
+
# - [Boolean] read Whether or not this message has been marked as read.
|
|
514
|
+
# - [String] timestamp Date the message was either sent or received.
|
|
515
|
+
def messages(conversation_id, mark_as_read=false, start=0, limit=25)
|
|
516
|
+
_params = {:conversation_id => conversation_id, :mark_as_read => mark_as_read, :start => start, :limit => limit}
|
|
517
|
+
return @master.call 'conversations/messages', _params
|
|
518
|
+
end
|
|
519
|
+
|
|
520
|
+
# Reply to a conversation
|
|
521
|
+
# @param [String] conversation_id the unique_id of the conversation to retrieve the messages for, can be obtained by calling converstaions/list().
|
|
522
|
+
# @param [String] message the text of the message you want to send.
|
|
523
|
+
# @return [Hash] Message data from the created message
|
|
524
|
+
# - [String] from_label A label representing the sender of this message.
|
|
525
|
+
# - [String] from_email The email address of the sender of this message.
|
|
526
|
+
# - [String] subject The subject of the message.
|
|
527
|
+
# - [String] message The plain-text content of the message.
|
|
528
|
+
# - [Boolean] read Whether or not this message has been marked as read.
|
|
529
|
+
# - [String] timestamp Date the message was either sent or received.
|
|
530
|
+
def reply(conversation_id, message)
|
|
531
|
+
_params = {:conversation_id => conversation_id, :message => message}
|
|
532
|
+
return @master.call 'conversations/reply', _params
|
|
533
|
+
end
|
|
534
|
+
|
|
453
535
|
end
|
|
454
536
|
class Ecomm
|
|
455
537
|
attr_accessor :master
|
|
@@ -474,9 +556,9 @@ module Mailchimp
|
|
|
474
556
|
# - [Int] line_num optional the line number of the item on the order. We will generate these if they are not passed
|
|
475
557
|
# - [Int] product_id the store's internal Id for the product. Lines that do no contain this will be skipped
|
|
476
558
|
# - [String] sku optional the store's internal SKU for the product. (max 30 bytes)
|
|
477
|
-
# - [String] product_name the product name for the product_id associated with this item. We will auto update these as they change (based on product_id)
|
|
478
|
-
# - [Int] category_id the store's internal Id for the (main) category associated with this product. Our testing has found this to be a "best guess" scenario
|
|
479
|
-
# - [String] category_name the category name for the category_id this product is in. Our testing has found this to be a "best guess" scenario. Our plugins walk the category heirarchy up and send "Root - SubCat1 - SubCat4", etc.
|
|
559
|
+
# - [String] product_name the product name for the product_id associated with this item. We will auto update these as they change (based on product_id) (max 500 bytes)
|
|
560
|
+
# - [Int] category_id (required) the store's internal Id for the (main) category associated with this product. Our testing has found this to be a "best guess" scenario
|
|
561
|
+
# - [String] category_name (required) the category name for the category_id this product is in. Our testing has found this to be a "best guess" scenario. Our plugins walk the category heirarchy up and send "Root - SubCat1 - SubCat4", etc.
|
|
480
562
|
# - [Double] qty optional the quantity of the item ordered - defaults to 1
|
|
481
563
|
# - [Double] cost optional the cost of a single item (ie, not the extended cost of the line) - defaults to 0
|
|
482
564
|
# @return [Hash] with a single entry:
|
|
@@ -543,24 +625,24 @@ module Mailchimp
|
|
|
543
625
|
end
|
|
544
626
|
|
|
545
627
|
# Get all email addresses that complained about a campaign sent to a list
|
|
546
|
-
# @param [String] id the list id to pull abuse reports for (can be gathered using lists())
|
|
628
|
+
# @param [String] id the list id to pull abuse reports for (can be gathered using lists/list())
|
|
547
629
|
# @param [Int] start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
|
|
548
630
|
# @param [Int] limit optional for large data sets, the number of results to return - defaults to 500, upper limit set at 1000
|
|
549
631
|
# @param [String] since optional pull only messages since this time - 24 hour format in <strong>GMT</strong>, eg "2013-12-30 20:30:00"
|
|
550
632
|
# @return [Hash] the total of all reports and the specific reports reports this page
|
|
551
633
|
# - [Int] total the total number of matching abuse reports
|
|
552
634
|
# - [Array] data structs for the actual data for each reports, including:
|
|
553
|
-
# - [String] date date
|
|
635
|
+
# - [String] date date+time the abuse report was received and processed
|
|
554
636
|
# - [String] email the email address that reported abuse
|
|
555
637
|
# - [String] campaign_id the unique id for the campaign that report was made against
|
|
556
|
-
# - [String] type an internal type generally specifying the
|
|
638
|
+
# - [String] type an internal type generally specifying the originating mail provider - may not be useful outside of filling report views
|
|
557
639
|
def abuse_reports(id, start=0, limit=500, since=nil)
|
|
558
640
|
_params = {:id => id, :start => start, :limit => limit, :since => since}
|
|
559
641
|
return @master.call 'lists/abuse-reports', _params
|
|
560
642
|
end
|
|
561
643
|
|
|
562
644
|
# Access up to the previous 180 days of daily detailed aggregated activity stats for a given list. Does not include AutoResponder activity.
|
|
563
|
-
# @param [String] id the list id to connect to. Get by calling lists()
|
|
645
|
+
# @param [String] id the list id to connect to. Get by calling lists/list()
|
|
564
646
|
# @return [Array] of structs containing daily values, each containing:
|
|
565
647
|
def activity(id)
|
|
566
648
|
_params = {:id => id}
|
|
@@ -568,7 +650,7 @@ module Mailchimp
|
|
|
568
650
|
end
|
|
569
651
|
|
|
570
652
|
# Subscribe a batch of email addresses to a list at once. If you are using a serialized version of the API, we strongly suggest that you only run this method as a POST request, and <em>not</em> a GET request. Maximum batch sizes vary based on the amount of data in each record, though you should cap them at 5k - 10k records, depending on your experience. These calls are also long, so be sure you increase your timeout values.
|
|
571
|
-
# @param [String] id the list id to connect to. Get by calling lists()
|
|
653
|
+
# @param [String] id the list id to connect to. Get by calling lists/list()
|
|
572
654
|
# @param [Array] batch an array of structs for each address using the following keys:
|
|
573
655
|
# - [Hash] email a struct with one of the following keys - failing to provide anything will produce an error relating to the email address. Provide multiples and we'll use the first we see in this same order.
|
|
574
656
|
# - [String] email an email address
|
|
@@ -605,7 +687,7 @@ module Mailchimp
|
|
|
605
687
|
end
|
|
606
688
|
|
|
607
689
|
# Unsubscribe a batch of email addresses from a list
|
|
608
|
-
# @param [String] id the list id to connect to. Get by calling lists()
|
|
690
|
+
# @param [String] id the list id to connect to. Get by calling lists/list()
|
|
609
691
|
# @param [Array] batch array of structs to unsubscribe, each with one of the following keys - failing to provide anything will produce an error relating to the email address. Provide multiples and we'll use the first we see in this same order.
|
|
610
692
|
# - [String] email an email address
|
|
611
693
|
# - [String] euid the unique id for an email address (not list related) - the email "id" returned from listMemberInfo, Webhooks, Campaigns, etc.
|
|
@@ -616,7 +698,6 @@ module Mailchimp
|
|
|
616
698
|
# @return [Array] Array of structs containing results and any errors that occurred
|
|
617
699
|
# - [Int] success_count Number of email addresses that were successfully removed
|
|
618
700
|
# - [Int] error_count Number of email addresses that failed during addition/updating
|
|
619
|
-
# - [Array] of structs contain error details including:
|
|
620
701
|
# - [Array] errors array of error structs including:
|
|
621
702
|
# - [String] email whatever was passed in the batch record's email parameter
|
|
622
703
|
# - [String] email the email address added
|
|
@@ -630,7 +711,7 @@ module Mailchimp
|
|
|
630
711
|
end
|
|
631
712
|
|
|
632
713
|
# Retrieve the clients that the list's subscribers have been tagged as being used based on user agents seen. Made possible by <a href="http://user-agent-string.info" target="_blank">user-agent-string.info</a>
|
|
633
|
-
# @param [String] id the list id to connect to. Get by calling lists()
|
|
714
|
+
# @param [String] id the list id to connect to. Get by calling lists/list()
|
|
634
715
|
# @return [Hash] the desktop and mobile user agents in use on the list
|
|
635
716
|
# - [Hash] desktop desktop user agents and percentages
|
|
636
717
|
# - [Double] penetration the percent of desktop clients in use
|
|
@@ -652,7 +733,7 @@ module Mailchimp
|
|
|
652
733
|
end
|
|
653
734
|
|
|
654
735
|
# Access the Growth History by Month in aggregate or for a given list.
|
|
655
|
-
# @param [String] id optional - if provided, the list id to connect to. Get by calling lists/list. Otherwise the aggregate for the account.
|
|
736
|
+
# @param [String] id optional - if provided, the list id to connect to. Get by calling lists/list(). Otherwise the aggregate for the account.
|
|
656
737
|
# @return [Array] array of structs containing months and growth data
|
|
657
738
|
# - [String] month The Year and Month in question using YYYY-MM format
|
|
658
739
|
# - [Int] existing number of existing subscribers to start the month
|
|
@@ -664,7 +745,7 @@ module Mailchimp
|
|
|
664
745
|
end
|
|
665
746
|
|
|
666
747
|
# Get the list of interest groupings for a given list, including the label, form information, and included groups for each
|
|
667
|
-
# @param [String] id the list id to connect to. Get by calling lists()
|
|
748
|
+
# @param [String] id the list id to connect to. Get by calling lists/list()
|
|
668
749
|
# @param [Bool] counts optional whether or not to return subscriber counts for each group. defaults to false since that slows this call down a ton for large lists.
|
|
669
750
|
# @return [Array] array of structs of the interest groupings for the list
|
|
670
751
|
# - [Int] id The id for the Grouping
|
|
@@ -681,9 +762,9 @@ module Mailchimp
|
|
|
681
762
|
end
|
|
682
763
|
|
|
683
764
|
# Add a single Interest Group - if interest groups for the List are not yet enabled, adding the first group will automatically turn them on.
|
|
684
|
-
# @param [String] id the list id to connect to. Get by calling lists()
|
|
765
|
+
# @param [String] id the list id to connect to. Get by calling lists/list()
|
|
685
766
|
# @param [String] group_name the interest group to add - group names must be unique within a grouping
|
|
686
|
-
# @param [Int] grouping_id optional The grouping to add the new group to - get using
|
|
767
|
+
# @param [Int] grouping_id optional The grouping to add the new group to - get using lists/interest-groupings() . If not supplied, the first grouping on the list is used.
|
|
687
768
|
# @return [Hash] with a single entry:
|
|
688
769
|
# - [Bool] complete whether the call worked. reallistically this will always be true as errors will be thrown otherwise.
|
|
689
770
|
def interest_group_add(id, group_name, grouping_id=nil)
|
|
@@ -692,9 +773,9 @@ module Mailchimp
|
|
|
692
773
|
end
|
|
693
774
|
|
|
694
775
|
# Delete a single Interest Group - if the last group for a list is deleted, this will also turn groups for the list off.
|
|
695
|
-
# @param [String] id the list id to connect to. Get by calling lists()
|
|
776
|
+
# @param [String] id the list id to connect to. Get by calling lists/list()
|
|
696
777
|
# @param [String] group_name the interest group to delete
|
|
697
|
-
# @param [Int] grouping_id The grouping to delete the group from - get using
|
|
778
|
+
# @param [Int] grouping_id The grouping to delete the group from - get using lists/interest-groupings() . If not supplied, the first grouping on the list is used.
|
|
698
779
|
# @return [Hash] with a single entry:
|
|
699
780
|
# - [Bool] complete whether the call worked. reallistically this will always be true as errors will be thrown otherwise.
|
|
700
781
|
def interest_group_del(id, group_name, grouping_id=nil)
|
|
@@ -703,10 +784,10 @@ module Mailchimp
|
|
|
703
784
|
end
|
|
704
785
|
|
|
705
786
|
# Change the name of an Interest Group
|
|
706
|
-
# @param [String] id the list id to connect to. Get by calling lists()
|
|
787
|
+
# @param [String] id the list id to connect to. Get by calling lists/list()
|
|
707
788
|
# @param [String] old_name the interest group name to be changed
|
|
708
789
|
# @param [String] new_name the new interest group name to be set
|
|
709
|
-
# @param [Int] grouping_id optional The grouping to delete the group from - get using
|
|
790
|
+
# @param [Int] grouping_id optional The grouping to delete the group from - get using lists/interest-groupings() . If not supplied, the first grouping on the list is used.
|
|
710
791
|
# @return [Hash] with a single entry:
|
|
711
792
|
# - [Bool] complete whether the call worked. reallistically this will always be true as errors will be thrown otherwise.
|
|
712
793
|
def interest_group_update(id, old_name, new_name, grouping_id=nil)
|
|
@@ -715,7 +796,7 @@ module Mailchimp
|
|
|
715
796
|
end
|
|
716
797
|
|
|
717
798
|
# Add a new Interest Grouping - if interest groups for the List are not yet enabled, adding the first grouping will automatically turn them on.
|
|
718
|
-
# @param [String] id the list id to connect to. Get by calling lists()
|
|
799
|
+
# @param [String] id the list id to connect to. Get by calling lists/list()
|
|
719
800
|
# @param [String] name the interest grouping to add - grouping names must be unique
|
|
720
801
|
# @param [String] type The type of the grouping to add - one of "checkboxes", "hidden", "dropdown", "radio"
|
|
721
802
|
# @param [Array] groups The lists of initial group names to be added - at least 1 is required and the names must be unique within a grouping. If the number takes you over the 60 group limit, an error will be thrown.
|
|
@@ -727,7 +808,7 @@ module Mailchimp
|
|
|
727
808
|
end
|
|
728
809
|
|
|
729
810
|
# Delete an existing Interest Grouping - this will permanently delete all contained interest groups and will remove those selections from all list members
|
|
730
|
-
# @param [Int] grouping_id the interest grouping id - get from
|
|
811
|
+
# @param [Int] grouping_id the interest grouping id - get from lists/interest-groupings()
|
|
731
812
|
# @return [Hash] with a single entry:
|
|
732
813
|
# - [Bool] complete whether the call worked. reallistically this will always be true as errors will be thrown otherwise.
|
|
733
814
|
def interest_grouping_del(grouping_id)
|
|
@@ -736,7 +817,7 @@ module Mailchimp
|
|
|
736
817
|
end
|
|
737
818
|
|
|
738
819
|
# Update an existing Interest Grouping
|
|
739
|
-
# @param [Int] grouping_id the interest grouping id - get from
|
|
820
|
+
# @param [Int] grouping_id the interest grouping id - get from lists/interest-groupings()
|
|
740
821
|
# @param [String] name The name of the field to update - either "name" or "type". Groups within the grouping should be manipulated using the standard listInterestGroup* methods
|
|
741
822
|
# @param [String] value The new value of the field. Grouping names must be unique - only "hidden" and "checkboxes" grouping types can be converted between each other.
|
|
742
823
|
# @return [Hash] with a single entry:
|
|
@@ -747,7 +828,7 @@ module Mailchimp
|
|
|
747
828
|
end
|
|
748
829
|
|
|
749
830
|
# Retrieve the locations (countries) that the list's subscribers have been tagged to based on geocoding their IP address
|
|
750
|
-
# @param [String] id the list id to connect to. Get by calling lists()
|
|
831
|
+
# @param [String] id the list id to connect to. Get by calling lists/list()
|
|
751
832
|
# @return [Array] array of locations
|
|
752
833
|
# - [String] country the country name
|
|
753
834
|
# - [String] cc the ISO 3166 2 digit country code
|
|
@@ -759,7 +840,7 @@ module Mailchimp
|
|
|
759
840
|
end
|
|
760
841
|
|
|
761
842
|
# Get the most recent 100 activities for particular list members (open, click, bounce, unsub, abuse, sent to, etc.)
|
|
762
|
-
# @param [String] id the list id to connect to. Get by calling lists()
|
|
843
|
+
# @param [String] id the list id to connect to. Get by calling lists/list()
|
|
763
844
|
# @param [Array] emails an array of up to 50 email structs, each with with one of the following keys
|
|
764
845
|
# - [String] email an email address - for new subscribers obviously this should be used
|
|
765
846
|
# - [String] euid the unique id for an email address (not list related) - the email "id" returned from listMemberInfo, Webhooks, Campaigns, etc.
|
|
@@ -781,7 +862,7 @@ module Mailchimp
|
|
|
781
862
|
# - [String] leid the list member's truly unique id
|
|
782
863
|
# - [Array] activity an array of structs containing the activity, including:
|
|
783
864
|
# - [String] action The action name, one of: open, click, bounce, unsub, abuse, sent, queued, ecomm, mandrill_send, mandrill_hard_bounce, mandrill_soft_bounce, mandrill_open, mandrill_click, mandrill_spam, mandrill_unsub, mandrill_reject
|
|
784
|
-
# - [String] timestamp The date
|
|
865
|
+
# - [String] timestamp The date+time of the action (GMT)
|
|
785
866
|
# - [String] url For click actions, the url clicked, otherwise this is empty
|
|
786
867
|
# - [String] type If there's extra bounce, unsub, etc data it will show up here.
|
|
787
868
|
# - [String] campaign_id The campaign id the action was related to, if it exists - otherwise empty (ie, direct unsub from list)
|
|
@@ -792,7 +873,7 @@ module Mailchimp
|
|
|
792
873
|
end
|
|
793
874
|
|
|
794
875
|
# Get all the information for particular members of a list
|
|
795
|
-
# @param [String] id the list id to connect to. Get by calling lists()
|
|
876
|
+
# @param [String] id the list id to connect to. Get by calling lists/list()
|
|
796
877
|
# @param [Array] emails an array of up to 50 email structs, each with with one of the following keys
|
|
797
878
|
# - [String] email an email address - for new subscribers obviously this should be used
|
|
798
879
|
# - [String] euid the unique id for an email address (not list related) - the email "id" returned from listMemberInfo, Webhooks, Campaigns, etc.
|
|
@@ -819,15 +900,15 @@ module Mailchimp
|
|
|
819
900
|
# - [Bool] interested whether the member has this group selected
|
|
820
901
|
# - [String] status The subscription status for this email address, either pending, subscribed, unsubscribed, or cleaned
|
|
821
902
|
# - [String] ip_signup IP Address this address signed up from. This may be blank if single optin is used.
|
|
822
|
-
# - [String] timestamp_signup The date
|
|
903
|
+
# - [String] timestamp_signup The date+time the double optin was initiated. This may be blank if single optin is used.
|
|
823
904
|
# - [String] ip_opt IP Address this address opted in from.
|
|
824
|
-
# - [String] timestamp_opt The date
|
|
905
|
+
# - [String] timestamp_opt The date+time the optin completed
|
|
825
906
|
# - [Int] member_rating the rating of the subscriber. This will be 1 - 5 as described <a href="http://eepurl.com/f-2P" target="_blank">here</a>
|
|
826
907
|
# - [String] campaign_id If the user is unsubscribed and they unsubscribed from a specific campaign, that campaign_id will be listed, otherwise this is not returned.
|
|
827
908
|
# - [Array] lists An array of structs for the other lists this member belongs to
|
|
828
909
|
# - [String] id the list id
|
|
829
910
|
# - [String] status the members status on that list
|
|
830
|
-
# - [String] timestamp The date
|
|
911
|
+
# - [String] timestamp The date+time this email address entered it's current status
|
|
831
912
|
# - [String] info_changed The last time this record was changed. If the record is old enough, this may be blank.
|
|
832
913
|
# - [Int] web_id The Member id used in our web app, allows you to create a link directly to it
|
|
833
914
|
# - [Int] leid The Member id used in our web app, allows you to create a link directly to it
|
|
@@ -861,8 +942,8 @@ module Mailchimp
|
|
|
861
942
|
return @master.call 'lists/member-info', _params
|
|
862
943
|
end
|
|
863
944
|
|
|
864
|
-
# Get all of the list members for a list that are of a particular status and potentially matching a segment. This will cause locking, so don't run multiples at once. Are you trying to get a dump including lots of merge data or specific members of a list? If so, checkout the <a href="export/1.0/list.func.php">List Export API</a>
|
|
865
|
-
# @param [String] id the list id to connect to. Get by calling lists()
|
|
945
|
+
# Get all of the list members for a list that are of a particular status and potentially matching a segment. This will cause locking, so don't run multiples at once. Are you trying to get a dump including lots of merge data or specific members of a list? If so, checkout the <a href="/export/1.0/list.func.php">List Export API</a>
|
|
946
|
+
# @param [String] id the list id to connect to. Get by calling lists/list()
|
|
866
947
|
# @param [String] status the status to get members for - one of(subscribed, unsubscribed, <a target="_blank" href="http://eepurl.com/gWOO">cleaned</a>), defaults to subscribed
|
|
867
948
|
# @param [Hash] opts various options for controlling returned data
|
|
868
949
|
# - [Int] start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
|
|
@@ -879,16 +960,16 @@ module Mailchimp
|
|
|
879
960
|
end
|
|
880
961
|
|
|
881
962
|
# Add a new merge tag to a given list
|
|
882
|
-
# @param [String] id the list id to connect to. Get by calling lists()
|
|
963
|
+
# @param [String] id the list id to connect to. Get by calling lists/list()
|
|
883
964
|
# @param [String] tag The merge tag to add, e.g. FNAME. 10 bytes max, valid characters: "A-Z 0-9 _" no spaces, dashes, etc. Some tags and prefixes are <a href="http://kb.mailchimp.com/article/i-got-a-message-saying-that-my-list-field-name-is-reserved-and-cant-be-used" target="_blank">reserved</a>
|
|
884
965
|
# @param [String] name The long description of the tag being added, used for user displays - max 50 bytes
|
|
885
|
-
# @param [
|
|
966
|
+
# @param [Hash] options optional Various options for this merge var
|
|
886
967
|
# - [String] field_type optional one of: text, number, radio, dropdown, date, address, phone, url, imageurl, zip, birthday - defaults to text
|
|
887
968
|
# - [Boolean] req optional indicates whether the field is required - defaults to false
|
|
888
969
|
# - [Boolean] public optional indicates whether the field is displayed in public - defaults to true
|
|
889
970
|
# - [Boolean] show optional indicates whether the field is displayed in the app's list member view - defaults to true
|
|
890
971
|
# - [Int] order The order this merge tag should be displayed in - this will cause existing values to be reset so this fits
|
|
891
|
-
# - [String] default_value optional the default value for the field. See subscribe() for formatting info. Defaults to blank - max 255 bytes
|
|
972
|
+
# - [String] default_value optional the default value for the field. See lists/subscribe() for formatting info. Defaults to blank - max 255 bytes
|
|
892
973
|
# - [String] helptext optional the help text to be used with some newer forms. Defaults to blank - max 255 bytes
|
|
893
974
|
# - [Array] choices optional kind of - an array of strings to use as the choices for radio and dropdown type fields
|
|
894
975
|
# - [String] dateformat optional only valid for birthday and date fields. For birthday type, must be "MM/DD" (default) or "DD/MM". For date type, must be "MM/DD/YYYY" (default) or "DD/MM/YYYY". Any other values will be converted to the default.
|
|
@@ -904,7 +985,7 @@ module Mailchimp
|
|
|
904
985
|
# - [String] default The default value for this field
|
|
905
986
|
# - [String] helptext The helptext for this field
|
|
906
987
|
# - [String] size The width of the field to be used
|
|
907
|
-
# - [String] tag The merge tag that's used for forms and subscribe() and
|
|
988
|
+
# - [String] tag The merge tag that's used for forms and lists/subscribe() and lists/update-member()
|
|
908
989
|
# - [Array] choices the options available for radio and dropdown field types
|
|
909
990
|
# - [Int] id an unchanging id for the merge var
|
|
910
991
|
def merge_var_add(id, tag, name, options=[])
|
|
@@ -913,7 +994,7 @@ module Mailchimp
|
|
|
913
994
|
end
|
|
914
995
|
|
|
915
996
|
# Delete a merge tag from a given list and all its members. Seriously - the data is removed from all members as well! Note that on large lists this method may seem a bit slower than calls you typically make.
|
|
916
|
-
# @param [String] id the list id to connect to. Get by calling lists()
|
|
997
|
+
# @param [String] id the list id to connect to. Get by calling lists/list()
|
|
917
998
|
# @param [String] tag The merge tag to delete
|
|
918
999
|
# @return [Hash] with a single entry:
|
|
919
1000
|
# - [Bool] complete whether the call worked. reallistically this will always be true as errors will be thrown otherwise.
|
|
@@ -923,7 +1004,7 @@ module Mailchimp
|
|
|
923
1004
|
end
|
|
924
1005
|
|
|
925
1006
|
# Completely resets all data stored in a merge var on a list. All data is removed and this action can not be undone.
|
|
926
|
-
# @param [String] id the list id to connect to. Get by calling lists()
|
|
1007
|
+
# @param [String] id the list id to connect to. Get by calling lists/list()
|
|
927
1008
|
# @param [String] tag The merge tag to reset
|
|
928
1009
|
# @return [Hash] with a single entry:
|
|
929
1010
|
# - [Bool] complete whether the call worked. reallistically this will always be true as errors will be thrown otherwise.
|
|
@@ -933,9 +1014,9 @@ module Mailchimp
|
|
|
933
1014
|
end
|
|
934
1015
|
|
|
935
1016
|
# Sets a particular merge var to the specified value for every list member. Only merge var ids 1 - 30 may be modified this way. This is generally a dirty method unless you're fixing data since you should probably be using default_values and/or conditional content. as with lists/merge-var-reset(), this can not be undone.
|
|
936
|
-
# @param [String] id the list id to connect to. Get by calling lists()
|
|
1017
|
+
# @param [String] id the list id to connect to. Get by calling lists/list()
|
|
937
1018
|
# @param [String] tag The merge tag to reset
|
|
938
|
-
# @param [String] value The value to set - see subscribe() for formatting. Must validate to something non-empty.
|
|
1019
|
+
# @param [String] value The value to set - see lists/subscribe() for formatting. Must validate to something non-empty.
|
|
939
1020
|
# @return [Hash] with a single entry:
|
|
940
1021
|
# - [Bool] complete whether the call worked. reallistically this will always be true as errors will be thrown otherwise.
|
|
941
1022
|
def merge_var_set(id, tag, value)
|
|
@@ -944,9 +1025,9 @@ module Mailchimp
|
|
|
944
1025
|
end
|
|
945
1026
|
|
|
946
1027
|
# Update most parameters for a merge tag on a given list. You cannot currently change the merge type
|
|
947
|
-
# @param [String] id the list id to connect to. Get by calling lists()
|
|
1028
|
+
# @param [String] id the list id to connect to. Get by calling lists/list()
|
|
948
1029
|
# @param [String] tag The merge tag to update
|
|
949
|
-
# @param [Hash] options The options to change for a merge var. See
|
|
1030
|
+
# @param [Hash] options The options to change for a merge var. See lists/merge-var-add() for valid options. "tag" and "name" may also be used here.
|
|
950
1031
|
# @return [Hash] the full data for the new merge var, just like merge-vars returns
|
|
951
1032
|
# - [String] name Name/description of the merge field
|
|
952
1033
|
# - [Bool] req Denotes whether the field is required (true) or not (false)
|
|
@@ -957,7 +1038,7 @@ module Mailchimp
|
|
|
957
1038
|
# - [String] default The default value for this field
|
|
958
1039
|
# - [String] helptext The helptext for this field
|
|
959
1040
|
# - [String] size The width of the field to be used
|
|
960
|
-
# - [String] tag The merge tag that's used for forms and subscribe() and
|
|
1041
|
+
# - [String] tag The merge tag that's used for forms and lists/subscribe() and lists/update-member()
|
|
961
1042
|
# - [Array] choices the options available for radio and dropdown field types
|
|
962
1043
|
# - [Int] id an unchanging id for the merge var
|
|
963
1044
|
def merge_var_update(id, tag, options)
|
|
@@ -966,7 +1047,7 @@ module Mailchimp
|
|
|
966
1047
|
end
|
|
967
1048
|
|
|
968
1049
|
# Get the list of merge tags for a given list, including their name, tag, and required setting
|
|
969
|
-
# @param [Array] id the list ids to retrieve merge vars for. Get by calling lists() - max of 100
|
|
1050
|
+
# @param [Array] id the list ids to retrieve merge vars for. Get by calling lists/list() - max of 100
|
|
970
1051
|
# @return [Hash] of data and success/error counts
|
|
971
1052
|
# - [Int] success_count the number of subscribers successfully found on the list
|
|
972
1053
|
# - [Int] error_count the number of subscribers who were not found on the list
|
|
@@ -983,7 +1064,7 @@ module Mailchimp
|
|
|
983
1064
|
# - [String] default The default value the list owner has set for this field
|
|
984
1065
|
# - [String] helptext The helptext for this field
|
|
985
1066
|
# - [String] size The width of the field to be used
|
|
986
|
-
# - [String] tag The merge tag that's used for forms and
|
|
1067
|
+
# - [String] tag The merge tag that's used for forms and lists/subscribe() and listUpdateMember()
|
|
987
1068
|
# - [Array] choices For radio and dropdown field types, an array of the options available
|
|
988
1069
|
# - [Int] id an unchanging id for the merge var
|
|
989
1070
|
# - [Array] errors of error structs
|
|
@@ -995,8 +1076,80 @@ module Mailchimp
|
|
|
995
1076
|
return @master.call 'lists/merge-vars', _params
|
|
996
1077
|
end
|
|
997
1078
|
|
|
1079
|
+
# Retrieve all of Segments for a list.
|
|
1080
|
+
# @param [String] id the list id to connect to. Get by calling lists/list()
|
|
1081
|
+
# @param [String] type optional, if specified should be "static" or "saved" and will limit the returned entries to that type
|
|
1082
|
+
# @return [Hash] with 2 keys:
|
|
1083
|
+
# - [Array] static of structs with data for each segment
|
|
1084
|
+
# - [Int] id the id of the segment
|
|
1085
|
+
# - [String] name the name for the segment
|
|
1086
|
+
# - [String] created_date the date+time the segment was created
|
|
1087
|
+
# - [String] last_update the date+time the segment was last updated (add or del)
|
|
1088
|
+
# - [String] last_reset the date+time the segment was last reset (ie had all members cleared from it)
|
|
1089
|
+
# - [Array] saved of structs with data for each segment
|
|
1090
|
+
# - [Int] id the id of the segment
|
|
1091
|
+
# - [String] name the name for the segment
|
|
1092
|
+
# - [String] segment_opts same match+conditions struct typically used
|
|
1093
|
+
# - [String] segment_text a textual description of the segment match/conditions
|
|
1094
|
+
# - [String] created_date the date+time the segment was created
|
|
1095
|
+
# - [String] last_update the date+time the segment was last updated (add or del)
|
|
1096
|
+
def segments(id, type=nil)
|
|
1097
|
+
_params = {:id => id, :type => type}
|
|
1098
|
+
return @master.call 'lists/segments', _params
|
|
1099
|
+
end
|
|
1100
|
+
|
|
1101
|
+
# Save a segment against a list for later use. There is no limit to the number of segments which can be saved. Static Segments <strong>are not</strong> tied to any merge data, interest groups, etc. They essentially allow you to configure an unlimited number of custom segments which will have standard performance. When using proper segments, Static Segments are one of the available options for segmentation just as if you used a merge var (and they can be used with other segmentation options), though performance may degrade at that point. Saved Segments (called "auto-updating" in the app) are essentially just the match+conditions typically used.
|
|
1102
|
+
# @param [String] id the list id to connect to. Get by calling lists/list()
|
|
1103
|
+
# @param [Hash] opts various options for the new segment
|
|
1104
|
+
# - [String] type either "static" or "saved"
|
|
1105
|
+
# - [String] name a unique name per list for the segment - 100 byte maximum length, anything longer will throw an error
|
|
1106
|
+
# - [Hash] segment_opts for "saved" only, the standard segment match+conditions, just like campaigns/segment-test
|
|
1107
|
+
# - [String] match "any" or "all"
|
|
1108
|
+
# - [Array] conditions structs for each condition, just like campaigns/segment-test
|
|
1109
|
+
# @return [Hash] with a single entry:
|
|
1110
|
+
# - [Int] id the id of the new segment, otherwise an error will be thrown.
|
|
1111
|
+
def segment_add(id, opts)
|
|
1112
|
+
_params = {:id => id, :opts => opts}
|
|
1113
|
+
return @master.call 'lists/segment-add', _params
|
|
1114
|
+
end
|
|
1115
|
+
|
|
1116
|
+
# Delete a segment. Note that this will, of course, remove any member affiliations with any static segments deleted
|
|
1117
|
+
# @param [String] id the list id to connect to. Get by calling lists/list()
|
|
1118
|
+
# @param [Int] seg_id the id of the static segment to delete - get from lists/static-segments()
|
|
1119
|
+
# @return [Hash] with a single entry:
|
|
1120
|
+
# - [Bool] complete whether the call worked. reallistically this will always be true as errors will be thrown otherwise.
|
|
1121
|
+
def segment_del(id, seg_id)
|
|
1122
|
+
_params = {:id => id, :seg_id => seg_id}
|
|
1123
|
+
return @master.call 'lists/segment-del', _params
|
|
1124
|
+
end
|
|
1125
|
+
|
|
1126
|
+
# Allows one to test their segmentation rules before creating a campaign using them - this is no different from campaigns/segment-test() and will eventually replace it. For the time being, the crazy segmenting condition documentation will continue to live over there.
|
|
1127
|
+
# @param [String] list_id the list to test segmentation on - get lists using lists/list()
|
|
1128
|
+
# @param [Hash] options See the campaigns/segment-test() call for details.
|
|
1129
|
+
# @return [Hash] with a single entry:
|
|
1130
|
+
# - [Int] total The total number of subscribers matching your segmentation options
|
|
1131
|
+
def segment_test(list_id, options)
|
|
1132
|
+
_params = {:list_id => list_id, :options => options}
|
|
1133
|
+
return @master.call 'lists/segment-test', _params
|
|
1134
|
+
end
|
|
1135
|
+
|
|
1136
|
+
# Update an existing segment. The list and type can not be changed.
|
|
1137
|
+
# @param [String] id the list id to connect to. Get by calling lists/list()
|
|
1138
|
+
# @param [Int] seg_id the segment to updated. Get by calling lists/segments()
|
|
1139
|
+
# @param [Hash] opts various options to update
|
|
1140
|
+
# - [String] name a unique name per list for the segment - 100 byte maximum length, anything longer will throw an error
|
|
1141
|
+
# - [Hash] segment_opts for "saved" only, the standard segment match+conditions, just like campaigns/segment-test
|
|
1142
|
+
# - [String] match "any" or "all"
|
|
1143
|
+
# - [Array] conditions structs for each condition, just like campaigns/segment-test
|
|
1144
|
+
# @return [Hash] with a single entry:
|
|
1145
|
+
# - [Bool] complete whether the call worked. reallistically this will always be true as errors will be thrown otherwise.
|
|
1146
|
+
def segment_update(id, seg_id, opts)
|
|
1147
|
+
_params = {:id => id, :seg_id => seg_id, :opts => opts}
|
|
1148
|
+
return @master.call 'lists/segment-update', _params
|
|
1149
|
+
end
|
|
1150
|
+
|
|
998
1151
|
# Save a segment against a list for later use. There is no limit to the number of segments which can be saved. Static Segments <strong>are not</strong> tied to any merge data, interest groups, etc. They essentially allow you to configure an unlimited number of custom segments which will have standard performance. When using proper segments, Static Segments are one of the available options for segmentation just as if you used a merge var (and they can be used with other segmentation options), though performance may degrade at that point.
|
|
999
|
-
# @param [String] id the list id to connect to. Get by calling lists()
|
|
1152
|
+
# @param [String] id the list id to connect to. Get by calling lists/list()
|
|
1000
1153
|
# @param [String] name a unique name per list for the segment - 100 byte maximum length, anything longer will throw an error
|
|
1001
1154
|
# @return [Hash] with a single entry:
|
|
1002
1155
|
# - [Int] id the id of the new segment, otherwise an error will be thrown.
|
|
@@ -1006,8 +1159,8 @@ module Mailchimp
|
|
|
1006
1159
|
end
|
|
1007
1160
|
|
|
1008
1161
|
# Delete a static segment. Note that this will, of course, remove any member affiliations with the segment
|
|
1009
|
-
# @param [String] id the list id to connect to. Get by calling lists()
|
|
1010
|
-
# @param [Int] seg_id the id of the static segment to delete - get from
|
|
1162
|
+
# @param [String] id the list id to connect to. Get by calling lists/list()
|
|
1163
|
+
# @param [Int] seg_id the id of the static segment to delete - get from lists/static-segments()
|
|
1011
1164
|
# @return [Hash] with a single entry:
|
|
1012
1165
|
# - [Bool] complete whether the call worked. reallistically this will always be true as errors will be thrown otherwise.
|
|
1013
1166
|
def static_segment_del(id, seg_id)
|
|
@@ -1016,15 +1169,15 @@ module Mailchimp
|
|
|
1016
1169
|
end
|
|
1017
1170
|
|
|
1018
1171
|
# Add list members to a static segment. It is suggested that you limit batch size to no more than 10,000 addresses per call. Email addresses must exist on the list in order to be included - this <strong>will not</strong> subscribe them to the list!
|
|
1019
|
-
# @param [String] id the list id to connect to. Get by calling lists()
|
|
1020
|
-
# @param [Int] seg_id the id of the static segment to modify - get from
|
|
1021
|
-
# @param [Array] batch an array of structs
|
|
1022
|
-
# - [
|
|
1023
|
-
#
|
|
1024
|
-
#
|
|
1025
|
-
# - [String] leid the list email id (previously called web_id) for a list-member-info type call. this doesn't change when the email address changes
|
|
1172
|
+
# @param [String] id the list id to connect to. Get by calling lists/list()
|
|
1173
|
+
# @param [Int] seg_id the id of the static segment to modify - get from lists/static-segments()
|
|
1174
|
+
# @param [Array] batch an array of email structs, each with with one of the following keys:
|
|
1175
|
+
# - [String] email an email address
|
|
1176
|
+
# - [String] euid the unique id for an email address (not list related) - the email "id" returned from lists/member-info(), Webhooks, Campaigns, etc.
|
|
1177
|
+
# - [String] leid the list email id (previously called web_id) for a list-member-info type call. this doesn't change when the email address changes
|
|
1026
1178
|
# @return [Hash] an array with the results of the operation
|
|
1027
1179
|
# - [Int] success_count the total number of successful updates (will include members already in the segment)
|
|
1180
|
+
# - [Int] error_count the total number of errors
|
|
1028
1181
|
# - [Array] errors structs for each error including:
|
|
1029
1182
|
# - [String] email whatever was passed in the email parameter
|
|
1030
1183
|
# - [String] email the email address added
|
|
@@ -1038,13 +1191,12 @@ module Mailchimp
|
|
|
1038
1191
|
end
|
|
1039
1192
|
|
|
1040
1193
|
# Remove list members from a static segment. It is suggested that you limit batch size to no more than 10,000 addresses per call. Email addresses must exist on the list in order to be removed - this <strong>will not</strong> unsubscribe them from the list!
|
|
1041
|
-
# @param [String] id the list id to connect to. Get by calling lists()
|
|
1042
|
-
# @param [Int] seg_id the id of the static segment to delete - get from
|
|
1043
|
-
# @param [Array] batch an array of structs for each address using the following keys:
|
|
1044
|
-
# - [
|
|
1045
|
-
#
|
|
1046
|
-
#
|
|
1047
|
-
# - [String] leid the list email id (previously called web_id) for a list-member-info type call. this doesn't change when the email address changes
|
|
1194
|
+
# @param [String] id the list id to connect to. Get by calling lists/list()
|
|
1195
|
+
# @param [Int] seg_id the id of the static segment to delete - get from lists/static-segments()
|
|
1196
|
+
# @param [Array] batch an array of structs for each address using one of the following keys:
|
|
1197
|
+
# - [String] email an email address
|
|
1198
|
+
# - [String] euid the unique id for an email address (not list related) - the email "id" returned from listMemberInfo, Webhooks, Campaigns, etc.
|
|
1199
|
+
# - [String] leid the list email id (previously called web_id) for a list-member-info type call. this doesn't change when the email address changes
|
|
1048
1200
|
# @return [Hash] an array with the results of the operation
|
|
1049
1201
|
# - [Int] success_count the total number of successful removals
|
|
1050
1202
|
# - [Int] error_count the total number of unsuccessful removals
|
|
@@ -1061,8 +1213,8 @@ module Mailchimp
|
|
|
1061
1213
|
end
|
|
1062
1214
|
|
|
1063
1215
|
# Resets a static segment - removes <strong>all</strong> members from the static segment. Note: does not actually affect list member data
|
|
1064
|
-
# @param [String] id the list id to connect to. Get by calling lists()
|
|
1065
|
-
# @param [Int] seg_id the id of the static segment to reset - get from
|
|
1216
|
+
# @param [String] id the list id to connect to. Get by calling lists/list()
|
|
1217
|
+
# @param [Int] seg_id the id of the static segment to reset - get from lists/static-segments()
|
|
1066
1218
|
# @return [Hash] with a single entry:
|
|
1067
1219
|
# - [Bool] complete whether the call worked. reallistically this will always be true as errors will be thrown otherwise.
|
|
1068
1220
|
def static_segment_reset(id, seg_id)
|
|
@@ -1071,27 +1223,30 @@ module Mailchimp
|
|
|
1071
1223
|
end
|
|
1072
1224
|
|
|
1073
1225
|
# Retrieve all of the Static Segments for a list.
|
|
1074
|
-
# @param [String] id the list id to connect to. Get by calling lists()
|
|
1226
|
+
# @param [String] id the list id to connect to. Get by calling lists/list()
|
|
1227
|
+
# @param [Boolean] get_counts optional Retreiving counts for static segments can be slow, leaving them out can speed up this call. Defaults to 'true'.
|
|
1228
|
+
# @param [Int] start optional - control paging, start results at this offset, defaults to 1st page of data (offset 0)
|
|
1229
|
+
# @param [Int] limit optional - control paging, number of results to return with each call, returns all by default
|
|
1075
1230
|
# @return [Array] an of structs with data for each static segment
|
|
1076
1231
|
# - [Int] id the id of the segment
|
|
1077
1232
|
# - [String] name the name for the segment
|
|
1078
1233
|
# - [Int] member_count the total number of subscribed members currently in a segment
|
|
1079
|
-
# - [String] created_date the date
|
|
1080
|
-
# - [String] last_update the date
|
|
1081
|
-
# - [String] last_reset the date
|
|
1082
|
-
def static_segments(id)
|
|
1083
|
-
_params = {:id => id}
|
|
1234
|
+
# - [String] created_date the date+time the segment was created
|
|
1235
|
+
# - [String] last_update the date+time the segment was last updated (add or del)
|
|
1236
|
+
# - [String] last_reset the date+time the segment was last reset (ie had all members cleared from it)
|
|
1237
|
+
def static_segments(id, get_counts=true, start=0, limit=nil)
|
|
1238
|
+
_params = {:id => id, :get_counts => get_counts, :start => start, :limit => limit}
|
|
1084
1239
|
return @master.call 'lists/static-segments', _params
|
|
1085
1240
|
end
|
|
1086
1241
|
|
|
1087
1242
|
# Subscribe the provided email to a list. By default this sends a confirmation email - you will not see new members until the link contained in it is clicked!
|
|
1088
1243
|
# @param [String] id the list id to connect to. Get by calling lists/list()
|
|
1089
|
-
# @param [Hash] email a struct with one of the following keys - failing to provide anything will produce an error relating to the email address.
|
|
1244
|
+
# @param [Hash] email a struct with one of the following keys - failing to provide anything will produce an error relating to the email address. If multiple keys are provided, the first one from the following list that we find will be used, the rest will be ignored.
|
|
1090
1245
|
# - [String] email an email address - for new subscribers obviously this should be used
|
|
1091
1246
|
# - [String] euid the unique id for an email address (not list related) - the email "id" returned from listMemberInfo, Webhooks, Campaigns, etc.
|
|
1092
1247
|
# - [String] leid the list email id (previously called web_id) for a list-member-info type call. this doesn't change when the email address changes
|
|
1093
|
-
# @param [Hash] merge_vars optional merges for the email (FNAME, LNAME, <a href="http://kb.mailchimp.com/article/where-can-i-find-my-lists-merge-tags target="_blank">etc.</a>) (see examples below for handling "blank" arrays). Note that a merge field can only hold up to 255 bytes. Also, there are a few "special" keys:
|
|
1094
|
-
# - [String] new-email set this to change the email address. This is only respected on calls using update_existing or when passed to
|
|
1248
|
+
# @param [Hash] merge_vars optional merges for the email (FNAME, LNAME, <a href="http://kb.mailchimp.com/article/where-can-i-find-my-lists-merge-tags" target="_blank">etc.</a>) (see examples below for handling "blank" arrays). Note that a merge field can only hold up to 255 bytes. Also, there are a few "special" keys:
|
|
1249
|
+
# - [String] new-email set this to change the email address. This is only respected on calls using update_existing or when passed to lists/update.
|
|
1095
1250
|
# - [Array] groupings of Interest Grouping structs. Each should contain:
|
|
1096
1251
|
# - [Int] id Grouping "id" from lists/interest-groupings (either this or name must be present) - this id takes precedence and can't change (unlike the name)
|
|
1097
1252
|
# - [String] name Grouping "name" from lists/interest-groupings (either this or id must be present)
|
|
@@ -1122,8 +1277,8 @@ module Mailchimp
|
|
|
1122
1277
|
end
|
|
1123
1278
|
|
|
1124
1279
|
# Unsubscribe the given email address from the list
|
|
1125
|
-
# @param [String] id the list id to connect to. Get by calling lists()
|
|
1126
|
-
# @param [Hash] email a struct with one of the following keys - failing to provide anything will produce an error relating to the email address.
|
|
1280
|
+
# @param [String] id the list id to connect to. Get by calling lists/list()
|
|
1281
|
+
# @param [Hash] email a struct with one of the following keys - failing to provide anything will produce an error relating to the email address. If multiple keys are provided, the first one from the following list that we find will be used, the rest will be ignored.
|
|
1127
1282
|
# - [String] email an email address
|
|
1128
1283
|
# - [String] euid the unique id for an email address (not list related) - the email "id" returned from listMemberInfo, Webhooks, Campaigns, etc.
|
|
1129
1284
|
# - [String] leid the list email id (previously called web_id) for a list-member-info type call. this doesn't change when the email address changes
|
|
@@ -1137,13 +1292,13 @@ module Mailchimp
|
|
|
1137
1292
|
return @master.call 'lists/unsubscribe', _params
|
|
1138
1293
|
end
|
|
1139
1294
|
|
|
1140
|
-
# Edit the email address, merge fields, and interest groups for a list member. If you are doing a batch update on lots of users, consider using
|
|
1141
|
-
# @param [String] id the list id to connect to. Get by calling lists()
|
|
1142
|
-
# @param [Hash] email a struct with one of the following keys - failing to provide anything will produce an error relating to the email address.
|
|
1295
|
+
# Edit the email address, merge fields, and interest groups for a list member. If you are doing a batch update on lots of users, consider using lists/batch-subscribe() with the update_existing and possible replace_interests parameter.
|
|
1296
|
+
# @param [String] id the list id to connect to. Get by calling lists/list()
|
|
1297
|
+
# @param [Hash] email a struct with one of the following keys - failing to provide anything will produce an error relating to the email address. If multiple keys are provided, the first one from the following list that we find will be used, the rest will be ignored.
|
|
1143
1298
|
# - [String] email an email address
|
|
1144
1299
|
# - [String] euid the unique id for an email address (not list related) - the email "id" returned from listMemberInfo, Webhooks, Campaigns, etc.
|
|
1145
1300
|
# - [String] leid the list email id (previously called web_id) for a list-member-info type call. this doesn't change when the email address changes
|
|
1146
|
-
# @param [
|
|
1301
|
+
# @param [Hash] merge_vars new field values to update the member with. See merge_vars in lists/subscribe() for details.
|
|
1147
1302
|
# @param [String] email_type change the email type preference for the member ("html" or "text"). Leave blank to keep the existing preference (optional)
|
|
1148
1303
|
# @param [Boolean] replace_interests flag to determine whether we replace the interest groups with the updated groups provided, or we add the provided groups to the member's interest groups (optional, defaults to true)
|
|
1149
1304
|
# @return [Hash] the ids for this subscriber
|
|
@@ -1156,7 +1311,7 @@ module Mailchimp
|
|
|
1156
1311
|
end
|
|
1157
1312
|
|
|
1158
1313
|
# Add a new Webhook URL for the given list
|
|
1159
|
-
# @param [String] id the list id to connect to. Get by calling lists()
|
|
1314
|
+
# @param [String] id the list id to connect to. Get by calling lists/list()
|
|
1160
1315
|
# @param [String] url a valid URL for the Webhook - it will be validated. note that a url may only exist on a list once.
|
|
1161
1316
|
# @param [Hash] actions optional a hash of actions to fire this Webhook for
|
|
1162
1317
|
# - [Bool] subscribe optional as subscribes occur, defaults to true
|
|
@@ -1177,7 +1332,7 @@ module Mailchimp
|
|
|
1177
1332
|
end
|
|
1178
1333
|
|
|
1179
1334
|
# Delete an existing Webhook URL from a given list
|
|
1180
|
-
# @param [String] id the list id to connect to. Get by calling lists()
|
|
1335
|
+
# @param [String] id the list id to connect to. Get by calling lists/list()
|
|
1181
1336
|
# @param [String] url the URL of a Webhook on this list
|
|
1182
1337
|
# @return [Hash] with a single entry:
|
|
1183
1338
|
# - [Bool] complete whether the call worked. reallistically this will always be true as errors will be thrown otherwise.
|
|
@@ -1187,7 +1342,7 @@ module Mailchimp
|
|
|
1187
1342
|
end
|
|
1188
1343
|
|
|
1189
1344
|
# Return the Webhooks configured for the given list
|
|
1190
|
-
# @param [String] id the list id to connect to. Get by calling lists()
|
|
1345
|
+
# @param [String] id the list id to connect to. Get by calling lists/list()
|
|
1191
1346
|
# @return [Array] of structs for each webhook
|
|
1192
1347
|
# - [String] url the URL for this Webhook
|
|
1193
1348
|
# - [Hash] actions the possible actions and whether they are enabled
|
|
@@ -1213,9 +1368,9 @@ module Mailchimp
|
|
|
1213
1368
|
# - [String] from_name optional - only lists that have a default from name matching this
|
|
1214
1369
|
# - [String] from_email optional - only lists that have a default from email matching this
|
|
1215
1370
|
# - [String] from_subject optional - only lists that have a default from email matching this
|
|
1216
|
-
# - [String] created_before optional - only show lists that were created before this date
|
|
1217
|
-
# - [String] created_after optional - only show lists that were created since this date
|
|
1218
|
-
# - [Boolean] exact optional - flag for whether to filter on exact values when filtering, or search within content for filter values - defaults to
|
|
1371
|
+
# - [String] created_before optional - only show lists that were created before this date+time - 24 hour format in <strong>GMT</strong>, eg "2013-12-30 20:30:00"
|
|
1372
|
+
# - [String] created_after optional - only show lists that were created since this date+time - 24 hour format in <strong>GMT</strong>, eg "2013-12-30 20:30:00"
|
|
1373
|
+
# - [Boolean] exact optional - flag for whether to filter on exact values when filtering, or search within content for filter values - defaults to false
|
|
1219
1374
|
# @param [Int] start optional - control paging of lists, start results at this list #, defaults to 1st page of data (page 0)
|
|
1220
1375
|
# @param [Int] limit optional - control paging of lists, number of lists to return with each call, defaults to 25 (max=100)
|
|
1221
1376
|
# @param [String] sort_field optional - "created" (the created date, default) or "web" (the display order in the web app). Invalid values will fall back on "created" - case insensitive.
|
|
@@ -1258,7 +1413,7 @@ module Mailchimp
|
|
|
1258
1413
|
# - [Array] errors structs of any errors found while loading lists - usually just from providing invalid list ids
|
|
1259
1414
|
# - [String] param the data that caused the failure
|
|
1260
1415
|
# - [Int] code the error code
|
|
1261
|
-
# - [
|
|
1416
|
+
# - [String] error the error message
|
|
1262
1417
|
def list(filters=[], start=0, limit=25, sort_field='created', sort_dir='DESC')
|
|
1263
1418
|
_params = {:filters => filters, :start => start, :limit => limit, :sort_field => sort_field, :sort_dir => sort_dir}
|
|
1264
1419
|
return @master.call 'lists/list', _params
|
|
@@ -1273,10 +1428,10 @@ module Mailchimp
|
|
|
1273
1428
|
end
|
|
1274
1429
|
|
|
1275
1430
|
# Get the content (both html and text) for a campaign either as it would appear in the campaign archive or as the raw, original content
|
|
1276
|
-
# @param [String] cid the campaign id to get content for (can be gathered using
|
|
1431
|
+
# @param [String] cid the campaign id to get content for (can be gathered using campaigns/list())
|
|
1277
1432
|
# @param [Hash] options various options to control this call
|
|
1278
1433
|
# - [String] view optional one of "archive" (default), "preview" (like our popup-preview) or "raw"
|
|
1279
|
-
# - [Hash] email optional if provided, view is "archive" or "preview", the campaign's list still exists, and the requested record is subscribed to the list. the returned content will be populated with member data populated. a struct with one of the following keys - failing to provide anything will produce an error relating to the email address.
|
|
1434
|
+
# - [Hash] email optional if provided, view is "archive" or "preview", the campaign's list still exists, and the requested record is subscribed to the list. the returned content will be populated with member data populated. a struct with one of the following keys - failing to provide anything will produce an error relating to the email address. If multiple keys are provided, the first one from the following list that we find will be used, the rest will be ignored.
|
|
1280
1435
|
# - [String] email an email address
|
|
1281
1436
|
# - [String] euid the unique id for an email address (not list related) - the email "id" returned from listMemberInfo, Webhooks, Campaigns, etc.
|
|
1282
1437
|
# - [String] leid the list email id (previously called web_id) for a list-member-info type call. this doesn't change when the email address changes
|
|
@@ -1291,7 +1446,7 @@ module Mailchimp
|
|
|
1291
1446
|
# Create a new draft campaign to send. You <strong>can not</strong> have more than 32,000 campaigns in your account.
|
|
1292
1447
|
# @param [String] type the Campaign Type to create - one of "regular", "plaintext", "absplit", "rss", "auto"
|
|
1293
1448
|
# @param [Hash] options a struct of the standard options for this campaign :
|
|
1294
|
-
# - [String] list_id the list to send this campaign to- get lists using lists()
|
|
1449
|
+
# - [String] list_id the list to send this campaign to- get lists using lists/list()
|
|
1295
1450
|
# - [String] subject the subject line for your campaign message
|
|
1296
1451
|
# - [String] from_email the From: email address for your campaign message
|
|
1297
1452
|
# - [String] from_name the From: name for your campaign message (not an email address)
|
|
@@ -1299,7 +1454,7 @@ module Mailchimp
|
|
|
1299
1454
|
# - [Int] template_id optional - use this user-created template to generate the HTML content of the campaign (takes precendence over other template options)
|
|
1300
1455
|
# - [Int] gallery_template_id optional - use a template from the public gallery to generate the HTML content of the campaign (takes precendence over base template options)
|
|
1301
1456
|
# - [Int] base_template_id optional - use this a base/start-from-scratch template to generate the HTML content of the campaign
|
|
1302
|
-
# - [Int] folder_id optional - automatically file the new campaign in the folder_id passed. Get using folders() - note that Campaigns and Autoresponders have separate folder
|
|
1457
|
+
# - [Int] folder_id optional - automatically file the new campaign in the folder_id passed. Get using folders/list() - note that Campaigns and Autoresponders have separate folder setups
|
|
1303
1458
|
# - [Hash] tracking optional - set which recipient actions will be tracked. Click tracking can not be disabled for Free accounts.
|
|
1304
1459
|
# - [Bool] opens whether to track opens, defaults to true
|
|
1305
1460
|
# - [Bool] html_clicks whether to track clicks in HTML content, defaults to true
|
|
@@ -1309,7 +1464,7 @@ module Mailchimp
|
|
|
1309
1464
|
# - [Hash] analytics optional - one or more of these keys set to the tag to use - that can be any custom text (up to 50 bytes)
|
|
1310
1465
|
# - [String] google for Google Analytics tracking
|
|
1311
1466
|
# - [String] clicktale for ClickTale tracking
|
|
1312
|
-
# - [String] gooal for
|
|
1467
|
+
# - [String] gooal for Goal tracking (the extra 'o' in the param name is not a typo)
|
|
1313
1468
|
# - [Boolean] auto_footer optional Whether or not we should auto-generate the footer for your content. Mostly useful for content from URLs or Imports
|
|
1314
1469
|
# - [Boolean] inline_css optional Whether or not css should be automatically inlined when this campaign is sent, defaults to false.
|
|
1315
1470
|
# - [Boolean] generate_text optional Whether of not to auto-generate your Text content from the HTML content. Note that this will be ignored if the Text part of the content passed is not empty, defaults to false.
|
|
@@ -1318,7 +1473,7 @@ module Mailchimp
|
|
|
1318
1473
|
# - [Boolean] fb_comments optional If true, the Facebook comments (and thus the <a href="http://kb.mailchimp.com/article/i-dont-want-an-archiave-of-my-campaign-can-i-turn-it-off/" target="_blank">archive bar</a> will be displayed. If false, Facebook comments will not be enabled (does not imply no archive bar, see previous link). Defaults to "true".
|
|
1319
1474
|
# - [Boolean] timewarp optional If set, this campaign must be scheduled 24 hours in advance of sending - default to false. Only valid for "regular" campaigns and "absplit" campaigns that split on schedule_time.
|
|
1320
1475
|
# - [Boolean] ecomm360 optional If set, our <a href="http://www.mailchimp.com/blog/ecommerce-tracking-plugin/" target="_blank">Ecommerce360 tracking</a> will be enabled for links in the campaign
|
|
1321
|
-
# - [
|
|
1476
|
+
# - [Hash] crm_tracking optional If set, a struct to enable CRM tracking for:
|
|
1322
1477
|
# - [Hash] salesforce optional Enable SalesForce push back
|
|
1323
1478
|
# - [Bool] campaign optional - if true, create a Campaign object and update it with aggregate stats
|
|
1324
1479
|
# - [Bool] notes optional - if true, attempt to update Contact notes based on email address
|
|
@@ -1334,7 +1489,7 @@ module Mailchimp
|
|
|
1334
1489
|
# - [String] url to have us pull in content from a URL. Note, this will override any other content options - for lists with Email Format options, you'll need to turn on generate_text as well
|
|
1335
1490
|
# - [String] archive to send a Base64 encoded archive file for us to import all media from. Note, this will override any other content options - for lists with Email Format options, you'll need to turn on generate_text as well
|
|
1336
1491
|
# - [String] archive_type optional - only necessary for the "archive" option. Supported formats are: zip, tar.gz, tar.bz2, tar, tgz, tbz . If not included, we will default to zip
|
|
1337
|
-
# @param [Hash] segment_opts if you wish to do Segmentation with this campaign this array should contain: see
|
|
1492
|
+
# @param [Hash] segment_opts if you wish to do Segmentation with this campaign this array should contain: see campaigns/segment-test(). It's suggested that you test your options against campaigns/segment-test().
|
|
1338
1493
|
# @param [Hash] type_opts various extra options based on the campaign type
|
|
1339
1494
|
# - [Hash] rss For RSS Campaigns this, struct should contain:
|
|
1340
1495
|
# - [String] url the URL to pull RSS content from - it will be verified and must exist
|
|
@@ -1351,7 +1506,7 @@ module Mailchimp
|
|
|
1351
1506
|
# - [Bool] 6 optional Saturday, defaults to true
|
|
1352
1507
|
# - [Bool] 7 optional Sunday, defaults to true
|
|
1353
1508
|
# - [Hash] absplit For A/B Split campaigns, this struct should contain:
|
|
1354
|
-
# - [String] split_test The values to segment based on. Currently, one of: "subject", "from_name", "schedule". NOTE, for "schedule", you will need to call
|
|
1509
|
+
# - [String] split_test The values to segment based on. Currently, one of: "subject", "from_name", "schedule". NOTE, for "schedule", you will need to call campaigns/schedule() separately!
|
|
1355
1510
|
# - [String] pick_winner How the winner will be picked, one of: "opens" (by the open_rate), "clicks" (by the click rate), "manual" (you pick manually)
|
|
1356
1511
|
# - [Int] wait_units optional the default time unit to wait before auto-selecting a winner - use "3600" for hours, "86400" for days. Defaults to 86400.
|
|
1357
1512
|
# - [Int] wait_time optional the number of units to wait before auto-selecting a winner - defaults to 1, so if not set, a winner will be selected after 1 Day.
|
|
@@ -1399,9 +1554,9 @@ module Mailchimp
|
|
|
1399
1554
|
# @param [Hash] filters a struct of filters to apply to this query - all are optional:
|
|
1400
1555
|
# - [String] campaign_id optional - return the campaign using a know campaign_id. Accepts multiples separated by commas when not using exact matching.
|
|
1401
1556
|
# - [String] parent_id optional - return the child campaigns using a known parent campaign_id. Accepts multiples separated by commas when not using exact matching.
|
|
1402
|
-
# - [String] list_id optional - the list to send this campaign to - get lists using lists(). Accepts multiples separated by commas when not using exact matching.
|
|
1403
|
-
# - [Int] folder_id optional - only show campaigns from this folder id - get folders using
|
|
1404
|
-
# - [Int] template_id optional - only show campaigns using this template id - get templates using templates(). Accepts multiples separated by commas when not using exact matching.
|
|
1557
|
+
# - [String] list_id optional - the list to send this campaign to - get lists using lists/list(). Accepts multiples separated by commas when not using exact matching.
|
|
1558
|
+
# - [Int] folder_id optional - only show campaigns from this folder id - get folders using folders/list(). Accepts multiples separated by commas when not using exact matching.
|
|
1559
|
+
# - [Int] template_id optional - only show campaigns using this template id - get templates using templates/list(). Accepts multiples separated by commas when not using exact matching.
|
|
1405
1560
|
# - [String] status optional - return campaigns of a specific status - one of "sent", "save", "paused", "schedule", "sending". Accepts multiples separated by commas when not using exact matching.
|
|
1406
1561
|
# - [String] type optional - return campaigns of a specific type - one of "regular", "plaintext", "absplit", "rss", "auto". Accepts multiples separated by commas when not using exact matching.
|
|
1407
1562
|
# - [String] from_name optional - only show campaigns that have this "From Name"
|
|
@@ -1446,22 +1601,34 @@ module Mailchimp
|
|
|
1446
1601
|
# - [Boolean] auto_footer Whether or not the auto_footer was manually turned on
|
|
1447
1602
|
# - [Boolean] timewarp Whether or not the campaign used Timewarp
|
|
1448
1603
|
# - [String] timewarp_schedule The time, in GMT, that the Timewarp campaign is being sent. For A/B Split campaigns, this is blank and is instead in their schedule_a and schedule_b in the type_opts array
|
|
1449
|
-
# - [String] parent_id the unique id of the parent campaign (currently only valid for rss children)
|
|
1604
|
+
# - [String] parent_id the unique id of the parent campaign (currently only valid for rss children). Will be blank for non-rss child campaigns or parent campaign has been deleted.
|
|
1605
|
+
# - [Boolean] is_child true if this is an RSS child campaign. Will return true even if the parent campaign has been deleted.
|
|
1606
|
+
# - [String] tests_sent tests sent
|
|
1607
|
+
# - [Int] tests_remain test sends remaining
|
|
1450
1608
|
# - [Hash] tracking the various tracking options used
|
|
1451
1609
|
# - [Boolean] html_clicks whether or not tracking for html clicks was enabled.
|
|
1452
1610
|
# - [Boolean] text_clicks whether or not tracking for text clicks was enabled.
|
|
1453
1611
|
# - [Boolean] opens whether or not opens tracking was enabled.
|
|
1454
1612
|
# - [String] segment_text a string marked-up with HTML explaining the segment used for the campaign in plain English
|
|
1455
|
-
# - [Array] segment_opts the segment used for the campaign - can be passed to campaigns/segment-test or campaigns/create
|
|
1456
|
-
# - [Hash]
|
|
1613
|
+
# - [Array] segment_opts the segment used for the campaign - can be passed to campaigns/segment-test or campaigns/create()
|
|
1614
|
+
# - [Hash] saved_segment if a saved segment was used (match+conditions returned above):
|
|
1615
|
+
# - [Int] id the saved segment id
|
|
1616
|
+
# - [String] type the saved segment type
|
|
1617
|
+
# - [String] name the saved segment name
|
|
1618
|
+
# - [Hash] type_opts the type-specific options for the campaign - can be passed to campaigns/create()
|
|
1457
1619
|
# - [Int] comments_total total number of comments left on this campaign
|
|
1458
1620
|
# - [Int] comments_unread total number of unread comments for this campaign based on the login the apikey belongs to
|
|
1459
1621
|
# - [Hash] summary if available, the basic aggregate stats returned by reports/summary
|
|
1622
|
+
# - [Hash] social_card If a social card has been attached to this campaign:
|
|
1623
|
+
# - [String] title The title of the campaign used with the card
|
|
1624
|
+
# - [String] description The description used with the card
|
|
1625
|
+
# - [String] image_url The URL of the image used with the card
|
|
1626
|
+
# - [String] enabled Whether or not the social card is enabled for this campaign.
|
|
1460
1627
|
# - [Array] errors structs of any errors found while loading lists - usually just from providing invalid list ids
|
|
1461
1628
|
# - [String] filter the filter that caused the failure
|
|
1462
1629
|
# - [String] value the filter value that caused the failure
|
|
1463
1630
|
# - [Int] code the error code
|
|
1464
|
-
# - [
|
|
1631
|
+
# - [String] error the error message
|
|
1465
1632
|
def list(filters=[], start=0, limit=25, sort_field='create_time', sort_dir='DESC')
|
|
1466
1633
|
_params = {:filters => filters, :start => start, :limit => limit, :sort_field => sort_field, :sort_dir => sort_dir}
|
|
1467
1634
|
return @master.call 'campaigns/list', _params
|
|
@@ -1498,7 +1665,7 @@ module Mailchimp
|
|
|
1498
1665
|
end
|
|
1499
1666
|
|
|
1500
1667
|
# Resume sending an AutoResponder or RSS campaign
|
|
1501
|
-
# @param [String] cid the id of the campaign to
|
|
1668
|
+
# @param [String] cid the id of the campaign to resume
|
|
1502
1669
|
# @return [Hash] with a single entry:
|
|
1503
1670
|
# - [Bool] complete whether the call worked. reallistically this will always be true as errors will be thrown otherwise.
|
|
1504
1671
|
def resume(cid)
|
|
@@ -1529,9 +1696,10 @@ module Mailchimp
|
|
|
1529
1696
|
return @master.call 'campaigns/schedule-batch', _params
|
|
1530
1697
|
end
|
|
1531
1698
|
|
|
1532
|
-
# Allows one to test their segmentation rules before creating a campaign using them
|
|
1533
|
-
# @param [String] list_id the list to test segmentation on - get lists using lists()
|
|
1534
|
-
# @param [Hash] options with 2 keys:
|
|
1699
|
+
# Allows one to test their segmentation rules before creating a campaign using them.
|
|
1700
|
+
# @param [String] list_id the list to test segmentation on - get lists using lists/list()
|
|
1701
|
+
# @param [Hash] options with 1 or 2 keys:
|
|
1702
|
+
# - [String] saved_segment_id a saved segment id from lists/segments() - this will take precendence, otherwise the match+conditions are required.
|
|
1535
1703
|
# - [String] match controls whether to use AND or OR when applying your options - expects "<strong>any</strong>" (for OR) or "<strong>all</strong>" (for AND)
|
|
1536
1704
|
# - [Array] conditions of up to 5 structs for different criteria to apply while segmenting. Each criteria row must contain 3 keys - "<strong>field</strong>", "<strong>op</strong>", and "<strong>value</strong>" - and possibly a fourth, "<strong>extra</strong>", based on these definitions:
|
|
1537
1705
|
# @return [Hash] with a single entry:
|
|
@@ -1562,7 +1730,7 @@ module Mailchimp
|
|
|
1562
1730
|
end
|
|
1563
1731
|
|
|
1564
1732
|
# Get the HTML template content sections for a campaign. Note that this <strong>will</strong> return very jagged, non-standard results based on the template a campaign is using. You only want to use this if you want to allow editing template sections in your application.
|
|
1565
|
-
# @param [String] cid the campaign id to get content for (can be gathered using campaigns())
|
|
1733
|
+
# @param [String] cid the campaign id to get content for (can be gathered using campaigns/list())
|
|
1566
1734
|
# @return [Hash] content containing all content section for the campaign - section name are dependent upon the template used and thus can't be documented
|
|
1567
1735
|
def template_content(cid)
|
|
1568
1736
|
_params = {:cid => cid}
|
|
@@ -1578,10 +1746,10 @@ module Mailchimp
|
|
|
1578
1746
|
return @master.call 'campaigns/unschedule', _params
|
|
1579
1747
|
end
|
|
1580
1748
|
|
|
1581
|
-
# Update just about any setting besides type for a campaign that has <em>not</em> been sent. See
|
|
1749
|
+
# Update just about any setting besides type for a campaign that has <em>not</em> been sent. See campaigns/create() for details. Caveats:<br/><ul class='bullets'> <li>If you set a new list_id, all segmentation options will be deleted and must be re-added.</li> <li>If you set template_id, you need to follow that up by setting it's 'content'</li> <li>If you set segment_opts, you should have tested your options against campaigns/segment-test().</li> <li>To clear/unset segment_opts, pass an empty string or array as the value. Various wrappers may require one or the other.</li> </ul>
|
|
1582
1750
|
# @param [String] cid the Campaign Id to update
|
|
1583
|
-
# @param [String] name the parameter name ( see
|
|
1584
|
-
# @param [Array] value an appropriate set of values for the parameter ( see
|
|
1751
|
+
# @param [String] name the parameter name ( see campaigns/create() ). This will be that parameter name (options, content, segment_opts) except "type_opts", which will be the name of the type - rss, auto, etc. The campaign "type" can not be changed.
|
|
1752
|
+
# @param [Array] value an appropriate set of values for the parameter ( see campaigns/create() ). For additional parameters, this is the same value passed to them.
|
|
1585
1753
|
# @return [Hash] updated campaign details and any errors
|
|
1586
1754
|
# - [Hash] data the update campaign details - will return same data as single campaign from campaigns/list()
|
|
1587
1755
|
# - [Array] errors for "options" only - structs containing:
|
|
@@ -1629,7 +1797,7 @@ module Mailchimp
|
|
|
1629
1797
|
end
|
|
1630
1798
|
|
|
1631
1799
|
# Add VIPs (previously called Golden Monkeys)
|
|
1632
|
-
# @param [String] id the list id to connect to. Get by calling lists()
|
|
1800
|
+
# @param [String] id the list id to connect to. Get by calling lists/list()
|
|
1633
1801
|
# @param [Array] emails an array of up to 50 email address structs to add, each with with one of the following keys
|
|
1634
1802
|
# - [String] email an email address - for new subscribers obviously this should be used
|
|
1635
1803
|
# - [String] euid the unique id for an email address (not list related) - the email "id" returned from listMemberInfo, Webhooks, Campaigns, etc.
|
|
@@ -1655,7 +1823,7 @@ module Mailchimp
|
|
|
1655
1823
|
end
|
|
1656
1824
|
|
|
1657
1825
|
# Remove VIPs - this does not affect list membership
|
|
1658
|
-
# @param [String] id the list id to connect to. Get by calling lists()
|
|
1826
|
+
# @param [String] id the list id to connect to. Get by calling lists/list()
|
|
1659
1827
|
# @param [Array] emails an array of up to 50 email address structs to remove, each with with one of the following keys
|
|
1660
1828
|
# - [String] email an email address - for new subscribers obviously this should be used
|
|
1661
1829
|
# - [String] euid the unique id for an email address (not list related) - the email "id" returned from listMemberInfo, Webhooks, Campaigns, etc.
|
|
@@ -1703,7 +1871,7 @@ module Mailchimp
|
|
|
1703
1871
|
end
|
|
1704
1872
|
|
|
1705
1873
|
# Get all email addresses that complained about a given campaign
|
|
1706
|
-
# @param [String] cid the campaign id to pull abuse reports for (can be gathered using campaigns())
|
|
1874
|
+
# @param [String] cid the campaign id to pull abuse reports for (can be gathered using campaigns/list())
|
|
1707
1875
|
# @param [Hash] opts various options for controlling returned data
|
|
1708
1876
|
# - [Int] start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
|
|
1709
1877
|
# - [Int] limit optional for large data sets, the number of results to return - defaults to 25, upper limit set at 100
|
|
@@ -1720,7 +1888,7 @@ module Mailchimp
|
|
|
1720
1888
|
end
|
|
1721
1889
|
|
|
1722
1890
|
# Retrieve the text presented in our app for how a campaign performed and any advice we may have for you - best suited for display in customized reports pages. Note: some messages will contain HTML - clean tags as necessary
|
|
1723
|
-
# @param [String] cid the campaign id to pull advice text for (can be gathered using campaigns())
|
|
1891
|
+
# @param [String] cid the campaign id to pull advice text for (can be gathered using campaigns/list())
|
|
1724
1892
|
# @return [Array] of structs for advice on the campaign's performance, each containing:
|
|
1725
1893
|
# - [String] msg the advice message
|
|
1726
1894
|
# - [String] type the "type" of the message. one of: negative, positive, or neutral
|
|
@@ -1730,14 +1898,14 @@ module Mailchimp
|
|
|
1730
1898
|
end
|
|
1731
1899
|
|
|
1732
1900
|
# Retrieve the most recent full bounce message for a specific email address on the given campaign. Messages over 30 days old are subject to being removed
|
|
1733
|
-
# @param [String] cid the campaign id to pull bounces for (can be gathered using campaigns())
|
|
1734
|
-
# @param [Hash] email a struct with one of the following keys - failing to provide anything will produce an error relating to the email address.
|
|
1901
|
+
# @param [String] cid the campaign id to pull bounces for (can be gathered using campaigns/list())
|
|
1902
|
+
# @param [Hash] email a struct with one of the following keys - failing to provide anything will produce an error relating to the email address. If multiple keys are provided, the first one from the following list that we find will be used, the rest will be ignored.
|
|
1735
1903
|
# - [String] email an email address - this is recommended for this method
|
|
1736
1904
|
# - [String] euid the unique id for an email address (not list related) - the email "id" returned from listMemberInfo, Webhooks, Campaigns, etc.
|
|
1737
1905
|
# - [String] leid the list email id (previously called web_id) for a list-member-info type call. this doesn't change when the email address changes
|
|
1738
1906
|
# @return [Hash] the full bounce message for this email+campaign along with some extra data.
|
|
1739
1907
|
# - [String] date date the bounce was received and processed
|
|
1740
|
-
# - [Hash] member the member record as returned by lists/member-info
|
|
1908
|
+
# - [Hash] member the member record as returned by lists/member-info()
|
|
1741
1909
|
# - [String] message the entire bounce message received
|
|
1742
1910
|
def bounce_message(cid, email)
|
|
1743
1911
|
_params = {:cid => cid, :email => email}
|
|
@@ -1745,7 +1913,7 @@ module Mailchimp
|
|
|
1745
1913
|
end
|
|
1746
1914
|
|
|
1747
1915
|
# Retrieve the full bounce messages for the given campaign. Note that this can return very large amounts of data depending on how large the campaign was and how much cruft the bounce provider returned. Also, messages over 30 days old are subject to being removed
|
|
1748
|
-
# @param [String] cid the campaign id to pull bounces for (can be gathered using campaigns())
|
|
1916
|
+
# @param [String] cid the campaign id to pull bounces for (can be gathered using campaigns/list())
|
|
1749
1917
|
# @param [Hash] opts various options for controlling returned data
|
|
1750
1918
|
# - [Int] start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
|
|
1751
1919
|
# - [Int] limit optional for large data sets, the number of results to return - defaults to 25, upper limit set at 100
|
|
@@ -1754,7 +1922,7 @@ module Mailchimp
|
|
|
1754
1922
|
# - [Int] total that total number of bounce messages for the campaign
|
|
1755
1923
|
# - [Array] data structs containing the data for this page
|
|
1756
1924
|
# - [String] date date the bounce was received and processed
|
|
1757
|
-
# - [Hash] member the member record as returned by lists/member-info
|
|
1925
|
+
# - [Hash] member the member record as returned by lists/member-info()
|
|
1758
1926
|
# - [String] message the entire bounce message received
|
|
1759
1927
|
def bounce_messages(cid, opts=[])
|
|
1760
1928
|
_params = {:cid => cid, :opts => opts}
|
|
@@ -1762,7 +1930,7 @@ module Mailchimp
|
|
|
1762
1930
|
end
|
|
1763
1931
|
|
|
1764
1932
|
# Return the list of email addresses that clicked on a given url, and how many times they clicked
|
|
1765
|
-
# @param [String] cid the campaign id to get click stats for (can be gathered using campaigns())
|
|
1933
|
+
# @param [String] cid the campaign id to get click stats for (can be gathered using campaigns/list())
|
|
1766
1934
|
# @param [Int] tid the "tid" for the URL from reports/clicks
|
|
1767
1935
|
# @param [Hash] opts various options for controlling returned data
|
|
1768
1936
|
# - [Int] start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
|
|
@@ -1772,7 +1940,7 @@ module Mailchimp
|
|
|
1772
1940
|
# @return [Hash] containing the total records matched and the specific records for this page
|
|
1773
1941
|
# - [Int] total the total number of records matched
|
|
1774
1942
|
# - [Array] data structs for each email addresses that click the requested url
|
|
1775
|
-
# - [Hash] member the member record as returned by lists/member-info
|
|
1943
|
+
# - [Hash] member the member record as returned by lists/member-info()
|
|
1776
1944
|
# - [Int] clicks Total number of times the URL was clicked by this email address
|
|
1777
1945
|
def click_detail(cid, tid, opts=[])
|
|
1778
1946
|
_params = {:cid => cid, :tid => tid, :opts => opts}
|
|
@@ -1780,7 +1948,7 @@ module Mailchimp
|
|
|
1780
1948
|
end
|
|
1781
1949
|
|
|
1782
1950
|
# The urls tracked and their click counts for a given campaign.
|
|
1783
|
-
# @param [String] cid the campaign id to pull stats for (can be gathered using campaigns())
|
|
1951
|
+
# @param [String] cid the campaign id to pull stats for (can be gathered using campaigns/list())
|
|
1784
1952
|
# @return [Hash] including:
|
|
1785
1953
|
# - [Array] total structs for each url tracked for the full campaign
|
|
1786
1954
|
# - [String] url the url being tracked - urls are tracked individually, so duplicates can exist with vastly different stats
|
|
@@ -1808,8 +1976,8 @@ module Mailchimp
|
|
|
1808
1976
|
return @master.call 'reports/clicks', _params
|
|
1809
1977
|
end
|
|
1810
1978
|
|
|
1811
|
-
# Retrieve the Ecommerce Orders tracked by
|
|
1812
|
-
# @param [String] cid the campaign id to pull orders for for (can be gathered using campaigns())
|
|
1979
|
+
# Retrieve the Ecommerce Orders tracked by ecomm/order-add()
|
|
1980
|
+
# @param [String] cid the campaign id to pull orders for for (can be gathered using campaigns/list())
|
|
1813
1981
|
# @param [Hash] opts various options for controlling returned data
|
|
1814
1982
|
# - [Int] start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
|
|
1815
1983
|
# - [Int] limit optional for large data sets, the number of results to return - defaults to 25, upper limit set at 100
|
|
@@ -1817,30 +1985,30 @@ module Mailchimp
|
|
|
1817
1985
|
# @return [Hash] the total matching orders and the specific orders for the requested page
|
|
1818
1986
|
# - [Int] total the total matching orders
|
|
1819
1987
|
# - [Array] data structs for the actual data for each order being returned
|
|
1820
|
-
#
|
|
1821
|
-
#
|
|
1822
|
-
#
|
|
1823
|
-
#
|
|
1824
|
-
#
|
|
1825
|
-
#
|
|
1826
|
-
#
|
|
1827
|
-
#
|
|
1828
|
-
#
|
|
1829
|
-
#
|
|
1830
|
-
#
|
|
1831
|
-
#
|
|
1832
|
-
#
|
|
1833
|
-
#
|
|
1834
|
-
#
|
|
1835
|
-
#
|
|
1836
|
-
#
|
|
1988
|
+
# - [String] store_id the store id generated by the plugin used to uniquely identify a store
|
|
1989
|
+
# - [String] store_name the store name collected by the plugin - often the domain name
|
|
1990
|
+
# - [String] order_id the internal order id the store tracked this order by
|
|
1991
|
+
# - [Hash] member the member record as returned by lists/member-info() that received this campaign and is associated with this order
|
|
1992
|
+
# - [Double] order_total the order total
|
|
1993
|
+
# - [Double] tax_total the total tax for the order (if collected)
|
|
1994
|
+
# - [Double] ship_total the shipping total for the order (if collected)
|
|
1995
|
+
# - [String] order_date the date the order was tracked - from the store if possible, otherwise the GMT time we received it
|
|
1996
|
+
# - [Array] lines structs containing details of the order:
|
|
1997
|
+
# - [Int] line_num the line number assigned to this line
|
|
1998
|
+
# - [Int] product_id the product id assigned to this item
|
|
1999
|
+
# - [String] product_name the product name
|
|
2000
|
+
# - [String] product_sku the sku for the product
|
|
2001
|
+
# - [Int] product_category_id the id for the product category
|
|
2002
|
+
# - [String] product_category_name the product category name
|
|
2003
|
+
# - [Double] qty optional the quantity of the item ordered - defaults to 1
|
|
2004
|
+
# - [Double] cost optional the cost of a single item (ie, not the extended cost of the line) - defaults to 0
|
|
1837
2005
|
def ecomm_orders(cid, opts=[])
|
|
1838
2006
|
_params = {:cid => cid, :opts => opts}
|
|
1839
2007
|
return @master.call 'reports/ecomm-orders', _params
|
|
1840
2008
|
end
|
|
1841
2009
|
|
|
1842
2010
|
# Retrieve the eepurl stats from the web/Twitter mentions for this campaign
|
|
1843
|
-
# @param [String] cid the campaign id to pull stats for (can be gathered using campaigns())
|
|
2011
|
+
# @param [String] cid the campaign id to pull stats for (can be gathered using campaigns/list())
|
|
1844
2012
|
# @return [Hash] containing tweets, retweets, clicks, and referrer related to using the campaign's eepurl
|
|
1845
2013
|
# - [Hash] twitter various Twitter related stats
|
|
1846
2014
|
# - [Int] tweets Total number of tweets seen
|
|
@@ -1873,7 +2041,7 @@ module Mailchimp
|
|
|
1873
2041
|
end
|
|
1874
2042
|
|
|
1875
2043
|
# Given a campaign and email address, return the entire click and open history with timestamps, ordered by time. If you need to dump the full activity for a campaign and/or get incremental results, you should use the <a href="http://apidocs.mailchimp.com/export/1.0/campaignsubscriberactivity.func.php" targret="_new">campaignSubscriberActivity Export API method</a>, <strong>not</strong> this, especially for large campaigns.
|
|
1876
|
-
# @param [String] cid the campaign id to get stats for (can be gathered using campaigns())
|
|
2044
|
+
# @param [String] cid the campaign id to get stats for (can be gathered using campaigns/list())
|
|
1877
2045
|
# @param [Array] emails an array of up to 50 email address struct to retrieve activity information for
|
|
1878
2046
|
# - [String] email an email address
|
|
1879
2047
|
# - [String] euid the unique id for an email address (not list related) - the email "id" returned from listMemberInfo, Webhooks, Campaigns, etc.
|
|
@@ -1892,7 +2060,7 @@ module Mailchimp
|
|
|
1892
2060
|
# - [String] email the email address added
|
|
1893
2061
|
# - [String] euid the email unique id
|
|
1894
2062
|
# - [String] leid the list member's truly unique id
|
|
1895
|
-
# - [Hash] member the member record as returned by lists/member-info
|
|
2063
|
+
# - [Hash] member the member record as returned by lists/member-info()
|
|
1896
2064
|
# - [Array] activity an array of structs containing the activity, including:
|
|
1897
2065
|
# - [String] action The action name - either open or click
|
|
1898
2066
|
# - [String] timestamp The date/time of the action (GMT)
|
|
@@ -1904,38 +2072,38 @@ module Mailchimp
|
|
|
1904
2072
|
end
|
|
1905
2073
|
|
|
1906
2074
|
# Retrieve the list of email addresses that did not open a given campaign
|
|
1907
|
-
# @param [String] cid the campaign id to get no opens for (can be gathered using campaigns())
|
|
2075
|
+
# @param [String] cid the campaign id to get no opens for (can be gathered using campaigns/list())
|
|
1908
2076
|
# @param [Hash] opts various options for controlling returned data
|
|
1909
2077
|
# - [Int] start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
|
|
1910
2078
|
# - [Int] limit optional for large data sets, the number of results to return - defaults to 25, upper limit set at 100
|
|
1911
2079
|
# @return [Hash] a total of all matching emails and the specific emails for this page
|
|
1912
2080
|
# - [Int] total the total number of members who didn't open the campaign
|
|
1913
|
-
# - [Array] data structs for each campaign member matching as returned by lists/member-info
|
|
2081
|
+
# - [Array] data structs for each campaign member matching as returned by lists/member-info()
|
|
1914
2082
|
def not_opened(cid, opts=[])
|
|
1915
2083
|
_params = {:cid => cid, :opts => opts}
|
|
1916
2084
|
return @master.call 'reports/not-opened', _params
|
|
1917
2085
|
end
|
|
1918
2086
|
|
|
1919
2087
|
# Retrieve the list of email addresses that opened a given campaign with how many times they opened
|
|
1920
|
-
# @param [String] cid the campaign id to get opens for (can be gathered using campaigns())
|
|
2088
|
+
# @param [String] cid the campaign id to get opens for (can be gathered using campaigns/list())
|
|
1921
2089
|
# @param [Hash] opts various options for controlling returned data
|
|
1922
2090
|
# - [Int] start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
|
|
1923
2091
|
# - [Int] limit optional for large data sets, the number of results to return - defaults to 25, upper limit set at 100
|
|
1924
2092
|
# - [String] sort_field optional the data to sort by - "opened" (order opens occurred, default) or "opens" (total number of opens). Invalid fields will fall back on the default.
|
|
1925
2093
|
# - [String] sort_dir optional the direct - ASC or DESC. defaults to ASC (case insensitive)
|
|
1926
|
-
# @return [
|
|
2094
|
+
# @return [Hash] containing the total records matched and the specific records for this page
|
|
1927
2095
|
# - [Int] total the total number of records matched
|
|
1928
2096
|
# - [Array] data structs for the actual opens data, including:
|
|
1929
|
-
# - [Hash] member the member record as returned by lists/member-info
|
|
2097
|
+
# - [Hash] member the member record as returned by lists/member-info()
|
|
1930
2098
|
# - [Int] opens Total number of times the campaign was opened by this email address
|
|
1931
2099
|
def opened(cid, opts=[])
|
|
1932
2100
|
_params = {:cid => cid, :opts => opts}
|
|
1933
2101
|
return @master.call 'reports/opened', _params
|
|
1934
2102
|
end
|
|
1935
2103
|
|
|
1936
|
-
# Get the top 5 performing email domains for this campaign. Users wanting more than 5 should use campaign
|
|
1937
|
-
# @param [String] cid the campaign id to pull email domain performance for (can be gathered using campaigns())
|
|
1938
|
-
# @return [Array] domains
|
|
2104
|
+
# Get the top 5 performing email domains for this campaign. Users wanting more than 5 should use campaign reports/member-activity() or campaignEmailStatsAIMAll() and generate any additional stats they require.
|
|
2105
|
+
# @param [String] cid the campaign id to pull email domain performance for (can be gathered using campaigns/list())
|
|
2106
|
+
# @return [Array] domains structs for each email domains and their associated stats
|
|
1939
2107
|
# - [String] domain Domain name or special "Other" to roll-up stats past 5 domains
|
|
1940
2108
|
# - [Int] total_sent Total Email across all domains - this will be the same in every row
|
|
1941
2109
|
# - [Int] emails Number of emails sent to this domain
|
|
@@ -1955,12 +2123,12 @@ module Mailchimp
|
|
|
1955
2123
|
end
|
|
1956
2124
|
|
|
1957
2125
|
# Retrieve the countries/regions and number of opens tracked for each. Email address are not returned.
|
|
1958
|
-
# @param [String] cid the campaign id to pull bounces for (can be gathered using campaigns())
|
|
2126
|
+
# @param [String] cid the campaign id to pull bounces for (can be gathered using campaigns/list())
|
|
1959
2127
|
# @return [Array] an array of country structs where opens occurred
|
|
1960
2128
|
# - [String] code The ISO3166 2 digit country code
|
|
1961
2129
|
# - [String] name A version of the country name, if we have it
|
|
1962
2130
|
# - [Int] opens The total number of opens that occurred in the country
|
|
1963
|
-
# - [Array] regions
|
|
2131
|
+
# - [Array] regions structs of data for each sub-region in the country
|
|
1964
2132
|
# - [String] code An internal code for the region. When this is blank, it indicates we know the country, but not the region
|
|
1965
2133
|
# - [String] name The name of the region, if we have one. For blank "code" values, this will be "Rest of Country"
|
|
1966
2134
|
# - [Int] opens The total number of opens that occurred in the country
|
|
@@ -1970,7 +2138,7 @@ module Mailchimp
|
|
|
1970
2138
|
end
|
|
1971
2139
|
|
|
1972
2140
|
# Retrieve the Google Analytics data we've collected for this campaign. Note, requires Google Analytics Add-on to be installed and configured.
|
|
1973
|
-
# @param [String] cid the campaign id to pull bounces for (can be gathered using campaigns())
|
|
2141
|
+
# @param [String] cid the campaign id to pull bounces for (can be gathered using campaigns/list())
|
|
1974
2142
|
# @return [Array] of structs for analytics we've collected for the passed campaign.
|
|
1975
2143
|
# - [Int] visits number of visits
|
|
1976
2144
|
# - [Int] pages number of page views
|
|
@@ -1991,7 +2159,7 @@ module Mailchimp
|
|
|
1991
2159
|
end
|
|
1992
2160
|
|
|
1993
2161
|
# Get email addresses the campaign was sent to
|
|
1994
|
-
# @param [String] cid the campaign id to pull members for (can be gathered using campaigns())
|
|
2162
|
+
# @param [String] cid the campaign id to pull members for (can be gathered using campaigns/list())
|
|
1995
2163
|
# @param [Hash] opts various options for controlling returned data
|
|
1996
2164
|
# - [String] status optional the status to pull - one of 'sent', 'hard' (bounce), or 'soft' (bounce). By default, all records are returned
|
|
1997
2165
|
# - [Int] start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
|
|
@@ -1999,7 +2167,7 @@ module Mailchimp
|
|
|
1999
2167
|
# @return [Hash] a total of all matching emails and the specific emails for this page
|
|
2000
2168
|
# - [Int] total the total number of members for the campaign and status
|
|
2001
2169
|
# - [Array] data structs for each campaign member matching
|
|
2002
|
-
# - [Hash] member the member record as returned by lists/member-info
|
|
2170
|
+
# - [Hash] member the member record as returned by lists/member-info()
|
|
2003
2171
|
# - [String] status the status of the send - one of 'sent', 'hard', 'soft'
|
|
2004
2172
|
# - [String] absplit_group if this was an absplit campaign, one of 'a','b', or 'winner'
|
|
2005
2173
|
# - [String] tz_group if this was an timewarp campaign the timezone GMT offset the member was included in
|
|
@@ -2009,7 +2177,7 @@ module Mailchimp
|
|
|
2009
2177
|
end
|
|
2010
2178
|
|
|
2011
2179
|
# Get the URL to a customized <a href="http://eepurl.com/gKmL" target="_blank">VIP Report</a> for the specified campaign and optionally send an email to someone with links to it. Note subsequent calls will overwrite anything already set for the same campign (eg, the password)
|
|
2012
|
-
# @param [String] cid the campaign id to share a report for (can be gathered using campaigns())
|
|
2180
|
+
# @param [String] cid the campaign id to share a report for (can be gathered using campaigns/list())
|
|
2013
2181
|
# @param [Array] opts optional various parameters which can be used to configure the shared report
|
|
2014
2182
|
# - [String] to_email optional - optional, comma delimited list of email addresses to share the report with - no value means an email will not be sent
|
|
2015
2183
|
# - [Int] theme_id optional - either a global or a user-specific theme id. Currently this needs to be pulled out of either the Share Report or Cobranding web views by grabbing the "theme" attribute from the list presented.
|
|
@@ -2025,7 +2193,7 @@ module Mailchimp
|
|
|
2025
2193
|
end
|
|
2026
2194
|
|
|
2027
2195
|
# Retrieve relevant aggregate campaign statistics (opens, bounces, clicks, etc.)
|
|
2028
|
-
# @param [String] cid the campaign id to pull stats for (can be gathered using campaigns())
|
|
2196
|
+
# @param [String] cid the campaign id to pull stats for (can be gathered using campaigns/list())
|
|
2029
2197
|
# @return [Hash] the statistics for this campaign
|
|
2030
2198
|
# - [Int] syntax_errors Number of email addresses in campaign that had syntactical errors.
|
|
2031
2199
|
# - [Int] hard_bounces Number of email addresses in campaign that hard bounced.
|
|
@@ -2045,6 +2213,14 @@ module Mailchimp
|
|
|
2045
2213
|
# - [Int] unique_likes total number of unique likes (Facebook)
|
|
2046
2214
|
# - [Int] recipient_likes total number of recipients who liked (Facebook) the campaign
|
|
2047
2215
|
# - [Int] facebook_likes total number of likes (Facebook) that came from Facebook
|
|
2216
|
+
# - [Hash] industry Various rates/percentages for the account's selected industry - empty otherwise. These will vary across calls, do not use them for anything important.
|
|
2217
|
+
# - [String] type the selected industry
|
|
2218
|
+
# - [Float] open_rate industry open rate
|
|
2219
|
+
# - [Float] click_rate industry click rate
|
|
2220
|
+
# - [Float] bounce_rate industry bounce rate
|
|
2221
|
+
# - [Float] unopen_rate industry unopen rate
|
|
2222
|
+
# - [Float] unsub_rate industry unsub rate
|
|
2223
|
+
# - [Float] abuse_rate industry abuse rate
|
|
2048
2224
|
# - [Hash] absplit If this was an absplit campaign, stats for the A and B groups will be returned - otherwise this is empty
|
|
2049
2225
|
# - [Int] bounces_a bounces for the A group
|
|
2050
2226
|
# - [Int] bounces_b bounces for the B group
|
|
@@ -2070,7 +2246,7 @@ module Mailchimp
|
|
|
2070
2246
|
# - [Int] unique_opens the unique opens for this timezone
|
|
2071
2247
|
# - [Int] clicks the total clicks for this timezone
|
|
2072
2248
|
# - [String] last_click the date/time of the last click for this timezone
|
|
2073
|
-
# - [Int]
|
|
2249
|
+
# - [Int] unique_clicks the unique clicks for this timezone
|
|
2074
2250
|
# - [Int] bounces the total bounces for this timezone
|
|
2075
2251
|
# - [Int] total the total number of members sent to in this timezone
|
|
2076
2252
|
# - [Int] sent the total number of members delivered to in this timezone
|
|
@@ -2085,14 +2261,14 @@ module Mailchimp
|
|
|
2085
2261
|
end
|
|
2086
2262
|
|
|
2087
2263
|
# Get all unsubscribed email addresses for a given campaign
|
|
2088
|
-
# @param [String] cid the campaign id to pull bounces for (can be gathered using campaigns())
|
|
2264
|
+
# @param [String] cid the campaign id to pull bounces for (can be gathered using campaigns/list())
|
|
2089
2265
|
# @param [Hash] opts various options for controlling returned data
|
|
2090
2266
|
# - [Int] start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
|
|
2091
2267
|
# - [Int] limit optional for large data sets, the number of results to return - defaults to 25, upper limit set at 100
|
|
2092
2268
|
# @return [Hash] a total of all unsubscribed emails and the specific members for this page
|
|
2093
2269
|
# - [Int] total the total number of unsubscribes for the campaign
|
|
2094
2270
|
# - [Array] data structs for the email addresses that unsubscribed
|
|
2095
|
-
# - [String] member the member that unsubscribed as returned by lists/member-info
|
|
2271
|
+
# - [String] member the member that unsubscribed as returned by lists/member-info()
|
|
2096
2272
|
# - [String] reason the reason collected for the unsubscribe. If populated, one of 'NORMAL','NOSIGNUP','INAPPROPRIATE','SPAM','OTHER'
|
|
2097
2273
|
# - [String] reason_text if the reason is OTHER, the text entered.
|
|
2098
2274
|
def unsubscribes(cid, opts=[])
|
|
@@ -2116,9 +2292,11 @@ module Mailchimp
|
|
|
2116
2292
|
# - [String] sort_by optional field to sort by - one of size, time, name - defaults to time
|
|
2117
2293
|
# - [String] sort_dir optional field to sort by - one of asc, desc - defaults to desc
|
|
2118
2294
|
# - [String] search_term optional a term to search for in names
|
|
2295
|
+
# - [Int] folder_id optional to return files that are in a specific folder. id returned by the list-folders call
|
|
2119
2296
|
# @return [Hash] the matching gallery items
|
|
2120
2297
|
# - [Int] total the total matching items
|
|
2121
2298
|
# - [Array] data structs for each item included in the set, including:
|
|
2299
|
+
# - [Int] id the id of the file
|
|
2122
2300
|
# - [String] name the file name
|
|
2123
2301
|
# - [String] time the creation date for the item
|
|
2124
2302
|
# - [Int] size the file size in bytes
|
|
@@ -2129,6 +2307,107 @@ module Mailchimp
|
|
|
2129
2307
|
return @master.call 'gallery/list', _params
|
|
2130
2308
|
end
|
|
2131
2309
|
|
|
2310
|
+
# Return a list of the folders available to the file gallery
|
|
2311
|
+
# @param [Hash] opts various options for controlling returned data
|
|
2312
|
+
# - [Int] start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
|
|
2313
|
+
# - [Int] limit optional for large data sets, the number of results to return - defaults to 25, upper limit set at 100
|
|
2314
|
+
# - [String] search_term optional a term to search for in names
|
|
2315
|
+
# @return [Hash] the matching gallery folders
|
|
2316
|
+
# - [Int] total the total matching folders
|
|
2317
|
+
# - [Array] data structs for each folder included in the set, including:
|
|
2318
|
+
# - [Int] id the id of the folder
|
|
2319
|
+
# - [String] name the file name
|
|
2320
|
+
# - [Int] file_count the number of files in the folder
|
|
2321
|
+
def list_folders(opts=[])
|
|
2322
|
+
_params = {:opts => opts}
|
|
2323
|
+
return @master.call 'gallery/list-folders', _params
|
|
2324
|
+
end
|
|
2325
|
+
|
|
2326
|
+
# Adds a folder to the file gallery
|
|
2327
|
+
# @param [String] name the name of the folder to add (255 character max)
|
|
2328
|
+
# @return [Hash] the new data for the created folder
|
|
2329
|
+
# - [Int] data.id the id of the new folder
|
|
2330
|
+
def add_folder(name)
|
|
2331
|
+
_params = {:name => name}
|
|
2332
|
+
return @master.call 'gallery/add-folder', _params
|
|
2333
|
+
end
|
|
2334
|
+
|
|
2335
|
+
# Remove a folder
|
|
2336
|
+
# @param [Int] folder_id the id of the folder to remove, as returned by the listFolders call
|
|
2337
|
+
# @return [Boolean] true/false for success/failure
|
|
2338
|
+
def remove_folder(folder_id)
|
|
2339
|
+
_params = {:folder_id => folder_id}
|
|
2340
|
+
return @master.call 'gallery/remove-folder', _params
|
|
2341
|
+
end
|
|
2342
|
+
|
|
2343
|
+
# Add a file to a folder
|
|
2344
|
+
# @param [Int] file_id the id of the file you want to add to a folder, as returned by the list call
|
|
2345
|
+
# @param [Int] folder_id the id of the folder to add the file to, as returned by the listFolders call
|
|
2346
|
+
# @return [Boolean] true/false for success/failure
|
|
2347
|
+
def add_file_to_folder(file_id, folder_id)
|
|
2348
|
+
_params = {:file_id => file_id, :folder_id => folder_id}
|
|
2349
|
+
return @master.call 'gallery/add-file-to-folder', _params
|
|
2350
|
+
end
|
|
2351
|
+
|
|
2352
|
+
# Remove a file from a folder
|
|
2353
|
+
# @param [Int] file_id the id of the file you want to remove from the folder, as returned by the list call
|
|
2354
|
+
# @param [Int] folder_id the id of the folder to remove the file from, as returned by the listFolders call
|
|
2355
|
+
# @return [Boolean] true/false for success/failure
|
|
2356
|
+
def remove_file_from_folder(file_id, folder_id)
|
|
2357
|
+
_params = {:file_id => file_id, :folder_id => folder_id}
|
|
2358
|
+
return @master.call 'gallery/remove-file-from-folder', _params
|
|
2359
|
+
end
|
|
2360
|
+
|
|
2361
|
+
# Remove all files from a folder (Note that the files are not deleted, they are only removed from the folder)
|
|
2362
|
+
# @param [Int] folder_id the id of the folder to remove the file from, as returned by the listFolders call
|
|
2363
|
+
# @return [Boolean] true/false for success/failure
|
|
2364
|
+
def remove_all_files_from_folder(folder_id)
|
|
2365
|
+
_params = {:folder_id => folder_id}
|
|
2366
|
+
return @master.call 'gallery/remove-all-files-from-folder', _params
|
|
2367
|
+
end
|
|
2368
|
+
|
|
2369
|
+
end
|
|
2370
|
+
class Goal
|
|
2371
|
+
attr_accessor :master
|
|
2372
|
+
|
|
2373
|
+
def initialize(master)
|
|
2374
|
+
@master = master
|
|
2375
|
+
end
|
|
2376
|
+
|
|
2377
|
+
# Retrieve goal event data for a particular list member. Note: only unique events are returned. If a user triggers a particular event multiple times, you will still only receive one entry for that event.
|
|
2378
|
+
# @param [String] list_id the list id to connect to. Get by calling lists/list()
|
|
2379
|
+
# @param [Hash] email a struct with one of the following keys - failing to provide anything will produce an error relating to the email address. If multiple keys are provided, the first one from the following list that we find will be used, the rest will be ignored.
|
|
2380
|
+
# - [String] email an email address
|
|
2381
|
+
# - [String] euid the unique id for an email address (not list related) - the email "id" returned from listMemberInfo, Webhooks, Campaigns, etc.
|
|
2382
|
+
# - [String] leid the list email id (previously called web_id) for a list-member-info type call. this doesn't change when the email address changes
|
|
2383
|
+
# @param [Int] start optional - control paging of lists, start results at this list #, defaults to 1st page of data (page 0)
|
|
2384
|
+
# @param [Int] limit optional - control paging of lists, number of lists to return with each call, defaults to 25 (max=100)
|
|
2385
|
+
# @return [Hash] Event data and metadata
|
|
2386
|
+
# - [Array] data An array of goal data structs for the specified list member in the following format
|
|
2387
|
+
# - [String] event The URL or name of the event that was triggered
|
|
2388
|
+
# - [String] last_visited_at A timestamp in the format 'YYYY-MM-DD HH:MM:SS' that represents the last time this event was seen.
|
|
2389
|
+
# - [Int] total The total number of events that match your criteria.
|
|
2390
|
+
def events(list_id, email, start=0, limit=25)
|
|
2391
|
+
_params = {:list_id => list_id, :email => email, :start => start, :limit => limit}
|
|
2392
|
+
return @master.call 'goal/events', _params
|
|
2393
|
+
end
|
|
2394
|
+
|
|
2395
|
+
# This allows programmatically trigger goal event collection without the use of front-end code.
|
|
2396
|
+
# @param [String] list_id the list id to connect to. Get by calling lists/list()
|
|
2397
|
+
# @param [Hash] email a struct with one of the following keys - failing to provide anything will produce an error relating to the email address. If multiple keys are provided, the first one from the following list that we find will be used, the rest will be ignored.
|
|
2398
|
+
# - [String] email an email address
|
|
2399
|
+
# - [String] euid the unique id for an email address (not list related) - the email "id" returned from listMemberInfo, Webhooks, Campaigns, etc.
|
|
2400
|
+
# - [String] leid the list email id (previously called web_id) for a list-member-info type call. this doesn't change when the email address changes
|
|
2401
|
+
# @param [String] campaign_id the campaign id to get content for (can be gathered using campaigns/list())
|
|
2402
|
+
# @param [String] event The name of the event or the URL visited
|
|
2403
|
+
# @return [Hash] Event data for the submitted event
|
|
2404
|
+
# - [String] event The URL or name of the event that was triggered
|
|
2405
|
+
# - [String] last_visited_at A timestamp in the format 'YYYY-MM-DD HH:MM:SS' that represents the last time this event was seen.
|
|
2406
|
+
def record_event(list_id, email, campaign_id, event)
|
|
2407
|
+
_params = {:list_id => list_id, :email => email, :campaign_id => campaign_id, :event => event}
|
|
2408
|
+
return @master.call 'goal/record-event', _params
|
|
2409
|
+
end
|
|
2410
|
+
|
|
2132
2411
|
end
|
|
2133
2412
|
end
|
|
2134
2413
|
|