mailchimp-api 2.0.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (4) hide show
  1. data/lib/mailchimp.rb +202 -0
  2. data/lib/mailchimp/api.rb +2128 -0
  3. data/lib/mailchimp/errors.rb +179 -0
  4. metadata +98 -0
data/lib/mailchimp.rb ADDED
@@ -0,0 +1,202 @@
1
+ require 'rubygems'
2
+ require 'excon'
3
+ require 'json'
4
+
5
+ require 'mailchimp/errors'
6
+ require 'mailchimp/api'
7
+
8
+ module Mailchimp
9
+ class API
10
+
11
+ attr_accessor :host, :path, :apikey, :debug, :session
12
+
13
+ def initialize(apikey=nil, debug=false)
14
+ @host = 'https://api.mailchimp.com'
15
+ @path = '/2.0/'
16
+ @dc = 'us1'
17
+ @apikey = apikey
18
+ if @apikey.split('-').length == 2
19
+ @host = "https://#{@apikey.split('-')[1]}.api.mailchimp.com"
20
+ end
21
+
22
+ @session = Excon.new @host
23
+ @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
+ end
36
+
37
+ def call(url, params={})
38
+ params[:apikey] = @apikey
39
+ params = JSON.generate(params)
40
+ r = @session.post(:path => "#{@path}#{url}.json", :headers => {'Content-Type' => 'application/json'}, :body => params)
41
+
42
+ cast_error(r.body) if r.status != 200
43
+ return JSON.parse(r.body)
44
+ end
45
+
46
+ def read_configs()
47
+ [File.expand_path('~/.mailchimp.key'), '/etc/mailchimp.key'].delete_if{ |p| not File.exist? p}.each do |path|
48
+ f = File.new path
49
+ apikey = f.read.strip
50
+ f.close
51
+ return apikey if apikey != ''
52
+ end
53
+
54
+ return nil
55
+ end
56
+
57
+ def cast_error(body)
58
+
59
+ error_map = {
60
+ 'ValidationError' => ValidationError,
61
+ 'ServerError_MethodUnknown' => ServerMethodUnknownError,
62
+ 'ServerError_InvalidParameters' => ServerInvalidParametersError,
63
+ 'Unknown_Exception' => UnknownExceptionError,
64
+ 'Request_TimedOut' => RequestTimedOutError,
65
+ 'Zend_Uri_Exception' => ZendUriExceptionError,
66
+ 'PDOException' => PDOExceptionError,
67
+ 'Avesta_Db_Exception' => AvestaDbExceptionError,
68
+ 'XML_RPC2_Exception' => XMLRPC2ExceptionError,
69
+ 'XML_RPC2_FaultException' => XMLRPC2FaultExceptionError,
70
+ 'Too_Many_Connections' => TooManyConnectionsError,
71
+ 'Parse_Exception' => ParseExceptionError,
72
+ 'User_Unknown' => UserUnknownError,
73
+ 'User_Disabled' => UserDisabledError,
74
+ 'User_DoesNotExist' => UserDoesNotExistError,
75
+ 'User_NotApproved' => UserNotApprovedError,
76
+ 'Invalid_ApiKey' => InvalidApiKeyError,
77
+ 'User_UnderMaintenance' => UserUnderMaintenanceError,
78
+ 'Invalid_AppKey' => InvalidAppKeyError,
79
+ 'Invalid_IP' => InvalidIPError,
80
+ 'User_DoesExist' => UserDoesExistError,
81
+ 'User_InvalidRole' => UserInvalidRoleError,
82
+ 'User_InvalidAction' => UserInvalidActionError,
83
+ 'User_MissingEmail' => UserMissingEmailError,
84
+ 'User_CannotSendCampaign' => UserCannotSendCampaignError,
85
+ 'User_MissingModuleOutbox' => UserMissingModuleOutboxError,
86
+ 'User_ModuleAlreadyPurchased' => UserModuleAlreadyPurchasedError,
87
+ 'User_ModuleNotPurchased' => UserModuleNotPurchasedError,
88
+ 'User_NotEnoughCredit' => UserNotEnoughCreditError,
89
+ 'MC_InvalidPayment' => MCInvalidPaymentError,
90
+ 'List_DoesNotExist' => ListDoesNotExistError,
91
+ 'List_InvalidInterestFieldType' => ListInvalidInterestFieldTypeError,
92
+ 'List_InvalidOption' => ListInvalidOptionError,
93
+ 'List_InvalidUnsubMember' => ListInvalidUnsubMemberError,
94
+ 'List_InvalidBounceMember' => ListInvalidBounceMemberError,
95
+ 'List_AlreadySubscribed' => ListAlreadySubscribedError,
96
+ 'List_NotSubscribed' => ListNotSubscribedError,
97
+ 'List_InvalidImport' => ListInvalidImportError,
98
+ 'MC_PastedList_Duplicate' => MCPastedListDuplicateError,
99
+ 'MC_PastedList_InvalidImport' => MCPastedListInvalidImportError,
100
+ 'Email_AlreadySubscribed' => EmailAlreadySubscribedError,
101
+ 'Email_AlreadyUnsubscribed' => EmailAlreadyUnsubscribedError,
102
+ 'Email_NotExists' => EmailNotExistsError,
103
+ 'Email_NotSubscribed' => EmailNotSubscribedError,
104
+ 'List_MergeFieldRequired' => ListMergeFieldRequiredError,
105
+ 'List_CannotRemoveEmailMerge' => ListCannotRemoveEmailMergeError,
106
+ 'List_Merge_InvalidMergeID' => ListMergeInvalidMergeIDError,
107
+ 'List_TooManyMergeFields' => ListTooManyMergeFieldsError,
108
+ 'List_InvalidMergeField' => ListInvalidMergeFieldError,
109
+ 'List_InvalidInterestGroup' => ListInvalidInterestGroupError,
110
+ 'List_TooManyInterestGroups' => ListTooManyInterestGroupsError,
111
+ 'Campaign_DoesNotExist' => CampaignDoesNotExistError,
112
+ 'Campaign_StatsNotAvailable' => CampaignStatsNotAvailableError,
113
+ 'Campaign_InvalidAbsplit' => CampaignInvalidAbsplitError,
114
+ 'Campaign_InvalidContent' => CampaignInvalidContentError,
115
+ 'Campaign_InvalidOption' => CampaignInvalidOptionError,
116
+ 'Campaign_InvalidStatus' => CampaignInvalidStatusError,
117
+ 'Campaign_NotSaved' => CampaignNotSavedError,
118
+ 'Campaign_InvalidSegment' => CampaignInvalidSegmentError,
119
+ 'Campaign_InvalidRss' => CampaignInvalidRssError,
120
+ 'Campaign_InvalidAuto' => CampaignInvalidAutoError,
121
+ 'MC_ContentImport_InvalidArchive' => MCContentImportInvalidArchiveError,
122
+ 'Campaign_BounceMissing' => CampaignBounceMissingError,
123
+ 'Campaign_InvalidTemplate' => CampaignInvalidTemplateError,
124
+ 'Invalid_EcommOrder' => InvalidEcommOrderError,
125
+ 'Absplit_UnknownError' => AbsplitUnknownError,
126
+ 'Absplit_UnknownSplitTest' => AbsplitUnknownSplitTestError,
127
+ 'Absplit_UnknownTestType' => AbsplitUnknownTestTypeError,
128
+ 'Absplit_UnknownWaitUnit' => AbsplitUnknownWaitUnitError,
129
+ 'Absplit_UnknownWinnerType' => AbsplitUnknownWinnerTypeError,
130
+ 'Absplit_WinnerNotSelected' => AbsplitWinnerNotSelectedError,
131
+ 'Invalid_Analytics' => InvalidAnalyticsError,
132
+ 'Invalid_DateTime' => InvalidDateTimeError,
133
+ 'Invalid_Email' => InvalidEmailError,
134
+ 'Invalid_SendType' => InvalidSendTypeError,
135
+ 'Invalid_Template' => InvalidTemplateError,
136
+ 'Invalid_TrackingOptions' => InvalidTrackingOptionsError,
137
+ 'Invalid_Options' => InvalidOptionsError,
138
+ 'Invalid_Folder' => InvalidFolderError,
139
+ 'Invalid_URL' => InvalidURLError,
140
+ 'Module_Unknown' => ModuleUnknownError,
141
+ 'MonthlyPlan_Unknown' => MonthlyPlanUnknownError,
142
+ 'Order_TypeUnknown' => OrderTypeUnknownError,
143
+ 'Invalid_PagingLimit' => InvalidPagingLimitError,
144
+ 'Invalid_PagingStart' => InvalidPagingStartError,
145
+ 'Max_Size_Reached' => MaxSizeReachedError,
146
+ 'MC_SearchException' => MCSearchExceptionError
147
+ }
148
+
149
+ begin
150
+ error_info = JSON.parse(body)
151
+ if error_info['status'] != 'error' or not error_info['name']
152
+ raise Error, "We received an unexpected error: #{body}"
153
+ end
154
+ if error_map[error_info['name']]
155
+ raise error_map[error_info['name']], error_info['message']
156
+ else
157
+ raise Error, error_info['message']
158
+ end
159
+ rescue JSON::ParserError
160
+ raise Error, "We received an unexpected error: #{body}"
161
+ end
162
+ end
163
+
164
+ def folders()
165
+ Folders.new self
166
+ end
167
+ def templates()
168
+ Templates.new self
169
+ end
170
+ def users()
171
+ Users.new self
172
+ end
173
+ def helper()
174
+ Helper.new self
175
+ end
176
+ def mobile()
177
+ Mobile.new self
178
+ end
179
+ def ecomm()
180
+ Ecomm.new self
181
+ end
182
+ def neapolitan()
183
+ Neapolitan.new self
184
+ end
185
+ def lists()
186
+ Lists.new self
187
+ end
188
+ def campaigns()
189
+ Campaigns.new self
190
+ end
191
+ def vip()
192
+ Vip.new self
193
+ end
194
+ def reports()
195
+ Reports.new self
196
+ end
197
+ def gallery()
198
+ Gallery.new self
199
+ end
200
+ end
201
+ end
202
+
data/lib/mailchimp/api.rb ADDED
@@ -0,0 +1,2128 @@
1
+ module Mailchimp
2
+
3
+
4
+ class Folders
5
+ attr_accessor :master
6
+
7
+ def initialize(master)
8
+ @master = master
9
+ end
10
+
11
+ # Add a new folder to file campaigns, autoresponders, or templates in
12
+ # @param [String] name a unique name for a folder (max 100 bytes)
13
+ # @param [String] type the type of folder to create - one of "campaign", "autoresponder", or "template".
14
+ # @return [Hash] with a single value:
15
+ # - [Int] folder_id the folder_id of the newly created folder.
16
+ def add(name, type)
17
+ _params = {:name => name, :type => type}
18
+ return @master.call 'folders/add', _params
19
+ end
20
+
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()
23
+ # @param [String] type the type of folder to delete - either "campaign", "autoresponder", or "template"
24
+ # @return [Hash] with a single entry:
25
+ # - [Bool] complete whether the call worked. reallistically this will always be true as errors will be thrown otherwise.
26
+ def del(fid, type)
27
+ _params = {:fid => fid, :type => type}
28
+ return @master.call 'folders/del', _params
29
+ end
30
+
31
+ # List all the folders of a certain type
32
+ # @param [String] type the type of folders to return "campaign", "autoresponder", or "template"
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.
35
+ # - [String] name Name of the given folder
36
+ # - [String] date_created The date/time the folder was created
37
+ # - [String] type The type of the folders being returned, just to make sure you know.
38
+ # - [Int] cnt number of items in the folder.
39
+ def list(type)
40
+ _params = {:type => type}
41
+ return @master.call 'folders/list', _params
42
+ end
43
+
44
+ # Update the name of a folder for campaigns, autoresponders, or templates
45
+ # @param [Int] fid the folder id to update - retrieve from folders()
46
+ # @param [String] name a new, unique name for the folder (max 100 bytes)
47
+ # @param [String] type the type of folder to update - one of "campaign", "autoresponder", or "template".
48
+ # @return [Hash] with a single entry:
49
+ # - [Bool] complete whether the call worked. reallistically this will always be true as errors will be thrown otherwise.
50
+ def update(fid, name, type)
51
+ _params = {:fid => fid, :name => name, :type => type}
52
+ return @master.call 'folders/update', _params
53
+ end
54
+
55
+ end
56
+ class Templates
57
+ attr_accessor :master
58
+
59
+ def initialize(master)
60
+ @master = master
61
+ end
62
+
63
+ # Create a new user template, <strong>NOT</strong> campaign content. These templates can then be applied while creating campaigns.
64
+ # @param [String] name the name for the template - names must be unique and a max of 50 bytes
65
+ # @param [String] html a string specifying the entire template to be created. This is <strong>NOT</strong> campaign content. They are intended to utilize our <a href="http://www.mailchimp.com/resources/email-template-language/" target="_blank">template language</a>.
66
+ # @param [Int] folder_id the folder to put this template in.
67
+ # @return [Hash] with a single element:
68
+ # - [Int] template_id the new template id, otherwise an error is thrown.
69
+ def add(name, html, folder_id=nil)
70
+ _params = {:name => name, :html => html, :folder_id => folder_id}
71
+ return @master.call 'templates/add', _params
72
+ end
73
+
74
+ # Delete (deactivate) a user template
75
+ # @param [Int] template_id the id of the user template to delete
76
+ # @return [Hash] with a single entry:
77
+ # - [Bool] complete whether the call worked. reallistically this will always be true as errors will be thrown otherwise.
78
+ def del(template_id)
79
+ _params = {:template_id => template_id}
80
+ return @master.call 'templates/del', _params
81
+ end
82
+
83
+ # Pull details for a specific template to help support editing
84
+ # @param [Int] template_id the template id - get from templates()
85
+ # @param [String] type optional the template type to load - one of 'user', 'gallery', 'base', defaults to user.
86
+ # @return [Hash] info to be used when editing
87
+ # - [Hash] default_content the default content broken down into the named editable sections for the template - dependant upon template, so not documented
88
+ # - [Hash] sections the valid editable section names - dependant upon template, so not documented
89
+ # - [String] source the full source of the template as if you exported it via our template editor
90
+ # - [String] preview similar to the source, but the rendered version of the source from our popup preview
91
+ def info(template_id, type='user')
92
+ _params = {:template_id => template_id, :type => type}
93
+ return @master.call 'templates/info', _params
94
+ end
95
+
96
+ # Retrieve various templates available in the system, allowing some thing similar to our template gallery to be created.
97
+ # @param [Hash] types optional the types of templates to return
98
+ # - [Boolean] user Custom templates for this user account. Defaults to true.
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.
101
+ # @param [Hash] filters optional options to control how inactive templates are returned, if at all
102
+ # - [String] category optional for Gallery templates only, limit to a specific template category
103
+ # - [String] folder_id user templates, limit to this folder_id
104
+ # - [Boolean] include_inactive user templates are not deleted, only set inactive. defaults to false.
105
+ # - [Boolean] inactive_only only include inactive user templates. defaults to false.
106
+ # @return [Hash] for each type
107
+ # - [Array] user matching user templates, if requested.
108
+ # - [Int] id Id of the template
109
+ # - [String] name Name of the template
110
+ # - [String] layout General description of the layout of the template
111
+ # - [String] category The category for the template, if there is one.
112
+ # - [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
113
+ # - [String] date_created The date/time the template was created
114
+ # - [Boolean] active whether or not the template is active and available for use.
115
+ # - [Boolean] edit_source Whether or not you are able to edit the source of a template.
116
+ # - [Boolean] folder_id if it's in one, the folder id
117
+ # - [Array] gallery matching gallery templates, if requested.
118
+ # - [Int] id Id of the template
119
+ # - [String] name Name of the template
120
+ # - [String] layout General description of the layout of the template
121
+ # - [String] category The category for the template, if there is one.
122
+ # - [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
123
+ # - [String] date_created The date/time the template was created
124
+ # - [Boolean] active whether or not the template is active and available for use.
125
+ # - [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.
135
+ def list(types=[], filters=[])
136
+ _params = {:types => types, :filters => filters}
137
+ return @master.call 'templates/list', _params
138
+ end
139
+
140
+ # Undelete (reactivate) a user template
141
+ # @param [Int] template_id the id of the user template to reactivate
142
+ # @return [Hash] with a single entry:
143
+ # - [Bool] complete whether the call worked. reallistically this will always be true as errors will be thrown otherwise.
144
+ def undel(template_id)
145
+ _params = {:template_id => template_id}
146
+ return @master.call 'templates/undel', _params
147
+ end
148
+
149
+ # Replace the content of a user template, <strong>NOT</strong> campaign content.
150
+ # @param [Int] template_id the id of the user template to update
151
+ # @param [Hash] values the values to updates - while both are optional, at least one should be provided. Both can be updated at the same time.
152
+ # - [String] name the name for the template - names must be unique and a max of 50 bytes
153
+ # - [String] html a string specifying the entire template to be created. This is <strong>NOT</strong> campaign content. They are intended to utilize our <a href="http://www.mailchimp.com/resources/email-template-language/" target="_blank">template language</a>.
154
+ # - [Int] folder_id the folder to put this template in - 0 or a blank values will remove it from a folder.
155
+ # @return [Hash] with a single entry:
156
+ # - [Bool] complete whether the call worked. reallistically this will always be true as errors will be thrown otherwise.
157
+ def update(template_id, values)
158
+ _params = {:template_id => template_id, :values => values}
159
+ return @master.call 'templates/update', _params
160
+ end
161
+
162
+ end
163
+ class Users
164
+ attr_accessor :master
165
+
166
+ def initialize(master)
167
+ @master = master
168
+ end
169
+
170
+ # Invite a user to your account
171
+ # @param [String] email A valid email address to send the invitation to
172
+ # @param [String] role the role to assign to the user - one of viewer, author, manager, admin. defaults to viewer. More details <a href="http://kb.mailchimp.com/article/can-we-have-multiple-users-on-our-account-with-limited-access" target="_blank">here</a>
173
+ # @param [String] msg an optional message to include. Plain text any HTML tags will be stripped.
174
+ # @return [Hash] the method completion status
175
+ # - [String] status The status (success) of the call if it completed. Otherwise an error is thrown.
176
+ def invite(email, role='viewer', msg='')
177
+ _params = {:email => email, :role => role, :msg => msg}
178
+ return @master.call 'users/invite', _params
179
+ end
180
+
181
+ # Resend an invite a user to your account. Note, if the same address has been invited multiple times, this will simpy re-send the most recent invite
182
+ # @param [String] email A valid email address to resend an invitation to
183
+ # @return [Hash] the method completion status
184
+ # - [String] status The status (success) of the call if it completed. Otherwise an error is thrown.
185
+ def invite_resend(email)
186
+ _params = {:email => email}
187
+ return @master.call 'users/invite-resend', _params
188
+ end
189
+
190
+ # Revoke an invitation sent to a user to your account. Note, if the same address has been invited multiple times, this will simpy revoke the most recent invite
191
+ # @param [String] email A valid email address to send the invitation to
192
+ # @return [Hash] the method completion status
193
+ # - [String] status The status (success) of the call if it completed. Otherwise an error is thrown.
194
+ def invite_revoke(email)
195
+ _params = {:email => email}
196
+ return @master.call 'users/invite-revoke', _params
197
+ end
198
+
199
+ # Retrieve the list of pending users invitations have been sent for.
200
+ # @return [Array] structs for each invitation, including:
201
+ # - [String] email the email address the invitation was sent to
202
+ # - [String] role the role that will be assigned if they accept
203
+ # - [String] sent_at the time the invitation was sent. this will change if it's resent.
204
+ # - [String] expiration the expiration time for the invitation. this will change if it's resent.
205
+ # - [String] msg the welcome message included with the invitation
206
+ def invites()
207
+ _params = {}
208
+ return @master.call 'users/invites', _params
209
+ end
210
+
211
+ # Revoke access for a specified login
212
+ # @param [String] username The username of the login to revoke access of
213
+ # @return [Hash] the method completion status
214
+ # - [String] status The status (success) of the call if it completed. Otherwise an error is thrown.
215
+ def login_revoke(username)
216
+ _params = {:username => username}
217
+ return @master.call 'users/login-revoke', _params
218
+ end
219
+
220
+ # Retrieve the list of active logins.
221
+ # @return [Array] structs for each user, including:
222
+ # - [Int] id the login id for this login
223
+ # - [String] username the username used to log in
224
+ # - [String] name a display name for the account - empty first/last names will return the username
225
+ # - [String] email the email tied to the account used for passwords resets and the ilk
226
+ # - [String] role the role assigned to the account
227
+ def logins()
228
+ _params = {}
229
+ return @master.call 'users/logins', _params
230
+ end
231
+
232
+ end
233
+ class Helper
234
+ attr_accessor :master
235
+
236
+ def initialize(master)
237
+ @master = master
238
+ end
239
+
240
+ # 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.
241
+ # @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>.
242
+ # @return [Hash] containing the details for the account tied to this API Key
243
+ # - [String] username The Account username
244
+ # - [String] user_id The Account user unique id (for building some links)
245
+ # - [Bool] is_trial Whether the Account is in Trial mode (can only send campaigns to less than 100 emails)
246
+ # - [Bool] is_approved Whether the Account has been approved for purchases
247
+ # - [Bool] has_activated Whether the Account has been activated
248
+ # - [String] timezone The timezone for the Account - default is "US/Eastern"
249
+ # - [String] plan_type Plan Type - "monthly", "payasyougo", or "free"
250
+ # - [Int] plan_low <em>only for Monthly plans</em> - the lower tier for list size
251
+ # - [Int] plan_high <em>only for Monthly plans</em> - the upper tier for list size
252
+ # - [String] plan_start_date <em>only for Monthly plans</em> - the start date for a monthly plan
253
+ # - [Int] emails_left <em>only for Free and Pay-as-you-go plans</em> emails credits left for the account
254
+ # - [Bool] pending_monthly Whether the account is finishing Pay As You Go credits before switching to a Monthly plan
255
+ # - [String] first_payment date of first payment
256
+ # - [String] last_payment date of most recent payment
257
+ # - [Int] times_logged_in total number of times the account has been logged into via the web
258
+ # - [String] last_login date/time of last login via the web
259
+ # - [String] affiliate_link Monkey Rewards link for our Affiliate program
260
+ # - [String] industry the user's selected industry
261
+ # - [Hash] contact Contact details for the account
262
+ # - [String] fname First Name
263
+ # - [String] lname Last Name
264
+ # - [String] email Email Address
265
+ # - [String] company Company Name
266
+ # - [String] address1 Address Line 1
267
+ # - [String] address2 Address Line 2
268
+ # - [String] city City
269
+ # - [String] state State or Province
270
+ # - [String] zip Zip or Postal Code
271
+ # - [String] country Country name
272
+ # - [String] url Website URL
273
+ # - [String] phone Phone number
274
+ # - [String] fax Fax number
275
+ # - [Array] modules a struct for each addon module installed in the account
276
+ # - [String] id An internal module id
277
+ # - [String] name The module name
278
+ # - [String] added The date the module was added
279
+ # - [Hash] data Any extra data associated with this module as key=>value pairs
280
+ # - [Array] orders a struct for each order for the account
281
+ # - [Int] order_id The order id
282
+ # - [String] type The order type - either "monthly" or "credits"
283
+ # - [Double] amount The order amount
284
+ # - [String] date The order date
285
+ # - [Double] credits_used The total credits used
286
+ # - [Hash] rewards Rewards details for the account including credits & inspections earned, number of referrals, referral details, and rewards used
287
+ # - [Int] referrals_this_month the total number of referrals this month
288
+ # - [String] notify_on whether or not we notify the user when rewards are earned
289
+ # - [String] notify_email the email address address used for rewards notifications
290
+ # - [Hash] credits Email credits earned:
291
+ # - [Int] this_month credits earned this month
292
+ # - [Int] total_earned credits earned all time
293
+ # - [Int] remaining credits remaining
294
+ # - [Hash] inspections Inbox Inspections earned:
295
+ # - [Int] this_month credits earned this month
296
+ # - [Int] total_earned credits earned all time
297
+ # - [Int] remaining credits remaining
298
+ # - [Array] referrals a struct for each referral, including:
299
+ # - [String] name the name of the account
300
+ # - [String] email the email address associated with the account
301
+ # - [String] signup_date the signup date for the account
302
+ # - [String] type the source for the referral
303
+ # - [Array] applied a struct for each applied rewards, including:
304
+ # - [Int] value the number of credits user
305
+ # - [String] date the date applied
306
+ # - [Int] order_id the order number credits were applied to
307
+ # - [String] order_desc the order description
308
+ # - [Array] integrations a struct for each connected integrations that can be used with campaigns, including:
309
+ # - [Int] id an internal id for the integration
310
+ # - [String] name the integration name
311
+ # - [String] list_id either "_any_" when globally accessible or the list id it's valid for use against
312
+ # - [String] user_id if applicable, the user id for the integrated system
313
+ # - [String] account if applicable, the user/account name for the integrated system
314
+ # - [Array] profiles For Facebook, users/page that can be posted to.
315
+ # - [String] id the user or page id
316
+ # - [String] name the user or page name
317
+ # - [Bool] is_page whether this is a user or a page
318
+ def account_details(exclude=[])
319
+ _params = {:exclude => exclude}
320
+ return @master.call 'helper/account-details', _params
321
+ end
322
+
323
+ # Retrieve minimal data for all Campaigns a member was sent
324
+ # @param [Hash] email a struct with one fo the following keys - failing to provide anything will produce an error relating to the email address
325
+ # - [String] email an email address
326
+ # - [String] euid the unique id for an email address (not list related) - the email "id" returned from listMemberInfo, Webhooks, Campaigns, etc.
327
+ # - [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
328
+ # @param [Hash] options optional extra options to modify the returned data.
329
+ # - [String] list_id optional A list_id to limit the campaigns to
330
+ # @return [Array] an array of structs containing campaign data for each matching campaign (ordered by send time ascending), including:
331
+ # - [String] id the campaign unique id
332
+ # - [String] title the campaign's title
333
+ # - [String] subject the campaign's subject
334
+ # - [String] send_time the time the campaign was sent
335
+ # - [String] type the campaign type
336
+ def campaigns_for_email(email, options=nil)
337
+ _params = {:email => email, :options => options}
338
+ return @master.call 'helper/campaigns-for-email', _params
339
+ end
340
+
341
+ # Return the current Chimp Chatter messages for an account.
342
+ # @return [Array] An array of structs containing data for each chatter message
343
+ # - [String] message The chatter message
344
+ # - [String] type The type of the message - one of lists:new-subscriber, lists:unsubscribes, lists:profile-updates, campaigns:facebook-likes, campaigns:facebook-comments, campaigns:forward-to-friend, lists:imports, or campaigns:inbox-inspections
345
+ # - [String] url a url into the web app that the message could link to, if applicable
346
+ # - [String] list_id the list_id a message relates to, if applicable. Deleted lists will return -DELETED-
347
+ # - [String] campaign_id the list_id a message relates to, if applicable. Deleted campaigns will return -DELETED-
348
+ # - [String] update_time The date/time the message was last updated
349
+ def chimp_chatter()
350
+ _params = {}
351
+ return @master.call 'helper/chimp-chatter', _params
352
+ end
353
+
354
+ # Have HTML content auto-converted to a text-only format. You can send: plain HTML, an existing Campaign Id, or an existing Template Id. Note that this will <strong>not</strong> save anything to or update any of your lists, campaigns, or templates. It's also not just Lynx and is very fine tuned for our template layouts - your mileage may vary.
355
+ # @param [String] type The type of content to parse. Must be one of: "html", "url", "cid" (Campaign Id), "user_template_id", "base_template_id", "gallery_template_id"
356
+ # @param [Hash] content The content to use. The key names should be the same as type and while listed as optional, may cause errors if the content is obviously required (ie, html)
357
+ # - [String] html optional a single string value,
358
+ # - [String] cid a valid Campaign Id
359
+ # - [String] user_template_id the id of a user template
360
+ # - [String] base_template_id the id of a built in base/basic template
361
+ # - [String] gallery_template_id the id of a built in gallery template
362
+ # - [String] url a valid & public URL to pull html content from
363
+ # @return [Hash] the content pass in converted to text.
364
+ # - [String] text the converted html
365
+ def generate_text(type, content)
366
+ _params = {:type => type, :content => content}
367
+ return @master.call 'helper/generate-text', _params
368
+ end
369
+
370
+ # Send your HTML content to have the CSS inlined and optionally remove the original styles.
371
+ # @param [String] html Your HTML content
372
+ # @param [Bool] strip_css optional Whether you want the CSS &lt;style&gt; tags stripped from the returned document. Defaults to false.
373
+ # @return [Hash] with a "html" key
374
+ # - [String] html Your HTML content with all CSS inlined, just like if we sent it.
375
+ def inline_css(html, strip_css=false)
376
+ _params = {:html => html, :strip_css => strip_css}
377
+ return @master.call 'helper/inline-css', _params
378
+ end
379
+
380
+ # Retrieve minimal List data for all lists a member is subscribed to.
381
+ # @param [Hash] email a struct with one fo the following keys - failing to provide anything will produce an error relating to the email address
382
+ # - [String] email an email address
383
+ # - [String] euid the unique id for an email address (not list related) - the email "id" returned from listMemberInfo, Webhooks, Campaigns, etc.
384
+ # - [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
385
+ # @return [Array] An array of structs with info on the list_id the member is subscribed to.
386
+ # - [String] id the list unique id
387
+ # - [Web_id] the id referenced in web interface urls
388
+ # - [Name] the list name
389
+ def lists_for_email(email)
390
+ _params = {:email => email}
391
+ return @master.call 'helper/lists-for-email', _params
392
+ end
393
+
394
+ # "Ping" the MailChimp API - a simple method you can call that will return a constant value as long as everything is good. Note than unlike most all of our methods, we don't throw an Exception if we are having issues. You will simply receive a different string back that will explain our view on what is going on.
395
+ # @return [Hash] a with a "msg" key
396
+ # - [String] msg containing "Everything's Chimpy!" if everything is chimpy, otherwise returns an error message
397
+ def ping()
398
+ _params = {}
399
+ return @master.call 'helper/ping', _params
400
+ end
401
+
402
+ # Search all campaigns for the specified query terms
403
+ # @param [String] query terms to search on
404
+ # @param [Int] offset optional the paging offset to use if more than 100 records match
405
+ # @param [String] snip_start optional by default clear text is returned. To have the match highlighted with something (like a strong HTML tag), <strong>both</strong> this and "snip_end" must be passed. You're on your own to not break the tags - 25 character max.
406
+ # @param [String] snip_end optional see "snip_start" above.
407
+ # @return [Hash] containing the total matches and current results
408
+ # - [Int] total total campaigns matching
409
+ # - [Array] results matching campaigns and snippets
410
+ # - [String] snippet the matching snippet for the campaign
411
+ # - [Hash] campaign the matching campaign's details - will return same data as single campaign from campaigns()
412
+ # - [Hash] summary if available, the matching campaign's report/summary data, other wise empty
413
+ def search_campaigns(query, offset=0, snip_start=nil, snip_end=nil)
414
+ _params = {:query => query, :offset => offset, :snip_start => snip_start, :snip_end => snip_end}
415
+ return @master.call 'helper/search-campaigns', _params
416
+ end
417
+
418
+ # Search account wide or on a specific list using the specified query terms
419
+ # @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>
420
+ # @param [String] id optional the list id to limit the search to. Get by calling lists()
421
+ # @param [Int] offset optional the paging offset to use if more than 100 records match
422
+ # @return [Hash] An array of both exact matches and partial matches over a full search
423
+ # - [Hash] exact_matches containing the total matches and current results
424
+ # - [Int] total total members matching
425
+ # - [Array] members each entry will be struct matching the data format for a single member as returned by listMemberInfo()
426
+ # - [Hash] full_search containing the total matches and current results
427
+ # - [Int] total total members matching
428
+ # - [Array] members each entry will be struct matching the data format for a single member as returned by listMemberInfo()
429
+ def search_members(query, id=nil, offset=0)
430
+ _params = {:query => query, :id => id, :offset => offset}
431
+ return @master.call 'helper/search-members', _params
432
+ end
433
+
434
+ # Retrieve all domain verification records for an account
435
+ # @return [Array] structs for each domain verification has been attempted for
436
+ # - [String] domain the verified domain
437
+ # - [String] status the status of the verification - either "verified" or "pending"
438
+ # - [String] email the email address used for verification - "pre-existing" if we automatically backfilled it at some point
439
+ def verified_domains()
440
+ _params = {}
441
+ return @master.call 'helper/verified-domains', _params
442
+ end
443
+
444
+ end
445
+ class Mobile
446
+ attr_accessor :master
447
+
448
+ def initialize(master)
449
+ @master = master
450
+ end
451
+
452
+ end
453
+ class Ecomm
454
+ attr_accessor :master
455
+
456
+ def initialize(master)
457
+ @master = master
458
+ end
459
+
460
+ # Import Ecommerce Order Information to be used for Segmentation. This will generally be used by ecommerce package plugins <a href="http://connect.mailchimp.com/category/ecommerce" target="_blank">provided by us or by 3rd part system developers</a>.
461
+ # @param [Hash] order information pertaining to the order that has completed. Use the following keys:
462
+ # - [String] id the Order Id
463
+ # - [String] campaign_id optional the Campaign Id to track this order against (see the "mc_cid" query string variable a campaign passes)
464
+ # - [String] email_id optional (kind of) the Email Id of the subscriber we should attach this order to (see the "mc_eid" query string variable a campaign passes) - required if campaign_id is passed, otherwise either this or <strong>email</strong> is required. If both are provided, email_id takes precedence
465
+ # - [String] email optional (kind of) the Email Address we should attach this order to - either this or <strong>email_id</strong> is required. If both are provided, email_id takes precedence
466
+ # - [Double] total The Order Total (ie, the full amount the customer ends up paying)
467
+ # - [String] order_date optional the date of the order - if this is not provided, we will default the date to now. Should be in the format of 2012-12-30
468
+ # - [Double] shipping optional the total paid for Shipping Fees
469
+ # - [Double] tax optional the total tax paid
470
+ # - [String] store_id a unique id for the store sending the order in (32 bytes max)
471
+ # - [String] store_name optional a "nice" name for the store - typically the base web address (ie, "store.mailchimp.com"). We will automatically update this if it changes (based on store_id)
472
+ # - [Array] items structs for each individual line item including:
473
+ # - [Int] line_num optional the line number of the item on the order. We will generate these if they are not passed
474
+ # - [Int] product_id the store's internal Id for the product. Lines that do no contain this will be skipped
475
+ # - [String] sku optional the store's internal SKU for the product. (max 30 bytes)
476
+ # - [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)
477
+ # - [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
478
+ # - [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.
479
+ # - [Double] qty optional the quantity of the item ordered - defaults to 1
480
+ # - [Double] cost optional the cost of a single item (ie, not the extended cost of the line) - defaults to 0
481
+ # @return [Hash] with a single entry:
482
+ # - [Bool] complete whether the call worked. reallistically this will always be true as errors will be thrown otherwise.
483
+ def order_add(order)
484
+ _params = {:order => order}
485
+ return @master.call 'ecomm/order-add', _params
486
+ end
487
+
488
+ # Delete Ecommerce Order Information used for segmentation. This will generally be used by ecommerce package plugins <a href="/plugins/ecomm360.phtml">that we provide</a> or by 3rd part system developers.
489
+ # @param [String] store_id the store id the order belongs to
490
+ # @param [String] order_id the order id (generated by the store) to delete
491
+ # @return [Hash] with a single entry:
492
+ # - [Bool] complete whether the call worked. reallistically this will always be true as errors will be thrown otherwise.
493
+ def order_del(store_id, order_id)
494
+ _params = {:store_id => store_id, :order_id => order_id}
495
+ return @master.call 'ecomm/order-del', _params
496
+ end
497
+
498
+ # Retrieve the Ecommerce Orders for an account
499
+ # @param [String] cid if set, limit the returned orders to a particular campaign
500
+ # @param [Int] start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
501
+ # @param [Int] limit optional for large data sets, the number of results to return - defaults to 100, upper limit set at 500
502
+ # @param [String] since optional pull only messages since this time - 24 hour format in <strong>GMT</strong>, eg "2013-12-30 20:30:00"
503
+ # @return [Hash] the total matching orders and the specific orders for the requested page
504
+ # - [Int] total the total matching orders
505
+ # - [Array] data structs for each order being returned
506
+ # - [String] store_id the store id generated by the plugin used to uniquely identify a store
507
+ # - [String] store_name the store name collected by the plugin - often the domain name
508
+ # - [String] order_id the internal order id the store tracked this order by
509
+ # - [String] email the email address that received this campaign and is associated with this order
510
+ # - [Double] order_total the order total
511
+ # - [Double] tax_total the total tax for the order (if collected)
512
+ # - [Double] ship_total the shipping total for the order (if collected)
513
+ # - [String] order_date the date the order was tracked - from the store if possible, otherwise the GMT time we received it
514
+ # - [Array] items structs for each line item on this order.:
515
+ # - [Int] line_num the line number
516
+ # - [Int] product_id the product id
517
+ # - [String] product_name the product name
518
+ # - [String] product_sku the sku for the product
519
+ # - [Int] product_category_id the category id for the product
520
+ # - [String] product_category_name the category name for the product
521
+ # - [Int] qty the quantity ordered
522
+ # - [Double] cost the cost of the item
523
+ def orders(cid=nil, start=0, limit=100, since=nil)
524
+ _params = {:cid => cid, :start => start, :limit => limit, :since => since}
525
+ return @master.call 'ecomm/orders', _params
526
+ end
527
+
528
+ end
529
+ class Neapolitan
530
+ attr_accessor :master
531
+
532
+ def initialize(master)
533
+ @master = master
534
+ end
535
+
536
+ end
537
+ class Lists
538
+ attr_accessor :master
539
+
540
+ def initialize(master)
541
+ @master = master
542
+ end
543
+
544
+ # Get all email addresses that complained about a campaign sent to a list
545
+ # @param [String] id the list id to pull abuse reports for (can be gathered using lists())
546
+ # @param [Int] start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
547
+ # @param [Int] limit optional for large data sets, the number of results to return - defaults to 500, upper limit set at 1000
548
+ # @param [String] since optional pull only messages since this time - 24 hour format in <strong>GMT</strong>, eg "2013-12-30 20:30:00"
549
+ # @return [Hash] the total of all reports and the specific reports reports this page
550
+ # - [Int] total the total number of matching abuse reports
551
+ # - [Array] data structs for the actual data for each reports, including:
552
+ # - [String] date date/time the abuse report was received and processed
553
+ # - [String] email the email address that reported abuse
554
+ # - [String] campaign_id the unique id for the campaign that report was made against
555
+ # - [String] type an internal type generally specifying the orginating mail provider - may not be useful outside of filling report views
556
+ def abuse_reports(id, start=0, limit=500, since=nil)
557
+ _params = {:id => id, :start => start, :limit => limit, :since => since}
558
+ return @master.call 'lists/abuse-reports', _params
559
+ end
560
+
561
+ # Access up to the previous 180 days of daily detailed aggregated activity stats for a given list. Does not include AutoResponder activity.
562
+ # @param [String] id the list id to connect to. Get by calling lists()
563
+ # @return [Array] of structs containing daily values, each containing:
564
+ def activity(id)
565
+ _params = {:id => id}
566
+ return @master.call 'lists/activity', _params
567
+ end
568
+
569
+ # 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.
570
+ # @param [String] id the list id to connect to. Get by calling lists()
571
+ # @param [Array] batch an array of structs for each address using the following keys:
572
+ # - [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.
573
+ # - [String] email an email address
574
+ # - [String] euid the unique id for an email address (not list related) - the email "id" returned from listMemberInfo, Webhooks, Campaigns, etc.
575
+ # - [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
576
+ # - [String] email_type for the email type option (html or text)
577
+ # - [Hash] merge_vars data for the various list specific and special merge vars documented in lists/subscribe
578
+ # @param [Boolean] double_optin flag to control whether to send an opt-in confirmation email - defaults to true
579
+ # @param [Boolean] update_existing flag to control whether to update members that are already subscribed to the list or to return an error, defaults to false (return error)
580
+ # @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)
581
+ # @return [Hash] struct of result counts and associated data
582
+ # - [Int] add_count Number of email addresses that were successfully added
583
+ # - [Array] adds array of structs for each add
584
+ # - [String] email the email address added
585
+ # - [String] euid the email unique id
586
+ # - [String] leid the list member's truly unique id
587
+ # - [Int] update_count Number of email addresses that were successfully updated
588
+ # - [Array] updates array of structs for each update
589
+ # - [String] email the email address added
590
+ # - [String] euid the email unique id
591
+ # - [String] leid the list member's truly unique id
592
+ # - [Int] error_count Number of email addresses that failed during addition/updating
593
+ # - [Array] errors array of error structs including:
594
+ # - [String] email whatever was passed in the batch record's email parameter
595
+ # - [String] email the email address added
596
+ # - [String] euid the email unique id
597
+ # - [String] leid the list member's truly unique id
598
+ # - [Int] code the error code
599
+ # - [String] error the full error message
600
+ # - [Hash] row the row from the batch that caused the error
601
+ def batch_subscribe(id, batch, double_optin=true, update_existing=false, replace_interests=true)
602
+ _params = {:id => id, :batch => batch, :double_optin => double_optin, :update_existing => update_existing, :replace_interests => replace_interests}
603
+ return @master.call 'lists/batch-subscribe', _params
604
+ end
605
+
606
+ # Unsubscribe a batch of email addresses from a list
607
+ # @param [String] id the list id to connect to. Get by calling lists()
608
+ # @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.
609
+ # - [String] email an email address
610
+ # - [String] euid the unique id for an email address (not list related) - the email "id" returned from listMemberInfo, Webhooks, Campaigns, etc.
611
+ # - [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
612
+ # @param [Boolean] delete_member flag to completely delete the member from your list instead of just unsubscribing, default to false
613
+ # @param [Boolean] send_goodbye flag to send the goodbye email to the email addresses, defaults to true
614
+ # @param [Boolean] send_notify flag to send the unsubscribe notification email to the address defined in the list email notification settings, defaults to false
615
+ # @return [Array] Array of structs containing results and any errors that occurred
616
+ # - [Int] success_count Number of email addresses that were successfully removed
617
+ # - [Int] error_count Number of email addresses that failed during addition/updating
618
+ # - [Array] of structs contain error details including:
619
+ # - [Array] errors array of error structs including:
620
+ # - [String] email whatever was passed in the batch record's email parameter
621
+ # - [String] email the email address added
622
+ # - [String] euid the email unique id
623
+ # - [String] leid the list member's truly unique id
624
+ # - [Int] code the error code
625
+ # - [String] error the full error message
626
+ def batch_unsubscribe(id, batch, delete_member=false, send_goodbye=true, send_notify=false)
627
+ _params = {:id => id, :batch => batch, :delete_member => delete_member, :send_goodbye => send_goodbye, :send_notify => send_notify}
628
+ return @master.call 'lists/batch-unsubscribe', _params
629
+ end
630
+
631
+ # 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>
632
+ # @param [String] id the list id to connect to. Get by calling lists()
633
+ # @return [Hash] the desktop and mobile user agents in use on the list
634
+ # - [Hash] desktop desktop user agents and percentages
635
+ # - [Double] penetration the percent of desktop clients in use
636
+ # - [Array] clients array of structs for each client including:
637
+ # - [String] client the common name for the client
638
+ # - [String] icon a url to an image representing this client
639
+ # - [String] percent percent of list using the client
640
+ # - [String] members total members using the client
641
+ # - [Hash] mobile mobile user agents and percentages
642
+ # - [Double] penetration the percent of mobile clients in use
643
+ # - [Array] clients array of structs for each client including:
644
+ # - [String] client the common name for the client
645
+ # - [String] icon a url to an image representing this client
646
+ # - [String] percent percent of list using the client
647
+ # - [String] members total members using the client
648
+ def clients(id)
649
+ _params = {:id => id}
650
+ return @master.call 'lists/clients', _params
651
+ end
652
+
653
+ # Access the Growth History by Month in aggregate or for a given list.
654
+ # @param [String] id optional - if provided, the list id to connect to. Get by calling lists/list. Otherwise the aggregate for the account.
655
+ # @return [Array] array of structs containing months and growth data
656
+ # - [String] month The Year and Month in question using YYYY-MM format
657
+ # - [Int] existing number of existing subscribers to start the month
658
+ # - [Int] imports number of subscribers imported during the month
659
+ # - [Int] optins number of subscribers who opted-in during the month
660
+ def growth_history(id=nil)
661
+ _params = {:id => id}
662
+ return @master.call 'lists/growth-history', _params
663
+ end
664
+
665
+ # Get the list of interest groupings for a given list, including the label, form information, and included groups for each
666
+ # @param [String] id the list id to connect to. Get by calling lists()
667
+ # @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.
668
+ # @return [Array] array of structs of the interest groupings for the list
669
+ # - [Int] id The id for the Grouping
670
+ # - [String] name Name for the Interest groups
671
+ # - [String] form_field Gives the type of interest group: checkbox,radio,select
672
+ # - [Array] groups Array structs of the grouping options (interest groups) including:
673
+ # - [String] bit the bit value - not really anything to be done with this
674
+ # - [String] name the name of the group
675
+ # - [String] display_order the display order of the group, if set
676
+ # - [Int] subscribers total number of subscribers who have this group if "counts" is true. otherwise empty
677
+ def interest_groupings(id, counts=false)
678
+ _params = {:id => id, :counts => counts}
679
+ return @master.call 'lists/interest-groupings', _params
680
+ end
681
+
682
+ # Add a single Interest Group - if interest groups for the List are not yet enabled, adding the first group will automatically turn them on.
683
+ # @param [String] id the list id to connect to. Get by calling lists()
684
+ # @param [String] group_name the interest group to add - group names must be unique within a grouping
685
+ # @param [Int] grouping_id optional The grouping to add the new group to - get using listInterestGrouping() . If not supplied, the first grouping on the list is used.
686
+ # @return [Hash] with a single entry:
687
+ # - [Bool] complete whether the call worked. reallistically this will always be true as errors will be thrown otherwise.
688
+ def interest_group_add(id, group_name, grouping_id=nil)
689
+ _params = {:id => id, :group_name => group_name, :grouping_id => grouping_id}
690
+ return @master.call 'lists/interest-group-add', _params
691
+ end
692
+
693
+ # Delete a single Interest Group - if the last group for a list is deleted, this will also turn groups for the list off.
694
+ # @param [String] id the list id to connect to. Get by calling lists()
695
+ # @param [String] group_name the interest group to delete
696
+ # @param [Int] grouping_id The grouping to delete the group from - get using listInterestGrouping() . If not supplied, the first grouping on the list is used.
697
+ # @return [Hash] with a single entry:
698
+ # - [Bool] complete whether the call worked. reallistically this will always be true as errors will be thrown otherwise.
699
+ def interest_group_del(id, group_name, grouping_id=nil)
700
+ _params = {:id => id, :group_name => group_name, :grouping_id => grouping_id}
701
+ return @master.call 'lists/interest-group-del', _params
702
+ end
703
+
704
+ # Change the name of an Interest Group
705
+ # @param [String] id the list id to connect to. Get by calling lists()
706
+ # @param [String] old_name the interest group name to be changed
707
+ # @param [String] new_name the new interest group name to be set
708
+ # @param [Int] grouping_id optional The grouping to delete the group from - get using listInterestGrouping() . If not supplied, the first grouping on the list is used.
709
+ # @return [Hash] with a single entry:
710
+ # - [Bool] complete whether the call worked. reallistically this will always be true as errors will be thrown otherwise.
711
+ def interest_group_update(id, old_name, new_name, grouping_id=nil)
712
+ _params = {:id => id, :old_name => old_name, :new_name => new_name, :grouping_id => grouping_id}
713
+ return @master.call 'lists/interest-group-update', _params
714
+ end
715
+
716
+ # Add a new Interest Grouping - if interest groups for the List are not yet enabled, adding the first grouping will automatically turn them on.
717
+ # @param [String] id the list id to connect to. Get by calling lists()
718
+ # @param [String] name the interest grouping to add - grouping names must be unique
719
+ # @param [String] type The type of the grouping to add - one of "checkboxes", "hidden", "dropdown", "radio"
720
+ # @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.
721
+ # @return [Hash] with a single entry:
722
+ # - [Int] id the new grouping id if the request succeeds, otherwise an error will be thrown
723
+ def interest_grouping_add(id, name, type, groups)
724
+ _params = {:id => id, :name => name, :type => type, :groups => groups}
725
+ return @master.call 'lists/interest-grouping-add', _params
726
+ end
727
+
728
+ # Delete an existing Interest Grouping - this will permanently delete all contained interest groups and will remove those selections from all list members
729
+ # @param [Int] grouping_id the interest grouping id - get from listInterestGroupings()
730
+ # @return [Hash] with a single entry:
731
+ # - [Bool] complete whether the call worked. reallistically this will always be true as errors will be thrown otherwise.
732
+ def interest_grouping_del(grouping_id)
733
+ _params = {:grouping_id => grouping_id}
734
+ return @master.call 'lists/interest-grouping-del', _params
735
+ end
736
+
737
+ # Update an existing Interest Grouping
738
+ # @param [Int] grouping_id the interest grouping id - get from listInterestGroupings()
739
+ # @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
740
+ # @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.
741
+ # @return [Hash] with a single entry:
742
+ # - [Bool] complete whether the call worked. reallistically this will always be true as errors will be thrown otherwise.
743
+ def interest_grouping_update(grouping_id, name, value)
744
+ _params = {:grouping_id => grouping_id, :name => name, :value => value}
745
+ return @master.call 'lists/interest-grouping-update', _params
746
+ end
747
+
748
+ # Retrieve the locations (countries) that the list's subscribers have been tagged to based on geocoding their IP address
749
+ # @param [String] id the list id to connect to. Get by calling lists()
750
+ # @return [Array] array of locations
751
+ # - [String] country the country name
752
+ # - [String] cc the ISO 3166 2 digit country code
753
+ # - [Double] percent the percent of subscribers in the country
754
+ # - [Double] total the total number of subscribers in the country
755
+ def locations(id)
756
+ _params = {:id => id}
757
+ return @master.call 'lists/locations', _params
758
+ end
759
+
760
+ # Get the most recent 100 activities for particular list members (open, click, bounce, unsub, abuse, sent to, etc.)
761
+ # @param [String] id the list id to connect to. Get by calling lists()
762
+ # @param [Array] emails an array of up to 50 email address struct to retrieve activity information for
763
+ # - [String] email an email address
764
+ # - [String] euid the unique id for an email address (not list related) - the email "id" returned from listMemberInfo, Webhooks, Campaigns, etc.
765
+ # - [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
766
+ # @return [Hash] of data and success/error counts
767
+ # - [Int] success_count the number of subscribers successfully found on the list
768
+ # - [Int] error_count the number of subscribers who were not found on the list
769
+ # - [Array] errors array of error structs including:
770
+ # - [String] email whatever was passed in the email parameter
771
+ # - [String] email the email address added
772
+ # - [String] euid the email unique id
773
+ # - [String] leid the list member's truly unique id
774
+ # - [String] error the error message
775
+ # - [String] code the error code
776
+ # - [Array] data an array of structs where each activity record has:
777
+ # - [String] email whatever was passed in the email parameter
778
+ # - [String] email the email address added
779
+ # - [String] euid the email unique id
780
+ # - [String] leid the list member's truly unique id
781
+ # - [Array] activity an array of structs containing the activity, including:
782
+ # - [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
783
+ # - [String] timestamp The date/time of the action (GMT)
784
+ # - [String] url For click actions, the url clicked, otherwise this is empty
785
+ # - [String] type If there's extra bounce, unsub, etc data it will show up here.
786
+ # - [String] campaign_id The campaign id the action was related to, if it exists - otherwise empty (ie, direct unsub from list)
787
+ # - [Hash] campaign_data If not deleted, the campaigns/list data for the campaign
788
+ def member_activity(id, emails)
789
+ _params = {:id => id, :emails => emails}
790
+ return @master.call 'lists/member-activity', _params
791
+ end
792
+
793
+ # Get all the information for particular members of a list
794
+ # @param [String] id the list id to connect to. Get by calling lists()
795
+ # @param [Array] emails an array of up to 50 email address struct to retrieve member information for
796
+ # - [String] email an email address
797
+ # - [String] euid the unique id for an email address (not list related) - the email "id" returned from listMemberInfo, Webhooks, Campaigns, etc.
798
+ # - [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
799
+ # @return [Hash] of data and success/error counts
800
+ # - [Int] success_count the number of subscribers successfully found on the list
801
+ # - [Int] error_count the number of subscribers who were not found on the list
802
+ # - [Array] errors array of error structs including:
803
+ # - [Hash] email whatever was passed in the email parameter
804
+ # - [String] email the email address added
805
+ # - [String] euid the email unique id
806
+ # - [String] leid the list member's truly unique id
807
+ # - [String] error the error message
808
+ # - [Array] data array of structs for each valid list member
809
+ # - [String] id The unique id (euid) for this email address on an account
810
+ # - [String] email The email address associated with this record
811
+ # - [String] email_type The type of emails this customer asked to get: html or text
812
+ # - [Hash] merges a struct containing a key for each merge tags and the data for those tags for this email address, plus:
813
+ # - [Array] GROUPINGS if Interest groupings are enabled, this will exist with structs for each grouping:
814
+ # - [Int] id the grouping id
815
+ # - [String] name the interest group name
816
+ # - [Array] groups structs for each group in the grouping
817
+ # - [String] name the group name
818
+ # - [Bool] interested whether the member has this group selected
819
+ # - [String] status The subscription status for this email address, either pending, subscribed, unsubscribed, or cleaned
820
+ # - [String] ip_signup IP Address this address signed up from. This may be blank if single optin is used.
821
+ # - [String] timestamp_signup The date/time the double optin was initiated. This may be blank if single optin is used.
822
+ # - [String] ip_opt IP Address this address opted in from.
823
+ # - [String] timestamp_opt The date/time the optin completed
824
+ # - [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>
825
+ # - [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.
826
+ # - [Array] lists An array of structs for the other lists this member belongs to
827
+ # - [String] id the list id
828
+ # - [String] status the members status on that list
829
+ # - [String] timestamp The date/time this email address entered it's current status
830
+ # - [String] info_changed The last time this record was changed. If the record is old enough, this may be blank.
831
+ # - [Int] web_id The Member id used in our web app, allows you to create a link directly to it
832
+ # - [Int] leid The Member id used in our web app, allows you to create a link directly to it
833
+ # - [String] list_id The list id the for the member record being returned
834
+ # - [String] list_name The list name the for the member record being returned
835
+ # - [String] language if set/detected, a language code from <a href="http://kb.mailchimp.com/article/can-i-see-what-languages-my-subscribers-use#code" target="_blank">here</a>
836
+ # - [Bool] is_gmonkey Whether the member is a <a href="http://mailchimp.com/features/golden-monkeys/" target="_blank">Golden Monkey</a> or not.
837
+ # - [Hash] geo the geographic information if we have it. including:
838
+ # - [String] latitude the latitude
839
+ # - [String] longitude the longitude
840
+ # - [String] gmtoff GMT offset
841
+ # - [String] dstoff GMT offset during daylight savings (if DST not observered, will be same as gmtoff)
842
+ # - [String] timezone the timezone we've place them in
843
+ # - [String] cc 2 digit ISO-3166 country code
844
+ # - [String] region generally state, province, or similar
845
+ # - [Hash] clients the client we've tracked the address as using with two keys:
846
+ # - [String] name the common name of the client
847
+ # - [String] icon_url a url representing a path to an icon representing this client
848
+ # - [Array] static_segments structs for each static segments the member is a part of including:
849
+ # - [Int] id the segment id
850
+ # - [String] name the name given to the segment
851
+ # - [String] added the date the member was added
852
+ # - [Array] notes structs for each note entered for this member. For each note:
853
+ # - [Int] id the note id
854
+ # - [String] note the text entered
855
+ # - [String] created the date the note was created
856
+ # - [String] updated the date the note was last updated
857
+ # - [String] created_by_name the name of the user who created the note. This can change as users update their profile.
858
+ def member_info(id, emails)
859
+ _params = {:id => id, :emails => emails}
860
+ return @master.call 'lists/member-info', _params
861
+ end
862
+
863
+ # 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>
864
+ # @param [String] id the list id to connect to. Get by calling lists()
865
+ # @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
866
+ # @param [Hash] opts various options for controlling returned data
867
+ # - [Int] start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
868
+ # - [Int] limit optional for large data sets, the number of results to return - defaults to 25, upper limit set at 100
869
+ # - [String] sort_field optional the data field to sort by - mergeX (1-30), your custom merge tags, "email", "rating","last_update_time", or "optin_time" - invalid fields will be ignored
870
+ # - [String] sort_dir optional the direct - ASC or DESC. defaults to ASC (case insensitive)
871
+ # - [Hash] segment a properly formatted segment that works with campaigns/segment-test
872
+ # @return [Hash] of the total records matched and limited list member data for this page
873
+ # - [Int] total the total matching records
874
+ # - [Array] data structs for each member as returned by member-info
875
+ def members(id, status='subscribed', opts=[])
876
+ _params = {:id => id, :status => status, :opts => opts}
877
+ return @master.call 'lists/members', _params
878
+ end
879
+
880
+ # Add a new merge tag to a given list
881
+ # @param [String] id the list id to connect to. Get by calling lists()
882
+ # @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>
883
+ # @param [String] name The long description of the tag being added, used for user displays - max 50 bytes
884
+ # @param [Array] options optional Various options for this merge var. <em>note:</em> for historical purposes this can also take a "boolean"
885
+ # - [String] field_type optional one of: text, number, radio, dropdown, date, address, phone, url, imageurl, zip, birthday - defaults to text
886
+ # - [Boolean] req optional indicates whether the field is required - defaults to false
887
+ # - [Boolean] public optional indicates whether the field is displayed in public - defaults to true
888
+ # - [Boolean] show optional indicates whether the field is displayed in the app's list member view - defaults to true
889
+ # - [Int] order The order this merge tag should be displayed in - this will cause existing values to be reset so this fits
890
+ # - [String] default_value optional the default value for the field. See subscribe() for formatting info. Defaults to blank - max 255 bytes
891
+ # - [String] helptext optional the help text to be used with some newer forms. Defaults to blank - max 255 bytes
892
+ # - [Array] choices optional kind of - an array of strings to use as the choices for radio and dropdown type fields
893
+ # - [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.
894
+ # - [String] phoneformat optional "US" is the default - any other value will cause them to be unformatted (international)
895
+ # - [String] defaultcountry optional the <a href="http://www.iso.org/iso/english_country_names_and_code_elements" target="_blank">ISO 3166 2 digit character code</a> for the default country. Defaults to "US". Anything unrecognized will be converted to the default.
896
+ # @return [Hash] the full data for the new merge var, just like merge-vars returns
897
+ # - [String] name Name/description of the merge field
898
+ # - [Bool] req Denotes whether the field is required (true) or not (false)
899
+ # - [String] field_type The "data type" of this merge var. One of: email, text, number, radio, dropdown, date, address, phone, url, imageurl
900
+ # - [Bool] public Whether or not this field is visible to list subscribers
901
+ # - [Bool] show Whether the field is displayed in thelist dashboard
902
+ # - [String] order The order this field displays in on forms
903
+ # - [String] default The default value for this field
904
+ # - [String] helptext The helptext for this field
905
+ # - [String] size The width of the field to be used
906
+ # - [String] tag The merge tag that's used for forms and subscribe() and updateMember()
907
+ # - [Array] choices the options available for radio and dropdown field types
908
+ # - [Int] id an unchanging id for the merge var
909
+ def merge_var_add(id, tag, name, options=[])
910
+ _params = {:id => id, :tag => tag, :name => name, :options => options}
911
+ return @master.call 'lists/merge-var-add', _params
912
+ end
913
+
914
+ # 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.
915
+ # @param [String] id the list id to connect to. Get by calling lists()
916
+ # @param [String] tag The merge tag to delete
917
+ # @return [Hash] with a single entry:
918
+ # - [Bool] complete whether the call worked. reallistically this will always be true as errors will be thrown otherwise.
919
+ def merge_var_del(id, tag)
920
+ _params = {:id => id, :tag => tag}
921
+ return @master.call 'lists/merge-var-del', _params
922
+ end
923
+
924
+ # Completely resets all data stored in a merge var on a list. All data is removed and this action can not be undone.
925
+ # @param [String] id the list id to connect to. Get by calling lists()
926
+ # @param [String] tag The merge tag to reset
927
+ # @return [Hash] with a single entry:
928
+ # - [Bool] complete whether the call worked. reallistically this will always be true as errors will be thrown otherwise.
929
+ def merge_var_reset(id, tag)
930
+ _params = {:id => id, :tag => tag}
931
+ return @master.call 'lists/merge-var-reset', _params
932
+ end
933
+
934
+ # 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.
935
+ # @param [String] id the list id to connect to. Get by calling lists()
936
+ # @param [String] tag The merge tag to reset
937
+ # @param [String] value The value to set - see subscribe() for formatting. Must validate to something non-empty.
938
+ # @return [Hash] with a single entry:
939
+ # - [Bool] complete whether the call worked. reallistically this will always be true as errors will be thrown otherwise.
940
+ def merge_var_set(id, tag, value)
941
+ _params = {:id => id, :tag => tag, :value => value}
942
+ return @master.call 'lists/merge-var-set', _params
943
+ end
944
+
945
+ # Update most parameters for a merge tag on a given list. You cannot currently change the merge type
946
+ # @param [String] id the list id to connect to. Get by calling lists()
947
+ # @param [String] tag The merge tag to update
948
+ # @param [Hash] options The options to change for a merge var. See listMergeVarAdd() for valid options. "tag" and "name" may also be used here.
949
+ # @return [Hash] the full data for the new merge var, just like merge-vars returns
950
+ # - [String] name Name/description of the merge field
951
+ # - [Bool] req Denotes whether the field is required (true) or not (false)
952
+ # - [String] field_type The "data type" of this merge var. One of: email, text, number, radio, dropdown, date, address, phone, url, imageurl
953
+ # - [Bool] public Whether or not this field is visible to list subscribers
954
+ # - [Bool] show Whether the field is displayed in thelist dashboard
955
+ # - [String] order The order this field to displays in on forms
956
+ # - [String] default The default value for this field
957
+ # - [String] helptext The helptext for this field
958
+ # - [String] size The width of the field to be used
959
+ # - [String] tag The merge tag that's used for forms and subscribe() and updateMember()
960
+ # - [Array] choices the options available for radio and dropdown field types
961
+ # - [Int] id an unchanging id for the merge var
962
+ def merge_var_update(id, tag, options)
963
+ _params = {:id => id, :tag => tag, :options => options}
964
+ return @master.call 'lists/merge-var-update', _params
965
+ end
966
+
967
+ # Get the list of merge tags for a given list, including their name, tag, and required setting
968
+ # @param [Array] id the list ids to retrieve merge vars for. Get by calling lists() - max of 100
969
+ # @return [Hash] of data and success/error counts
970
+ # - [Int] success_count the number of subscribers successfully found on the list
971
+ # - [Int] error_count the number of subscribers who were not found on the list
972
+ # - [Array] data of structs for the merge tags on each list
973
+ # - [String] id the list id
974
+ # - [String] name the list name
975
+ # - [Array] merge_vars of structs for each merge var
976
+ # - [String] name Name of the merge field
977
+ # - [Bool] req Denotes whether the field is required (true) or not (false)
978
+ # - [String] field_type The "data type" of this merge var. One of: email, text, number, radio, dropdown, date, address, phone, url, imageurl
979
+ # - [Bool] public Whether or not this field is visible to list subscribers
980
+ # - [Bool] show Whether the list owner has this field displayed on their list dashboard
981
+ # - [String] order The order the list owner has set this field to display in
982
+ # - [String] default The default value the list owner has set for this field
983
+ # - [String] helptext The helptext for this field
984
+ # - [String] size The width of the field to be used
985
+ # - [String] tag The merge tag that's used for forms and listSubscribe() and listUpdateMember()
986
+ # - [Array] choices For radio and dropdown field types, an array of the options available
987
+ # - [Int] id an unchanging id for the merge var
988
+ # - [Array] errors of error structs
989
+ # - [String] id the passed list id that failed
990
+ # - [Int] code the resulting error code
991
+ # - [String] msg the resulting error message
992
+ def merge_vars(id)
993
+ _params = {:id => id}
994
+ return @master.call 'lists/merge-vars', _params
995
+ end
996
+
997
+ # 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.
998
+ # @param [String] id the list id to connect to. Get by calling lists()
999
+ # @param [String] name a unique name per list for the segment - 50 byte maximum length, anything longer will throw an error
1000
+ # @return [Hash] with a single entry:
1001
+ # - [Int] id the id of the new segment, otherwise an error will be thrown.
1002
+ def static_segment_add(id, name)
1003
+ _params = {:id => id, :name => name}
1004
+ return @master.call 'lists/static-segment-add', _params
1005
+ end
1006
+
1007
+ # Delete a static segment. Note that this will, of course, remove any member affiliations with the segment
1008
+ # @param [String] id the list id to connect to. Get by calling lists()
1009
+ # @param [Int] seg_id the id of the static segment to delete - get from listStaticSegments()
1010
+ # @return [Hash] with a single entry:
1011
+ # - [Bool] complete whether the call worked. reallistically this will always be true as errors will be thrown otherwise.
1012
+ def static_segment_del(id, seg_id)
1013
+ _params = {:id => id, :seg_id => seg_id}
1014
+ return @master.call 'lists/static-segment-del', _params
1015
+ end
1016
+
1017
+ # 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!
1018
+ # @param [String] id the list id to connect to. Get by calling lists()
1019
+ # @param [Int] seg_id the id of the static segment to modify - get from listStaticSegments()
1020
+ # @param [Array] batch an array of structs for each address using the following keys:
1021
+ # - [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.
1022
+ # - [String] email an email address
1023
+ # - [String] euid the unique id for an email address (not list related) - the email "id" returned from listMemberInfo, Webhooks, Campaigns, etc.
1024
+ # - [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
1025
+ # @return [Hash] an array with the results of the operation
1026
+ # - [Int] success_count the total number of successful updates (will include members already in the segment)
1027
+ # - [Array] errors structs for each error including:
1028
+ # - [String] email whatever was passed in the email parameter
1029
+ # - [String] email the email address added
1030
+ # - [String] euid the email unique id
1031
+ # - [String] leid the list member's truly unique id
1032
+ # - [String] code the error code
1033
+ # - [String] error the full error message
1034
+ def static_segment_members_add(id, seg_id, batch)
1035
+ _params = {:id => id, :seg_id => seg_id, :batch => batch}
1036
+ return @master.call 'lists/static-segment-members-add', _params
1037
+ end
1038
+
1039
+ # 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!
1040
+ # @param [String] id the list id to connect to. Get by calling lists()
1041
+ # @param [Int] seg_id the id of the static segment to delete - get from listStaticSegments()
1042
+ # @param [Array] batch an array of structs for each address using the following keys:
1043
+ # - [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.
1044
+ # - [String] email an email address
1045
+ # - [String] euid the unique id for an email address (not list related) - the email "id" returned from listMemberInfo, Webhooks, Campaigns, etc.
1046
+ # - [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
1047
+ # @return [Hash] an array with the results of the operation
1048
+ # - [Int] success_count the total number of successful removals
1049
+ # - [Int] error_count the total number of unsuccessful removals
1050
+ # - [Array] errors structs for each error including:
1051
+ # - [String] email whatever was passed in the email parameter
1052
+ # - [String] email the email address added
1053
+ # - [String] euid the email unique id
1054
+ # - [String] leid the list member's truly unique id
1055
+ # - [String] code the error code
1056
+ # - [String] error the full error message
1057
+ def static_segment_members_del(id, seg_id, batch)
1058
+ _params = {:id => id, :seg_id => seg_id, :batch => batch}
1059
+ return @master.call 'lists/static-segment-members-del', _params
1060
+ end
1061
+
1062
+ # Resets a static segment - removes <strong>all</strong> members from the static segment. Note: does not actually affect list member data
1063
+ # @param [String] id the list id to connect to. Get by calling lists()
1064
+ # @param [Int] seg_id the id of the static segment to reset - get from listStaticSegments()
1065
+ # @return [Hash] with a single entry:
1066
+ # - [Bool] complete whether the call worked. reallistically this will always be true as errors will be thrown otherwise.
1067
+ def static_segment_reset(id, seg_id)
1068
+ _params = {:id => id, :seg_id => seg_id}
1069
+ return @master.call 'lists/static-segment-reset', _params
1070
+ end
1071
+
1072
+ # Retrieve all of the Static Segments for a list.
1073
+ # @param [String] id the list id to connect to. Get by calling lists()
1074
+ # @return [Array] an of structs with data for each static segment
1075
+ # - [Int] id the id of the segment
1076
+ # - [String] name the name for the segment
1077
+ # - [Int] member_count the total number of subscribed members currently in a segment
1078
+ # - [String] created_date the date/time the segment was created
1079
+ # - [String] last_update the date/time the segment was last updated (add or del)
1080
+ # - [String] last_reset the date/time the segment was last reset (ie had all members cleared from it)
1081
+ def static_segments(id)
1082
+ _params = {:id => id}
1083
+ return @master.call 'lists/static-segments', _params
1084
+ end
1085
+
1086
+ # 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!
1087
+ # @param [String] id the list id to connect to. Get by calling lists/list()
1088
+ # @param [Hash] email a struct with one of the following keys - failing to provide anything will produce an error relating to the email address. Providing multiples and will use the first we see in this same order.
1089
+ # - [String] email an email address - for new subscribers obviously this should be used
1090
+ # - [String] euid the unique id for an email address (not list related) - the email "id" returned from listMemberInfo, Webhooks, Campaigns, etc.
1091
+ # - [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
1092
+ # @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:
1093
+ # - [String] new-email set this to change the email address. This is only respected on calls using update_existing or when passed to listUpdateMember().
1094
+ # - [Array] groupings of Interest Grouping structs. Each should contain:
1095
+ # - [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)
1096
+ # - [String] name Grouping "name" from lists/interest-groupings (either this or id must be present)
1097
+ # - [Array] groups an array of valid group names for this grouping.
1098
+ # - [String] optin_ip Set the Opt-in IP field. <em>Abusing this may cause your account to be suspended.</em> We do validate this and it must not be a private IP address.
1099
+ # - [String] optin_time Set the Opt-in Time field. <em>Abusing this may cause your account to be suspended.</em> We do validate this and it must be a valid date. Use - 24 hour format in <strong>GMT</strong>, eg "2013-12-30 20:30:00" to be safe. Generally, though, anything strtotime() understands we'll understand - <a href="http://us2.php.net/strtotime" target="_blank">http://us2.php.net/strtotime</a>
1100
+ # - [Hash] mc_location Set the member's geographic location either by optin_ip or geo data.
1101
+ # - [String] latitude use the specified latitude (longitude must exist for this to work)
1102
+ # - [String] longitude use the specified longitude (latitude must exist for this to work)
1103
+ # - [String] anything if this (or any other key exists here) we'll try to use the optin ip. NOTE - this will slow down each subscribe call a bit, especially for lat/lng pairs in sparsely populated areas. Currently our automated background processes can and will overwrite this based on opens and clicks.
1104
+ # - [String] mc_language Set the member's language preference. Supported codes are fully case-sensitive and can be found <a href="http://kb.mailchimp.com/article/can-i-see-what-languages-my-subscribers-use#code" target="_new">here</a>.
1105
+ # - [Array] mc_notes of structs for managing notes - it may contain:
1106
+ # - [String] note the note to set. this is required unless you're deleting a note
1107
+ # - [Int] id the note id to operate on. not including this (or using an invalid id) causes a new note to be added
1108
+ # - [String] action if the "id" key exists and is valid, an "update" key may be set to "append" (default), "prepend", "replace", or "delete" to handle how we should update existing notes. "delete", obviously, will only work with a valid "id" - passing that along with "note" and an invalid "id" is wrong and will be ignored.
1109
+ # @param [String] email_type optional email type preference for the email (html or text - defaults to html)
1110
+ # @param [Bool] double_optin optional flag to control whether a double opt-in confirmation message is sent, defaults to true. <em>Abusing this may cause your account to be suspended.</em>
1111
+ # @param [Bool] update_existing optional flag to control whether existing subscribers should be updated instead of throwing an error, defaults to false
1112
+ # @param [Bool] replace_interests optional flag to determine whether we replace the interest groups with the groups provided or we add the provided groups to the member's interest groups (optional, defaults to true)
1113
+ # @param [Bool] send_welcome optional if your double_optin is false and this is true, we will send your lists Welcome Email if this subscribe succeeds - this will *not* fire if we end up updating an existing subscriber. If double_optin is true, this has no effect. defaults to false.
1114
+ # @return [Hash] the ids for this subscriber
1115
+ # - [String] email the email address added
1116
+ # - [String] euid the email unique id
1117
+ # - [String] leid the list member's truly unique id
1118
+ def subscribe(id, email, merge_vars=nil, email_type='html', double_optin=true, update_existing=false, replace_interests=true, send_welcome=false)
1119
+ _params = {:id => id, :email => email, :merge_vars => merge_vars, :email_type => email_type, :double_optin => double_optin, :update_existing => update_existing, :replace_interests => replace_interests, :send_welcome => send_welcome}
1120
+ return @master.call 'lists/subscribe', _params
1121
+ end
1122
+
1123
+ # Unsubscribe the given email address from the list
1124
+ # @param [String] id the list id to connect to. Get by calling lists()
1125
+ # @param [Hash] email a struct with one of the following keys - failing to provide anything will produce an error relating to the email address. Providing multiples and will use the first we see in this same order.
1126
+ # - [String] email an email address
1127
+ # - [String] euid the unique id for an email address (not list related) - the email "id" returned from listMemberInfo, Webhooks, Campaigns, etc.
1128
+ # - [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
1129
+ # @param [Boolean] delete_member flag to completely delete the member from your list instead of just unsubscribing, default to false
1130
+ # @param [Boolean] send_goodbye flag to send the goodbye email to the email address, defaults to true
1131
+ # @param [Boolean] send_notify flag to send the unsubscribe notification email to the address defined in the list email notification settings, defaults to true
1132
+ # @return [Hash] with a single entry:
1133
+ # - [Bool] complete whether the call worked. reallistically this will always be true as errors will be thrown otherwise.
1134
+ def unsubscribe(id, email, delete_member=false, send_goodbye=true, send_notify=true)
1135
+ _params = {:id => id, :email => email, :delete_member => delete_member, :send_goodbye => send_goodbye, :send_notify => send_notify}
1136
+ return @master.call 'lists/unsubscribe', _params
1137
+ end
1138
+
1139
+ # 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 listBatchSubscribe() with the update_existing and possible replace_interests parameter.
1140
+ # @param [String] id the list id to connect to. Get by calling lists()
1141
+ # @param [Hash] email a struct with one of the following keys - failing to provide anything will produce an error relating to the email address. Providing multiples and will use the first we see in this same order.
1142
+ # - [String] email an email address
1143
+ # - [String] euid the unique id for an email address (not list related) - the email "id" returned from listMemberInfo, Webhooks, Campaigns, etc.
1144
+ # - [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
1145
+ # @param [Array] merge_vars array of new field values to update the member with. See merge_vars in listSubscribe() for details.
1146
+ # @param [String] email_type change the email type preference for the member ("html" or "text"). Leave blank to keep the existing preference (optional)
1147
+ # @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)
1148
+ # @return [Hash] the ids for this subscriber
1149
+ # - [String] email the email address added
1150
+ # - [String] euid the email unique id
1151
+ # - [String] leid the list member's truly unique id
1152
+ def update_member(id, email, merge_vars, email_type='', replace_interests=true)
1153
+ _params = {:id => id, :email => email, :merge_vars => merge_vars, :email_type => email_type, :replace_interests => replace_interests}
1154
+ return @master.call 'lists/update-member', _params
1155
+ end
1156
+
1157
+ # Add a new Webhook URL for the given list
1158
+ # @param [String] id the list id to connect to. Get by calling lists()
1159
+ # @param [String] url a valid URL for the Webhook - it will be validated. note that a url may only exist on a list once.
1160
+ # @param [Hash] actions optional a hash of actions to fire this Webhook for
1161
+ # - [Bool] subscribe optional as subscribes occur, defaults to true
1162
+ # - [Bool] unsubscribe optional as subscribes occur, defaults to true
1163
+ # - [Bool] profile optional as profile updates occur, defaults to true
1164
+ # - [Bool] cleaned optional as emails are cleaned from the list, defaults to true
1165
+ # - [Bool] upemail optional when subscribers change their email address, defaults to true
1166
+ # - [Bool] campaign option when a campaign is sent or canceled, defaults to true
1167
+ # @param [Hash] sources optional sources to fire this Webhook for
1168
+ # - [Bool] user optional user/subscriber initiated actions, defaults to true
1169
+ # - [Bool] admin optional admin actions in our web app, defaults to true
1170
+ # - [Bool] api optional actions that happen via API calls, defaults to false
1171
+ # @return [Hash] with a single entry:
1172
+ # - [Int] id the id of the new webhook, otherwise an error will be thrown.
1173
+ def webhook_add(id, url, actions=[], sources=[])
1174
+ _params = {:id => id, :url => url, :actions => actions, :sources => sources}
1175
+ return @master.call 'lists/webhook-add', _params
1176
+ end
1177
+
1178
+ # Delete an existing Webhook URL from a given list
1179
+ # @param [String] id the list id to connect to. Get by calling lists()
1180
+ # @param [String] url the URL of a Webhook on this list
1181
+ # @return [Hash] with a single entry:
1182
+ # - [Bool] complete whether the call worked. reallistically this will always be true as errors will be thrown otherwise.
1183
+ def webhook_del(id, url)
1184
+ _params = {:id => id, :url => url}
1185
+ return @master.call 'lists/webhook-del', _params
1186
+ end
1187
+
1188
+ # Return the Webhooks configured for the given list
1189
+ # @param [String] id the list id to connect to. Get by calling lists()
1190
+ # @return [Array] of structs for each webhook
1191
+ # - [String] url the URL for this Webhook
1192
+ # - [Hash] actions the possible actions and whether they are enabled
1193
+ # - [Bool] subscribe triggered when subscribes happen
1194
+ # - [Bool] unsubscribe triggered when unsubscribes happen
1195
+ # - [Bool] profile triggered when profile updates happen
1196
+ # - [Bool] cleaned triggered when a subscriber is cleaned (bounced) from a list
1197
+ # - [Bool] upemail triggered when a subscriber's email address is changed
1198
+ # - [Bool] campaign triggered when a campaign is sent or canceled
1199
+ # - [Hash] sources the possible sources and whether they are enabled
1200
+ # - [Bool] user whether user/subscriber triggered actions are returned
1201
+ # - [Bool] admin whether admin (manual, in-app) triggered actions are returned
1202
+ # - [Bool] api whether api triggered actions are returned
1203
+ def webhooks(id)
1204
+ _params = {:id => id}
1205
+ return @master.call 'lists/webhooks', _params
1206
+ end
1207
+
1208
+ # Retrieve all of the lists defined for your user account
1209
+ # @param [Hash] filters filters to apply to this query - all are optional:
1210
+ # - [String] list_id optional - return a single list using a known list_id. Accepts multiples separated by commas when not using exact matching
1211
+ # - [String] list_name optional - only lists that match this name
1212
+ # - [String] from_name optional - only lists that have a default from name matching this
1213
+ # - [String] from_email optional - only lists that have a default from email matching this
1214
+ # - [String] from_subject optional - only lists that have a default from email matching this
1215
+ # - [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"
1216
+ # - [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"
1217
+ # - [Boolean] exact optional - flag for whether to filter on exact values when filtering, or search within content for filter values - defaults to true
1218
+ # @param [Int] start optional - control paging of lists, start results at this list #, defaults to 1st page of data (page 0)
1219
+ # @param [Int] limit optional - control paging of lists, number of lists to return with each call, defaults to 25 (max=100)
1220
+ # @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.
1221
+ # @param [String] sort_dir optional - "DESC" for descending (default), "ASC" for Ascending. Invalid values will fall back on "created" - case insensitive. Note: to get the exact display order as the web app you'd use "web" and "ASC"
1222
+ # @return [Hash] result of the operation including valid data and any errors
1223
+ # - [Int] total the total number of lists which matched the provided filters
1224
+ # - [Array] data structs for the lists which matched the provided filters, including the following
1225
+ # - [String] id The list id for this list. This will be used for all other list management functions.
1226
+ # - [Int] web_id The list id used in our web app, allows you to create a link directly to it
1227
+ # - [String] name The name of the list.
1228
+ # - [String] date_created The date that this list was created.
1229
+ # - [Boolean] email_type_option Whether or not the List supports multiple formats for emails or just HTML
1230
+ # - [Boolean] use_awesomebar Whether or not campaigns for this list use the Awesome Bar in archives by default
1231
+ # - [String] default_from_name Default From Name for campaigns using this list
1232
+ # - [String] default_from_email Default From Email for campaigns using this list
1233
+ # - [String] default_subject Default Subject Line for campaigns using this list
1234
+ # - [String] default_language Default Language for this list's forms
1235
+ # - [Double] list_rating An auto-generated activity score for the list (0 - 5)
1236
+ # - [String] subscribe_url_short Our eepurl shortened version of this list's subscribe form (will not change)
1237
+ # - [String] subscribe_url_long The full version of this list's subscribe form (host will vary)
1238
+ # - [String] beamer_address The email address to use for this list's <a href="http://kb.mailchimp.com/article/how-do-i-import-a-campaign-via-email-email-beamer/">Email Beamer</a>
1239
+ # - [String] visibility Whether this list is Public (pub) or Private (prv). Used internally for projects like <a href="http://blog.mailchimp.com/introducing-wavelength/" target="_blank">Wavelength</a>
1240
+ # - [Hash] stats various stats and counts for the list - many of these are cached for at least 5 minutes
1241
+ # - [Double] member_count The number of active members in the given list.
1242
+ # - [Double] unsubscribe_count The number of members who have unsubscribed from the given list.
1243
+ # - [Double] cleaned_count The number of members cleaned from the given list.
1244
+ # - [Double] member_count_since_send The number of active members in the given list since the last campaign was sent
1245
+ # - [Double] unsubscribe_count_since_send The number of members who have unsubscribed from the given list since the last campaign was sent
1246
+ # - [Double] cleaned_count_since_send The number of members cleaned from the given list since the last campaign was sent
1247
+ # - [Double] campaign_count The number of campaigns in any status that use this list
1248
+ # - [Double] grouping_count The number of Interest Groupings for this list
1249
+ # - [Double] group_count The number of Interest Groups (regardless of grouping) for this list
1250
+ # - [Double] merge_var_count The number of merge vars for this list (not including the required EMAIL one)
1251
+ # - [Double] avg_sub_rate the average number of subscribe per month for the list (empty value if we haven't calculated this yet)
1252
+ # - [Double] avg_unsub_rate the average number of unsubscribe per month for the list (empty value if we haven't calculated this yet)
1253
+ # - [Double] target_sub_rate the target subscription rate for the list to keep it growing (empty value if we haven't calculated this yet)
1254
+ # - [Double] open_rate the average open rate per campaign for the list (empty value if we haven't calculated this yet)
1255
+ # - [Double] click_rate the average click rate per campaign for the list (empty value if we haven't calculated this yet)
1256
+ # - [Array] modules Any list specific modules installed for this list (example is SocialPro)
1257
+ # - [Array] errors structs of any errors found while loading lists - usually just from providing invalid list ids
1258
+ # - [String] param the data that caused the failure
1259
+ # - [Int] code the error code
1260
+ # - [Int] error the error message
1261
+ def list(filters=[], start=0, limit=25, sort_field='created', sort_dir='DESC')
1262
+ _params = {:filters => filters, :start => start, :limit => limit, :sort_field => sort_field, :sort_dir => sort_dir}
1263
+ return @master.call 'lists/list', _params
1264
+ end
1265
+
1266
+ end
1267
+ class Campaigns
1268
+ attr_accessor :master
1269
+
1270
+ def initialize(master)
1271
+ @master = master
1272
+ end
1273
+
1274
+ # 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
1275
+ # @param [String] cid the campaign id to get content for (can be gathered using campaign/list())
1276
+ # @param [Hash] options various options to control this call
1277
+ # - [String] view optional one of "archive" (default), "preview" (like our popup-preview) or "raw"
1278
+ # - [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. Providing multiples and will use the first we see in this same order.
1279
+ # - [String] email an email address
1280
+ # - [String] euid the unique id for an email address (not list related) - the email "id" returned from listMemberInfo, Webhooks, Campaigns, etc.
1281
+ # - [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
1282
+ # @return [Hash] containing all content for the campaign
1283
+ # - [String] html The HTML content used for the campaign with merge tags intact
1284
+ # - [String] text The Text content used for the campaign with merge tags intact
1285
+ def content(cid, options=[])
1286
+ _params = {:cid => cid, :options => options}
1287
+ return @master.call 'campaigns/content', _params
1288
+ end
1289
+
1290
+ # Create a new draft campaign to send. You <strong>can not</strong> have more than 32,000 campaigns in your account.
1291
+ # @param [String] type the Campaign Type to create - one of "regular", "plaintext", "absplit", "rss", "auto"
1292
+ # @param [Hash] options a struct of the standard options for this campaign :
1293
+ # - [String] list_id the list to send this campaign to- get lists using lists()
1294
+ # - [String] subject the subject line for your campaign message
1295
+ # - [String] from_email the From: email address for your campaign message
1296
+ # - [String] from_name the From: name for your campaign message (not an email address)
1297
+ # - [String] to_name the To: name recipients will see (not email address)
1298
+ # - [Int] template_id optional - use this user-created template to generate the HTML content of the campaign (takes precendence over other template options)
1299
+ # - [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)
1300
+ # - [Int] base_template_id optional - use this a base/start-from-scratch template to generate the HTML content of the campaign
1301
+ # - [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 setupsn
1302
+ # - [Hash] tracking optional - set which recipient actions will be tracked. Click tracking can not be disabled for Free accounts.
1303
+ # - [Bool] opens whether to track opens, defaults to true
1304
+ # - [Bool] html_clicks whether to track clicks in HTML content, defaults to true
1305
+ # - [Bool] text_clicks whether to track clicks in Text content, defaults to false
1306
+ # - [String] title optional - an internal name to use for this campaign. By default, the campaign subject will be used.
1307
+ # - [Boolean] authenticate optional - set to true to enable SenderID, DomainKeys, and DKIM authentication, defaults to false.
1308
+ # - [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)
1309
+ # - [String] google for Google Analytics tracking
1310
+ # - [String] clicktale for ClickTale tracking
1311
+ # - [String] gooal for Goo.al tracking
1312
+ # - [Boolean] auto_footer optional Whether or not we should auto-generate the footer for your content. Mostly useful for content from URLs or Imports
1313
+ # - [Boolean] inline_css optional Whether or not css should be automatically inlined when this campaign is sent, defaults to false.
1314
+ # - [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.
1315
+ # - [Boolean] auto_tweet optional If set, this campaign will be auto-tweeted when it is sent - defaults to false. Note that if a Twitter account isn't linked, this will be silently ignored.
1316
+ # - [Array] auto_fb_post optional If set, this campaign will be auto-posted to the page_ids contained in the array. If a Facebook account isn't linked or the account does not have permission to post to the page_ids requested, those failures will be silently ignored.
1317
+ # - [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".
1318
+ # - [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.
1319
+ # - [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
1320
+ # - [Array] crm_tracking optional If set, an array of structs to enable CRM tracking for:
1321
+ # - [Hash] salesforce optional Enable SalesForce push back
1322
+ # - [Bool] campaign optional - if true, create a Campaign object and update it with aggregate stats
1323
+ # - [Bool] notes optional - if true, attempt to update Contact notes based on email address
1324
+ # - [Hash] highrise optional Enable Highrise push back
1325
+ # - [Bool] campaign optional - if true, create a Kase object and update it with aggregate stats
1326
+ # - [Bool] notes optional - if true, attempt to update Contact notes based on email address
1327
+ # - [Hash] capsule optional Enable Capsule push back (only notes are supported)
1328
+ # - [Bool] notes optional - if true, attempt to update Contact notes based on email address
1329
+ # @param [Hash] content the content for this campaign - use a struct with the one of the following keys:
1330
+ # - [String] html for raw/pasted HTML content
1331
+ # - [Hash] sections when using a template instead of raw HTML, each key should be the unique mc:edit area name from the template.
1332
+ # - [String] text for the plain-text version
1333
+ # - [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
1334
+ # - [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
1335
+ # - [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
1336
+ # @param [Hash] segment_opts if you wish to do Segmentation with this campaign this array should contain: see campaignSegmentTest(). It's suggested that you test your options against campaignSegmentTest().
1337
+ # @param [Hash] type_opts various extra options based on the campaign type
1338
+ # - [Hash] rss For RSS Campaigns this, struct should contain:
1339
+ # - [String] url the URL to pull RSS content from - it will be verified and must exist
1340
+ # - [String] schedule optional one of "daily", "weekly", "monthly" - defaults to "daily"
1341
+ # - [String] schedule_hour optional an hour between 0 and 24 - default to 4 (4am <em>local time</em>) - applies to all schedule types
1342
+ # - [String] schedule_weekday optional for "weekly" only, a number specifying the day of the week to send: 0 (Sunday) - 6 (Saturday) - defaults to 1 (Monday)
1343
+ # - [String] schedule_monthday optional for "monthly" only, a number specifying the day of the month to send (1 - 28) or "last" for the last day of a given month. Defaults to the 1st day of the month
1344
+ # - [Hash] days optional used for "daily" schedules only, an array of the <a href="http://en.wikipedia.org/wiki/ISO-8601#Week_dates" target="_blank">ISO-8601 weekday numbers</a> to send on
1345
+ # - [Bool] 1 optional Monday, defaults to true
1346
+ # - [Bool] 2 optional Tuesday, defaults to true
1347
+ # - [Bool] 3 optional Wednesday, defaults to true
1348
+ # - [Bool] 4 optional Thursday, defaults to true
1349
+ # - [Bool] 5 optional Friday, defaults to true
1350
+ # - [Bool] 6 optional Saturday, defaults to true
1351
+ # - [Bool] 7 optional Sunday, defaults to true
1352
+ # - [Hash] absplit For A/B Split campaigns, this struct should contain:
1353
+ # - [String] split_test The values to segment based on. Currently, one of: "subject", "from_name", "schedule". NOTE, for "schedule", you will need to call campaignSchedule() separately!
1354
+ # - [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)
1355
+ # - [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.
1356
+ # - [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.
1357
+ # - [Int] split_size optional this is a percentage of what size the Campaign's List plus any segmentation options results in. "schedule" type forces 50%, all others default to 10%
1358
+ # - [String] from_name_a optional sort of, required when split_test is "from_name"
1359
+ # - [String] from_name_b optional sort of, required when split_test is "from_name"
1360
+ # - [String] from_email_a optional sort of, required when split_test is "from_name"
1361
+ # - [String] from_email_b optional sort of, required when split_test is "from_name"
1362
+ # - [String] subject_a optional sort of, required when split_test is "subject"
1363
+ # - [String] subject_b optional sort of, required when split_test is "subject"
1364
+ # - [Hash] auto For AutoResponder campaigns, this struct should contain:
1365
+ # - [String] offset-units one of "hourly", "day", "week", "month", "year" - required
1366
+ # - [String] offset-time optional, sort of - the number of units must be a number greater than 0 for signup based autoresponders, ignored for "hourly"
1367
+ # - [String] offset-dir either "before" or "after", ignored for "hourly"
1368
+ # - [String] event optional "signup" (default) to base this members added to a list, "date", "annual", or "birthday" to base this on merge field in the list, "campaignOpen" or "campaignClicka" to base this on any activity for a campaign, "campaignClicko" to base this on clicks on a specific URL in a campaign, "mergeChanged" to base this on a specific merge field being changed to a specific value
1369
+ # - [String] event-datemerge optional sort of, this is required if the event is "date", "annual", "birthday", or "mergeChanged"
1370
+ # - [String] campaign_id optional sort of, required for "campaignOpen", "campaignClicka", or "campaignClicko"
1371
+ # - [String] campaign_url optional sort of, required for "campaignClicko"
1372
+ # - [Int] schedule_hour The hour of the day - 24 hour format in GMT - the autoresponder should be triggered, ignored for "hourly"
1373
+ # - [Boolean] use_import_time whether or not imported subscribers (ie, <em>any</em> non-double optin subscribers) will receive
1374
+ # - [Hash] days optional used for "daily" schedules only, an array of the <a href="http://en.wikipedia.org/wiki/ISO-8601#Week_dates" target="_blank">ISO-8601 weekday numbers</a> to send on<
1375
+ # - [Bool] 1 optional Monday, defaults to true
1376
+ # - [Bool] 2 optional Tuesday, defaults to true
1377
+ # - [Bool] 3 optional Wednesday, defaults to true
1378
+ # - [Bool] 4 optional Thursday, defaults to true
1379
+ # - [Bool] 5 optional Friday, defaults to true
1380
+ # - [Bool] 6 optional Saturday, defaults to true
1381
+ # - [Bool] 7 optional Sunday, defaults to true
1382
+ # @return [Hash] the new campaign's details - will return same data as single campaign from campaigns/list()
1383
+ def create(type, options, content, segment_opts=nil, type_opts=nil)
1384
+ _params = {:type => type, :options => options, :content => content, :segment_opts => segment_opts, :type_opts => type_opts}
1385
+ return @master.call 'campaigns/create', _params
1386
+ end
1387
+
1388
+ # Delete a campaign. Seriously, "poof, gone!" - be careful! Seriously, no one can undelete these.
1389
+ # @param [String] cid the Campaign Id to delete
1390
+ # @return [Hash] with a single entry:
1391
+ # - [Bool] complete whether the call worked. reallistically this will always be true as errors will be thrown otherwise.
1392
+ def delete(cid)
1393
+ _params = {:cid => cid}
1394
+ return @master.call 'campaigns/delete', _params
1395
+ end
1396
+
1397
+ # Get the list of campaigns and their details matching the specified filters
1398
+ # @param [Array] filters a hash of filters to apply to this query - all are optional:
1399
+ # - [String] campaign_id optional - return the campaign using a know campaign_id. Accepts multiples separated by commas when not using exact matching.
1400
+ # - [String] parent_id optional - return the child campaigns using a known parent campaign_id. Accepts multiples separated by commas when not using exact matching.
1401
+ # - [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.
1402
+ # - [Int] folder_id optional - only show campaigns from this folder id - get folders using campaignFolders(). Accepts multiples separated by commas when not using exact matching.
1403
+ # - [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.
1404
+ # - [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.
1405
+ # - [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.
1406
+ # - [String] from_name optional - only show campaigns that have this "From Name"
1407
+ # - [String] from_email optional - only show campaigns that have this "Reply-to Email"
1408
+ # - [String] title optional - only show campaigns that have this title
1409
+ # - [String] subject optional - only show campaigns that have this subject
1410
+ # - [String] sendtime_start optional - only show campaigns that have been sent since this date/time (in GMT) - - 24 hour format in <strong>GMT</strong>, eg "2013-12-30 20:30:00" - if this is invalid the whole call fails
1411
+ # - [String] sendtime_end optional - only show campaigns that have been sent before this date/time (in GMT) - - 24 hour format in <strong>GMT</strong>, eg "2013-12-30 20:30:00" - if this is invalid the whole call fails
1412
+ # - [Boolean] uses_segment - whether to return just campaigns with or without segments
1413
+ # - [Boolean] exact optional - flag for whether to filter on exact values when filtering, or search within content for filter values - defaults to true. Using this disables the use of any filters that accept multiples.
1414
+ # @param [Int] start optional - control paging of campaigns, start results at this campaign #, defaults to 1st page of data (page 0)
1415
+ # @param [Int] limit optional - control paging of campaigns, number of campaigns to return with each call, defaults to 25 (max=1000)
1416
+ # @param [String] sort_field optional - one of "create_time", "send_time", "title", "subject" . Invalid values will fall back on "create_time" - case insensitive.
1417
+ # @param [String] sort_dir optional - "DESC" for descending (default), "ASC" for Ascending. Invalid values will fall back on "DESC" - case insensitive.
1418
+ # @return [Hash] containing a count of all matching campaigns, the specific ones for the current page, and any errors from the filters provided
1419
+ # - [Int] total the total number of campaigns matching the filters passed in
1420
+ # - [Array] data structs for each campaign being returned
1421
+ # - [String] id Campaign Id (used for all other campaign functions)
1422
+ # - [Int] web_id The Campaign id used in our web app, allows you to create a link directly to it
1423
+ # - [String] list_id The List used for this campaign
1424
+ # - [Int] folder_id The Folder this campaign is in
1425
+ # - [Int] template_id The Template this campaign uses
1426
+ # - [String] content_type How the campaign's content is put together - one of 'template', 'html', 'url'
1427
+ # - [String] title Title of the campaign
1428
+ # - [String] type The type of campaign this is (regular,plaintext,absplit,rss,inspection,auto)
1429
+ # - [String] create_time Creation time for the campaign
1430
+ # - [String] send_time Send time for the campaign - also the scheduled time for scheduled campaigns.
1431
+ # - [Int] emails_sent Number of emails email was sent to
1432
+ # - [String] status Status of the given campaign (save,paused,schedule,sending,sent)
1433
+ # - [String] from_name From name of the given campaign
1434
+ # - [String] from_email Reply-to email of the given campaign
1435
+ # - [String] subject Subject of the given campaign
1436
+ # - [String] to_name Custom "To:" email string using merge variables
1437
+ # - [String] archive_url Archive link for the given campaign
1438
+ # - [Boolean] inline_css Whether or not the campaign content's css was auto-inlined
1439
+ # - [String] analytics Either "google" if enabled or "N" if disabled
1440
+ # - [String] analytics_tag The name/tag the campaign's links were tagged with if analytics were enabled.
1441
+ # - [Boolean] authenticate Whether or not the campaign was authenticated
1442
+ # - [Boolean] ecomm360 Whether or not ecomm360 tracking was appended to links
1443
+ # - [Boolean] auto_tweet Whether or not the campaign was auto tweeted after sending
1444
+ # - [String] auto_fb_post A comma delimited list of Facebook Profile/Page Ids the campaign was posted to after sending. If not used, blank.
1445
+ # - [Boolean] auto_footer Whether or not the auto_footer was manually turned on
1446
+ # - [Boolean] timewarp Whether or not the campaign used Timewarp
1447
+ # - [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
1448
+ # - [String] parent_id the unique id of the parent campaign (currently only valid for rss children)
1449
+ # - [Hash] tracking the various tracking options used
1450
+ # - [Boolean] html_clicks whether or not tracking for html clicks was enabled.
1451
+ # - [Boolean] text_clicks whether or not tracking for text clicks was enabled.
1452
+ # - [Boolean] opens whether or not opens tracking was enabled.
1453
+ # - [String] segment_text a string marked-up with HTML explaining the segment used for the campaign in plain English
1454
+ # - [Array] segment_opts the segment used for the campaign - can be passed to campaigns/segment-test or campaigns/create
1455
+ # - [Hash] type_opts the type-specific options for the campaign - can be passed to campaigns/create
1456
+ # - [Int] comments_total total number of comments left on this campaign
1457
+ # - [Int] comments_unread total number of unread comments for this campaign based on the login the apikey belongs to
1458
+ # - [Hash] summary if available, the basic aggregate stats returned by reports/summary
1459
+ # - [Array] errors structs of any errors found while loading lists - usually just from providing invalid list ids
1460
+ # - [String] filter the filter that caused the failure
1461
+ # - [String] value the filter value that caused the failure
1462
+ # - [Int] code the error code
1463
+ # - [Int] error the error message
1464
+ def list(filters=[], start=0, limit=25, sort_field='create_time', sort_dir='DESC')
1465
+ _params = {:filters => filters, :start => start, :limit => limit, :sort_field => sort_field, :sort_dir => sort_dir}
1466
+ return @master.call 'campaigns/list', _params
1467
+ end
1468
+
1469
+ # Pause an AutoResponder or RSS campaign from sending
1470
+ # @param [String] cid the id of the campaign to pause
1471
+ # @return [Hash] with a single entry:
1472
+ # - [Bool] complete whether the call worked. reallistically this will always be true as errors will be thrown otherwise.
1473
+ def pause(cid)
1474
+ _params = {:cid => cid}
1475
+ return @master.call 'campaigns/pause', _params
1476
+ end
1477
+
1478
+ # Returns information on whether a campaign is ready to send and possible issues we may have detected with it - very similar to the confirmation step in the app.
1479
+ # @param [String] cid the Campaign Id to replicate
1480
+ # @return [Hash] the matching campaign's details - will return same data as single campaign from campaigns/list()
1481
+ def ready(cid)
1482
+ _params = {:cid => cid}
1483
+ return @master.call 'campaigns/ready', _params
1484
+ end
1485
+
1486
+ # Replicate a campaign.
1487
+ # @param [String] cid the Campaign Id to replicate
1488
+ # @return [Hash] the matching campaign's details - will return same data as single campaign from campaigns/list()
1489
+ def replicate(cid)
1490
+ _params = {:cid => cid}
1491
+ return @master.call 'campaigns/replicate', _params
1492
+ end
1493
+
1494
+ # Resume sending an AutoResponder or RSS campaign
1495
+ # @param [String] cid the id of the campaign to pause
1496
+ # @return [Hash] with a single entry:
1497
+ # - [Bool] complete whether the call worked. reallistically this will always be true as errors will be thrown otherwise.
1498
+ def resume(cid)
1499
+ _params = {:cid => cid}
1500
+ return @master.call 'campaigns/resume', _params
1501
+ end
1502
+
1503
+ # Schedule a campaign to be sent in the future
1504
+ # @param [String] cid the id of the campaign to schedule
1505
+ # @param [String] schedule_time the time to schedule the campaign. For A/B Split "schedule" campaigns, the time for Group A - 24 hour format in <strong>GMT</strong>, eg "2013-12-30 20:30:00"
1506
+ # @param [String] schedule_time_b optional -the time to schedule Group B of an A/B Split "schedule" campaign - 24 hour format in <strong>GMT</strong>, eg "2013-12-30 20:30:00"
1507
+ # @return [Hash] with a single entry:
1508
+ # - [Bool] complete whether the call worked. reallistically this will always be true as errors will be thrown otherwise.
1509
+ def schedule(cid, schedule_time, schedule_time_b=nil)
1510
+ _params = {:cid => cid, :schedule_time => schedule_time, :schedule_time_b => schedule_time_b}
1511
+ return @master.call 'campaigns/schedule', _params
1512
+ end
1513
+
1514
+ # Schedule a campaign to be sent in batches sometime in the future. Only valid for "regular" campaigns
1515
+ # @param [String] cid the id of the campaign to schedule
1516
+ # @param [String] schedule_time the time to schedule the campaign.
1517
+ # @param [Int] num_batches optional - the number of batches between 2 and 26 to send. defaults to 2
1518
+ # @param [Int] stagger_mins optional - the number of minutes between each batch - 5, 10, 15, 20, 25, 30, or 60. defaults to 5
1519
+ # @return [Hash] with a single entry:
1520
+ # - [Bool] complete whether the call worked. reallistically this will always be true as errors will be thrown otherwise.
1521
+ def schedule_batch(cid, schedule_time, num_batches=2, stagger_mins=5)
1522
+ _params = {:cid => cid, :schedule_time => schedule_time, :num_batches => num_batches, :stagger_mins => stagger_mins}
1523
+ return @master.call 'campaigns/schedule-batch', _params
1524
+ end
1525
+
1526
+ # Allows one to test their segmentation rules before creating a campaign using them
1527
+ # @param [String] list_id the list to test segmentation on - get lists using lists()
1528
+ # @param [Hash] options with 2 keys:
1529
+ # - [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)
1530
+ # - [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:
1531
+ # @return [Hash] with a single entry:
1532
+ # - [Int] total The total number of subscribers matching your segmentation options
1533
+ def segment_test(list_id, options)
1534
+ _params = {:list_id => list_id, :options => options}
1535
+ return @master.call 'campaigns/segment-test', _params
1536
+ end
1537
+
1538
+ # Send a given campaign immediately. For RSS campaigns, this will "start" them.
1539
+ # @param [String] cid the id of the campaign to send
1540
+ # @return [Hash] with a single entry:
1541
+ # - [Bool] complete whether the call worked. reallistically this will always be true as errors will be thrown otherwise.
1542
+ def send(cid)
1543
+ _params = {:cid => cid}
1544
+ return @master.call 'campaigns/send', _params
1545
+ end
1546
+
1547
+ # Send a test of this campaign to the provided email addresses
1548
+ # @param [String] cid the id of the campaign to test
1549
+ # @param [Array] test_emails an array of email address to receive the test message
1550
+ # @param [String] send_type by default just html is sent - can be "html" or "text" send specify the format
1551
+ # @return [Hash] with a single entry:
1552
+ # - [Bool] complete whether the call worked. reallistically this will always be true as errors will be thrown otherwise.
1553
+ def send_test(cid, test_emails=[], send_type='html')
1554
+ _params = {:cid => cid, :test_emails => test_emails, :send_type => send_type}
1555
+ return @master.call 'campaigns/send-test', _params
1556
+ end
1557
+
1558
+ # 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.
1559
+ # @param [String] cid the campaign id to get content for (can be gathered using campaigns())
1560
+ # @return [Hash] content containing all content section for the campaign - section name are dependent upon the template used and thus can't be documented
1561
+ def template_content(cid)
1562
+ _params = {:cid => cid}
1563
+ return @master.call 'campaigns/template-content', _params
1564
+ end
1565
+
1566
+ # Unschedule a campaign that is scheduled to be sent in the future
1567
+ # @param [String] cid the id of the campaign to unschedule
1568
+ # @return [Hash] with a single entry:
1569
+ # - [Bool] complete whether the call worked. reallistically this will always be true as errors will be thrown otherwise.
1570
+ def unschedule(cid)
1571
+ _params = {:cid => cid}
1572
+ return @master.call 'campaigns/unschedule', _params
1573
+ end
1574
+
1575
+ # Update just about any setting besides type for a campaign that has <em>not</em> been sent. See campaign/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 campaign/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>
1576
+ # @param [String] cid the Campaign Id to update
1577
+ # @param [String] name the parameter name ( see campaign/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.
1578
+ # @param [Array] value an appropriate set of values for the parameter ( see campaign/create ). For additional parameters, this is the same value passed to them.
1579
+ # @return [Hash] updated campaign details and any errors
1580
+ # - [Hash] data the update campaign details - will return same data as single campaign from campaigns/list()
1581
+ # - [Array] errors for "options" only - structs containing:
1582
+ # - [Int] code the error code
1583
+ # - [String] message the full error message
1584
+ # - [String] name the parameter name that failed
1585
+ def update(cid, name, value)
1586
+ _params = {:cid => cid, :name => name, :value => value}
1587
+ return @master.call 'campaigns/update', _params
1588
+ end
1589
+
1590
+ end
1591
+ class Vip
1592
+ attr_accessor :master
1593
+
1594
+ def initialize(master)
1595
+ @master = master
1596
+ end
1597
+
1598
+ # Retrieve all Activity (opens/clicks) for VIPs over the past 10 days
1599
+ # @return [Array] structs for each activity recorded.
1600
+ # - [String] action The action taken - either "open" or "click"
1601
+ # - [String] timestamp The datetime the action occurred in GMT
1602
+ # - [String] url IF the action is a click, the url that was clicked
1603
+ # - [String] unique_id The campaign_id of the List the Member appears on
1604
+ # - [String] title The campaign title
1605
+ # - [String] list_name The name of the List the Member appears on
1606
+ # - [String] list_id The id of the List the Member appears on
1607
+ # - [String] email The email address of the member
1608
+ # - [String] fname IF a FNAME merge field exists on the list, that value for the member
1609
+ # - [String] lname IF a LNAME merge field exists on the list, that value for the member
1610
+ # - [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>
1611
+ # - [String] member_since the datetime the member was added and/or confirmed
1612
+ # - [Hash] geo the geographic information if we have it. including:
1613
+ # - [String] latitude the latitude
1614
+ # - [String] longitude the longitude
1615
+ # - [String] gmtoff GMT offset
1616
+ # - [String] dstoff GMT offset during daylight savings (if DST not observered, will be same as gmtoff
1617
+ # - [String] timezone the timezone we've place them in
1618
+ # - [String] cc 2 digit ISO-3166 country code
1619
+ # - [String] region generally state, province, or similar
1620
+ def activity()
1621
+ _params = {}
1622
+ return @master.call 'vip/activity', _params
1623
+ end
1624
+
1625
+ # Add VIPs (previously called Golden Monkeys)
1626
+ # @param [String] id the list id to connect to. Get by calling lists()
1627
+ # @param [Array] emails an array of up to 50 email address structs to add
1628
+ # - [String] email an email address
1629
+ # - [String] euid the unique id for an email address (not list related) - the email "id" returned from listMemberInfo, Webhooks, Campaigns, etc.
1630
+ # - [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
1631
+ # @return [Hash] of data and success/error counts
1632
+ # - [Int] success_count the number of successful adds
1633
+ # - [Int] error_count the number of unsuccessful adds
1634
+ # - [Array] errors array of error structs including:
1635
+ # - [Hash] email whatever was passed in the email parameter
1636
+ # - [String] email the email address added
1637
+ # - [String] euid the email unique id
1638
+ # - [String] leid the list member's truly unique id
1639
+ # - [String] code the error code
1640
+ # - [String] error the error message
1641
+ # - [Array] data array of structs for each member added
1642
+ # - [Hash] email whatever was passed in the email parameter
1643
+ # - [String] email the email address added
1644
+ # - [String] euid the email unique id
1645
+ # - [String] leid the list member's truly unique id
1646
+ def add(id, emails)
1647
+ _params = {:id => id, :emails => emails}
1648
+ return @master.call 'vip/add', _params
1649
+ end
1650
+
1651
+ # Remove VIPs - this does not affect list membership
1652
+ # @param [String] id the list id to connect to. Get by calling lists()
1653
+ # @param [Array] emails an array of up to 50 email address structs to remove
1654
+ # - [String] email an email address
1655
+ # - [String] euid the unique id for an email address (not list related) - the email "id" returned from listMemberInfo, Webhooks, Campaigns, etc.
1656
+ # - [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
1657
+ # @return [Hash] of data and success/error counts
1658
+ # - [Int] success_count the number of successful deletions
1659
+ # - [Int] error_count the number of unsuccessful deletions
1660
+ # - [Array] errors array of error structs including:
1661
+ # - [Hash] email whatever was passed in the email parameter
1662
+ # - [String] email the email address
1663
+ # - [String] euid the email unique id
1664
+ # - [String] leid the list member's truly unique id
1665
+ # - [String] code the error code
1666
+ # - [String] msg the error message
1667
+ # - [Array] data array of structs for each member deleted
1668
+ # - [Hash] email whatever was passed in the email parameter
1669
+ # - [String] email the email address
1670
+ # - [String] euid the email unique id
1671
+ # - [String] leid the list member's truly unique id
1672
+ def del(id, emails)
1673
+ _params = {:id => id, :emails => emails}
1674
+ return @master.call 'vip/del', _params
1675
+ end
1676
+
1677
+ # Retrieve all Golden Monkey(s) for an account
1678
+ # @return [Array] structs for each Golden Monkey, including:
1679
+ # - [String] list_id The id of the List the Member appears on
1680
+ # - [String] list_name The name of the List the Member appears on
1681
+ # - [String] email The email address of the member
1682
+ # - [String] fname IF a FNAME merge field exists on the list, that value for the member
1683
+ # - [String] lname IF a LNAME merge field exists on the list, that value for the member
1684
+ # - [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>
1685
+ # - [String] member_since the datetime the member was added and/or confirmed
1686
+ def members()
1687
+ _params = {}
1688
+ return @master.call 'vip/members', _params
1689
+ end
1690
+
1691
+ end
1692
+ class Reports
1693
+ attr_accessor :master
1694
+
1695
+ def initialize(master)
1696
+ @master = master
1697
+ end
1698
+
1699
+ # Get all email addresses that complained about a given campaign
1700
+ # @param [String] cid the campaign id to pull abuse reports for (can be gathered using campaigns())
1701
+ # @param [Hash] opts various options for controlling returned data
1702
+ # - [Int] start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
1703
+ # - [Int] limit optional for large data sets, the number of results to return - defaults to 25, upper limit set at 100
1704
+ # - [String] since optional pull only messages since this time - 24 hour format in <strong>GMT</strong>, eg "2013-12-30 20:30:00"
1705
+ # @return [Hash] abuse report data for this campaign
1706
+ # - [Int] total the total reports matched
1707
+ # - [Array] data a struct for the each report, including:
1708
+ # - [String] date date/time the abuse report was received and processed
1709
+ # - [String] member the email address that reported abuse - will only contain email if the list or member has been removed
1710
+ # - [String] type an internal type generally specifying the originating mail provider - may not be useful outside of filling report views
1711
+ def abuse(cid, opts=[])
1712
+ _params = {:cid => cid, :opts => opts}
1713
+ return @master.call 'reports/abuse', _params
1714
+ end
1715
+
1716
+ # 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
1717
+ # @param [String] cid the campaign id to pull advice text for (can be gathered using campaigns())
1718
+ # @return [Array] of structs for advice on the campaign's performance, each containing:
1719
+ # - [String] msg the advice message
1720
+ # - [String] type the "type" of the message. one of: negative, positive, or neutral
1721
+ def advice(cid)
1722
+ _params = {:cid => cid}
1723
+ return @master.call 'reports/advice', _params
1724
+ end
1725
+
1726
+ # 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
1727
+ # @param [String] cid the campaign id to pull bounces for (can be gathered using campaigns())
1728
+ # @param [Hash] email a struct with one of the following keys - failing to provide anything will produce an error relating to the email address. Providing multiples and will use the first we see in this same order.
1729
+ # - [String] email an email address - this is recommended for this method
1730
+ # - [String] euid the unique id for an email address (not list related) - the email "id" returned from listMemberInfo, Webhooks, Campaigns, etc.
1731
+ # - [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
1732
+ # @return [Hash] the full bounce message for this email+campaign along with some extra data.
1733
+ # - [String] date date the bounce was received and processed
1734
+ # - [Hash] member the member record as returned by lists/member-info
1735
+ # - [String] message the entire bounce message received
1736
+ def bounce_message(cid, email)
1737
+ _params = {:cid => cid, :email => email}
1738
+ return @master.call 'reports/bounce-message', _params
1739
+ end
1740
+
1741
+ # 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
1742
+ # @param [String] cid the campaign id to pull bounces for (can be gathered using campaigns())
1743
+ # @param [Hash] opts various options for controlling returned data
1744
+ # - [Int] start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
1745
+ # - [Int] limit optional for large data sets, the number of results to return - defaults to 25, upper limit set at 100
1746
+ # - [String] since optional pull only messages since this time - 24 hour format in <strong>GMT</strong>, eg "2013-12-30 20:30:00"
1747
+ # @return [Hash] data for the full bounce messages for this campaign
1748
+ # - [Int] total that total number of bounce messages for the campaign
1749
+ # - [Array] data structs containing the data for this page
1750
+ # - [String] date date the bounce was received and processed
1751
+ # - [Hash] member the member record as returned by lists/member-info
1752
+ # - [String] message the entire bounce message received
1753
+ def bounce_messages(cid, opts=[])
1754
+ _params = {:cid => cid, :opts => opts}
1755
+ return @master.call 'reports/bounce-messages', _params
1756
+ end
1757
+
1758
+ # Return the list of email addresses that clicked on a given url, and how many times they clicked
1759
+ # @param [String] cid the campaign id to get click stats for (can be gathered using campaigns())
1760
+ # @param [Int] tid the "tid" for the URL from reports/clicks
1761
+ # @param [Hash] opts various options for controlling returned data
1762
+ # - [Int] start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
1763
+ # - [Int] limit optional for large data sets, the number of results to return - defaults to 25, upper limit set at 100
1764
+ # - [String] sort_field optional the data to sort by - "clicked" (order clicks occurred, default) or "clicks" (total number of opens). Invalid fields will fall back on the default.
1765
+ # - [String] sort_dir optional the direct - ASC or DESC. defaults to ASC (case insensitive)
1766
+ # @return [Hash] containing the total records matched and the specific records for this page
1767
+ # - [Int] total the total number of records matched
1768
+ # - [Array] data structs for each email addresses that click the requested url
1769
+ # - [Hash] member the member record as returned by lists/member-info
1770
+ # - [Int] clicks Total number of times the URL was clicked by this email address
1771
+ def click_detail(cid, tid, opts=[])
1772
+ _params = {:cid => cid, :tid => tid, :opts => opts}
1773
+ return @master.call 'reports/click-detail', _params
1774
+ end
1775
+
1776
+ # The urls tracked and their click counts for a given campaign.
1777
+ # @param [String] cid the campaign id to pull stats for (can be gathered using campaigns())
1778
+ # @return [Hash] including:
1779
+ # - [Array] total structs for each url tracked for the full campaign
1780
+ # - [String] url the url being tracked - urls are tracked individually, so duplicates can exist with vastly different stats
1781
+ # - [Int] clicks Number of times the specific link was clicked
1782
+ # - [Double] clicks_percent the percentage of total clicks "clicks" represents
1783
+ # - [Int] unique Number of unique people who clicked on the specific link
1784
+ # - [Double] unique_percent the percentage of unique clicks "unique" represents
1785
+ # - [Int] tid the tracking id used in campaign links - used primarily for reports/click-activity. also can be used to order urls by the order they appeared in the campaign to recreate our heat map.
1786
+ # - [Array] a if this was an absplit campaign, stat structs for the a group
1787
+ # - [String] url the url being tracked - urls are tracked individually, so duplicates can exist with vastly different stats
1788
+ # - [Int] clicks Number of times the specific link was clicked
1789
+ # - [Double] clicks_percent the percentage of total clicks "clicks" represents
1790
+ # - [Int] unique Number of unique people who clicked on the specific link
1791
+ # - [Double] unique_percent the percentage of unique clicks "unique" represents
1792
+ # - [Int] tid the tracking id used in campaign links - used primarily for reports/click-activity. also can be used to order urls by the order they appeared in the campaign to recreate our heat map.
1793
+ # - [Array] b if this was an absplit campaign, stat structs for the b group
1794
+ # - [String] url the url being tracked - urls are tracked individually, so duplicates can exist with vastly different stats
1795
+ # - [Int] clicks Number of times the specific link was clicked
1796
+ # - [Double] clicks_percent the percentage of total clicks "clicks" represents
1797
+ # - [Int] unique Number of unique people who clicked on the specific link
1798
+ # - [Double] unique_percent the percentage of unique clicks "unique" represents
1799
+ # - [Int] tid the tracking id used in campaign links - used primarily for reports/click-activity. also can be used to order urls by the order they appeared in the campaign to recreate our heat map.
1800
+ def clicks(cid)
1801
+ _params = {:cid => cid}
1802
+ return @master.call 'reports/clicks', _params
1803
+ end
1804
+
1805
+ # Retrieve the Ecommerce Orders tracked by campaignEcommOrderAdd()
1806
+ # @param [String] cid the campaign id to pull orders for for (can be gathered using campaigns())
1807
+ # @param [Hash] opts various options for controlling returned data
1808
+ # - [Int] start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
1809
+ # - [Int] limit optional for large data sets, the number of results to return - defaults to 25, upper limit set at 100
1810
+ # - [String] since optional pull only messages since this time - 24 hour format in <strong>GMT</strong>, eg "2013-12-30 20:30:00"
1811
+ # @return [Hash] the total matching orders and the specific orders for the requested page
1812
+ # - [Int] total the total matching orders
1813
+ # - [Array] data structs for the actual data for each order being returned
1814
+ # - [String] store_id the store id generated by the plugin used to uniquely identify a store
1815
+ # - [String] store_name the store name collected by the plugin - often the domain name
1816
+ # - [String] order_id the internal order id the store tracked this order by
1817
+ # - [Hash] member the member record as returned by lists/member-info that received this campaign and is associated with this order
1818
+ # - [Double] order_total the order total
1819
+ # - [Double] tax_total the total tax for the order (if collected)
1820
+ # - [Double] ship_total the shipping total for the order (if collected)
1821
+ # - [String] order_date the date the order was tracked - from the store if possible, otherwise the GMT time we received it
1822
+ # - [Array] lines structs containing details of the order:
1823
+ # - [Int] line_num the line number assigned to this line
1824
+ # - [Int] product_id the product id assigned to this item
1825
+ # - [String] product_name the product name
1826
+ # - [String] product_sku the sku for the product
1827
+ # - [Int] product_category_id the id for the product category
1828
+ # - [String] product_category_name the product category name
1829
+ # - [Double] qty optional the quantity of the item ordered - defaults to 1
1830
+ # - [Double] cost optional the cost of a single item (ie, not the extended cost of the line) - defaults to 0
1831
+ def ecomm_orders(cid, opts=[])
1832
+ _params = {:cid => cid, :opts => opts}
1833
+ return @master.call 'reports/ecomm-orders', _params
1834
+ end
1835
+
1836
+ # Retrieve the eepurl stats from the web/Twitter mentions for this campaign
1837
+ # @param [String] cid the campaign id to pull stats for (can be gathered using campaigns())
1838
+ # @return [Hash] containing tweets, retweets, clicks, and referrer related to using the campaign's eepurl
1839
+ # - [Hash] twitter various Twitter related stats
1840
+ # - [Int] tweets Total number of tweets seen
1841
+ # - [String] first_tweet date and time of the first tweet seen
1842
+ # - [String] last_tweet date and time of the last tweet seen
1843
+ # - [Int] retweets Total number of retweets seen
1844
+ # - [String] first_retweet date and time of the first retweet seen
1845
+ # - [String] last_retweet date and time of the last retweet seen
1846
+ # - [Array] statuses an structs for statuses recorded including:
1847
+ # - [String] status the text of the tweet/update
1848
+ # - [String] screen_name the screen name as recorded when first seen
1849
+ # - [String] status_id the status id of the tweet (they are really unsigned 64 bit ints)
1850
+ # - [String] datetime the date/time of the tweet
1851
+ # - [Bool] is_retweet whether or not this was a retweet
1852
+ # - [Hash] clicks stats related to click-throughs on the eepurl
1853
+ # - [Int] clicks Total number of clicks seen
1854
+ # - [String] first_click date and time of the first click seen
1855
+ # - [String] last_click date and time of the first click seen
1856
+ # - [Array] locations structs for geographic locations including:
1857
+ # - [String] country the country name the click was tracked to
1858
+ # - [String] region the region in the country the click was tracked to (if available)
1859
+ # - [Array] referrers structs for referrers, including
1860
+ # - [String] referrer the referrer, truncated to 100 bytes
1861
+ # - [Int] clicks Total number of clicks seen from this referrer
1862
+ # - [String] first_click date and time of the first click seen from this referrer
1863
+ # - [String] last_click date and time of the first click seen from this referrer
1864
+ def eepurl(cid)
1865
+ _params = {:cid => cid}
1866
+ return @master.call 'reports/eepurl', _params
1867
+ end
1868
+
1869
+ # 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.
1870
+ # @param [String] cid the campaign id to get stats for (can be gathered using campaigns())
1871
+ # @param [Array] emails an array of up to 50 email address struct to retrieve activity information for
1872
+ # - [String] email an email address
1873
+ # - [String] euid the unique id for an email address (not list related) - the email "id" returned from listMemberInfo, Webhooks, Campaigns, etc.
1874
+ # - [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
1875
+ # @return [Hash] of data and success/error counts
1876
+ # - [Int] success_count the number of subscribers successfully found on the list
1877
+ # - [Int] error_count the number of subscribers who were not found on the list
1878
+ # - [Array] errors array of error structs including:
1879
+ # - [String] email whatever was passed in the email parameter
1880
+ # - [String] email the email address added
1881
+ # - [String] euid the email unique id
1882
+ # - [String] leid the list member's truly unique id
1883
+ # - [String] msg the error message
1884
+ # - [Array] data an array of structs where each activity record has:
1885
+ # - [String] email whatever was passed in the email parameter
1886
+ # - [String] email the email address added
1887
+ # - [String] euid the email unique id
1888
+ # - [String] leid the list member's truly unique id
1889
+ # - [Hash] member the member record as returned by lists/member-info
1890
+ # - [Array] activity an array of structs containing the activity, including:
1891
+ # - [String] action The action name - either open or click
1892
+ # - [String] timestamp The date/time of the action (GMT)
1893
+ # - [String] url For click actions, the url clicked, otherwise this is empty
1894
+ # - [String] ip The IP address the activity came from
1895
+ def member_activity(cid, emails)
1896
+ _params = {:cid => cid, :emails => emails}
1897
+ return @master.call 'reports/member-activity', _params
1898
+ end
1899
+
1900
+ # Retrieve the list of email addresses that did not open a given campaign
1901
+ # @param [String] cid the campaign id to get no opens for (can be gathered using campaigns())
1902
+ # @param [Hash] opts various options for controlling returned data
1903
+ # - [Int] start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
1904
+ # - [Int] limit optional for large data sets, the number of results to return - defaults to 25, upper limit set at 100
1905
+ # @return [Hash] a total of all matching emails and the specific emails for this page
1906
+ # - [Int] total the total number of members who didn't open the campaign
1907
+ # - [Array] data structs for each campaign member matching as returned by lists/member-info
1908
+ def not_opened(cid, opts=[])
1909
+ _params = {:cid => cid, :opts => opts}
1910
+ return @master.call 'reports/not-opened', _params
1911
+ end
1912
+
1913
+ # Retrieve the list of email addresses that opened a given campaign with how many times they opened
1914
+ # @param [String] cid the campaign id to get opens for (can be gathered using campaigns())
1915
+ # @param [Hash] opts various options for controlling returned data
1916
+ # - [Int] start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
1917
+ # - [Int] limit optional for large data sets, the number of results to return - defaults to 25, upper limit set at 100
1918
+ # - [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.
1919
+ # - [String] sort_dir optional the direct - ASC or DESC. defaults to ASC (case insensitive)
1920
+ # @return [Array] array containing the total records matched and the specific records for this page
1921
+ # - [Int] total the total number of records matched
1922
+ # - [Array] data structs for the actual opens data, including:
1923
+ # - [Hash] member the member record as returned by lists/member-info
1924
+ # - [Int] opens Total number of times the campaign was opened by this email address
1925
+ def opened(cid, opts=[])
1926
+ _params = {:cid => cid, :opts => opts}
1927
+ return @master.call 'reports/opened', _params
1928
+ end
1929
+
1930
+ # Get the top 5 performing email domains for this campaign. Users wanting more than 5 should use campaign campaignEmailStatsAIM() or campaignEmailStatsAIMAll() and generate any additional stats they require.
1931
+ # @param [String] cid the campaign id to pull email domain performance for (can be gathered using campaigns())
1932
+ # @return [Array] domains stricts for each email domains and their associated stats
1933
+ # - [String] domain Domain name or special "Other" to roll-up stats past 5 domains
1934
+ # - [Int] total_sent Total Email across all domains - this will be the same in every row
1935
+ # - [Int] emails Number of emails sent to this domain
1936
+ # - [Int] bounces Number of bounces
1937
+ # - [Int] opens Number of opens
1938
+ # - [Int] clicks Number of clicks
1939
+ # - [Int] unsubs Number of unsubs
1940
+ # - [Int] delivered Number of deliveries
1941
+ # - [Int] emails_pct Percentage of emails that went to this domain (whole number)
1942
+ # - [Int] bounces_pct Percentage of bounces from this domain (whole number)
1943
+ # - [Int] opens_pct Percentage of opens from this domain (whole number)
1944
+ # - [Int] clicks_pct Percentage of clicks from this domain (whole number)
1945
+ # - [Int] unsubs_pct Percentage of unsubs from this domain (whole number)
1946
+ def domain_performance(cid)
1947
+ _params = {:cid => cid}
1948
+ return @master.call 'reports/domain-performance', _params
1949
+ end
1950
+
1951
+ # Retrieve the countries/regions and number of opens tracked for each. Email address are not returned.
1952
+ # @param [String] cid the campaign id to pull bounces for (can be gathered using campaigns())
1953
+ # @return [Array] an array of country structs where opens occurred
1954
+ # - [String] code The ISO3166 2 digit country code
1955
+ # - [String] name A version of the country name, if we have it
1956
+ # - [Int] opens The total number of opens that occurred in the country
1957
+ # - [Array] regions struct of data for each sub-region in the country
1958
+ # - [String] code An internal code for the region. When this is blank, it indicates we know the country, but not the region
1959
+ # - [String] name The name of the region, if we have one. For blank "code" values, this will be "Rest of Country"
1960
+ # - [Int] opens The total number of opens that occurred in the country
1961
+ def geo_opens(cid)
1962
+ _params = {:cid => cid}
1963
+ return @master.call 'reports/geo-opens', _params
1964
+ end
1965
+
1966
+ # Retrieve the Google Analytics data we've collected for this campaign. Note, requires Google Analytics Add-on to be installed and configured.
1967
+ # @param [String] cid the campaign id to pull bounces for (can be gathered using campaigns())
1968
+ # @return [Array] of structs for analytics we've collected for the passed campaign.
1969
+ # - [Int] visits number of visits
1970
+ # - [Int] pages number of page views
1971
+ # - [Int] new_visits new visits recorded
1972
+ # - [Int] bounces vistors who "bounced" from your site
1973
+ # - [Double] time_on_site the total time visitors spent on your sites
1974
+ # - [Int] goal_conversions number of goals converted
1975
+ # - [Double] goal_value value of conversion in dollars
1976
+ # - [Double] revenue revenue generated by campaign
1977
+ # - [Int] transactions number of transactions tracked
1978
+ # - [Int] ecomm_conversions number Ecommerce transactions tracked
1979
+ # - [Array] goals structs containing goal names and number of conversions
1980
+ # - [String] name the name of the goal
1981
+ # - [Int] conversions the number of conversions for the goal
1982
+ def google_analytics(cid)
1983
+ _params = {:cid => cid}
1984
+ return @master.call 'reports/google-analytics', _params
1985
+ end
1986
+
1987
+ # Get email addresses the campaign was sent to
1988
+ # @param [String] cid the campaign id to pull members for (can be gathered using campaigns())
1989
+ # @param [Hash] opts various options for controlling returned data
1990
+ # - [String] status optional the status to pull - one of 'sent', 'hard' (bounce), or 'soft' (bounce). By default, all records are returned
1991
+ # - [Int] start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
1992
+ # - [Int] limit optional for large data sets, the number of results to return - defaults to 25, upper limit set at 100
1993
+ # @return [Hash] a total of all matching emails and the specific emails for this page
1994
+ # - [Int] total the total number of members for the campaign and status
1995
+ # - [Array] data structs for each campaign member matching
1996
+ # - [Hash] member the member record as returned by lists/member-info
1997
+ # - [String] status the status of the send - one of 'sent', 'hard', 'soft'
1998
+ # - [String] absplit_group if this was an absplit campaign, one of 'a','b', or 'winner'
1999
+ # - [String] tz_group if this was an timewarp campaign the timezone GMT offset the member was included in
2000
+ def sent_to(cid, opts=[])
2001
+ _params = {:cid => cid, :opts => opts}
2002
+ return @master.call 'reports/sent-to', _params
2003
+ end
2004
+
2005
+ # 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)
2006
+ # @param [String] cid the campaign id to share a report for (can be gathered using campaigns())
2007
+ # @param [Array] opts optional various parameters which can be used to configure the shared report
2008
+ # - [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
2009
+ # - [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.
2010
+ # - [String] css_url optional - a link to an external CSS file to be included after our default CSS (http://vip-reports.net/css/vip.css) <strong>only if</strong> loaded via the "secure_url" - max 255 bytes
2011
+ # @return [Hash] details for the shared report, including:
2012
+ # - [String] title The Title of the Campaign being shared
2013
+ # - [String] url The URL to the shared report
2014
+ # - [String] secure_url The URL to the shared report, including the password (good for loading in an IFRAME). For non-secure reports, this will not be returned
2015
+ # - [String] password If secured, the password for the report, otherwise this field will not be returned
2016
+ def share(cid, opts=[])
2017
+ _params = {:cid => cid, :opts => opts}
2018
+ return @master.call 'reports/share', _params
2019
+ end
2020
+
2021
+ # Retrieve relevant aggregate campaign statistics (opens, bounces, clicks, etc.)
2022
+ # @param [String] cid the campaign id to pull stats for (can be gathered using campaigns())
2023
+ # @return [Hash] the statistics for this campaign
2024
+ # - [Int] syntax_errors Number of email addresses in campaign that had syntactical errors.
2025
+ # - [Int] hard_bounces Number of email addresses in campaign that hard bounced.
2026
+ # - [Int] soft_bounces Number of email addresses in campaign that soft bounced.
2027
+ # - [Int] unsubscribes Number of email addresses in campaign that unsubscribed.
2028
+ # - [Int] abuse_reports Number of email addresses in campaign that reported campaign for abuse.
2029
+ # - [Int] forwards Number of times email was forwarded to a friend.
2030
+ # - [Int] forwards_opens Number of times a forwarded email was opened.
2031
+ # - [Int] opens Number of times the campaign was opened.
2032
+ # - [String] last_open Date of the last time the email was opened.
2033
+ # - [Int] unique_opens Number of people who opened the campaign.
2034
+ # - [Int] clicks Number of times a link in the campaign was clicked.
2035
+ # - [Int] unique_clicks Number of unique recipient/click pairs for the campaign.
2036
+ # - [String] last_click Date of the last time a link in the email was clicked.
2037
+ # - [Int] users_who_clicked Number of unique recipients who clicked on a link in the campaign.
2038
+ # - [Int] emails_sent Number of email addresses campaign was sent to.
2039
+ # - [Int] unique_likes total number of unique likes (Facebook)
2040
+ # - [Int] recipient_likes total number of recipients who liked (Facebook) the campaign
2041
+ # - [Int] facebook_likes total number of likes (Facebook) that came from Facebook
2042
+ # - [Hash] absplit If this was an absplit campaign, stats for the A and B groups will be returned - otherwise this is empty
2043
+ # - [Int] bounces_a bounces for the A group
2044
+ # - [Int] bounces_b bounces for the B group
2045
+ # - [Int] forwards_a forwards for the A group
2046
+ # - [Int] forwards_b forwards for the B group
2047
+ # - [Int] abuse_reports_a abuse reports for the A group
2048
+ # - [Int] abuse_reports_b abuse reports for the B group
2049
+ # - [Int] unsubs_a unsubs for the A group
2050
+ # - [Int] unsubs_b unsubs for the B group
2051
+ # - [Int] recipients_click_a clicks for the A group
2052
+ # - [Int] recipients_click_b clicks for the B group
2053
+ # - [Int] forwards_opens_a opened forwards for the A group
2054
+ # - [Int] forwards_opens_b opened forwards for the B group
2055
+ # - [Int] opens_a total opens for the A group
2056
+ # - [Int] opens_b total opens for the B group
2057
+ # - [String] last_open_a date/time of last open for the A group
2058
+ # - [String] last_open_b date/time of last open for the BG group
2059
+ # - [Int] unique_opens_a unique opens for the A group
2060
+ # - [Int] unique_opens_b unique opens for the B group
2061
+ # - [Array] timewarp If this campaign was a Timewarp campaign, an array of structs from each timezone stats exist for. Each will contain:
2062
+ # - [Int] opens opens for this timezone
2063
+ # - [String] last_open the date/time of the last open for this timezone
2064
+ # - [Int] unique_opens the unique opens for this timezone
2065
+ # - [Int] clicks the total clicks for this timezone
2066
+ # - [String] last_click the date/time of the last click for this timezone
2067
+ # - [Int] unique_opens the unique clicks for this timezone
2068
+ # - [Int] bounces the total bounces for this timezone
2069
+ # - [Int] total the total number of members sent to in this timezone
2070
+ # - [Int] sent the total number of members delivered to in this timezone
2071
+ # - [Array] timeseries structs for the first 24 hours of the campaign, per-hour stats:
2072
+ # - [String] timestamp The timestemp in Y-m-d H:00:00 format
2073
+ # - [Int] emails_sent the total emails sent during the hour
2074
+ # - [Int] unique_opens unique opens seen during the hour
2075
+ # - [Int] recipients_click unique clicks seen during the hour
2076
+ def summary(cid)
2077
+ _params = {:cid => cid}
2078
+ return @master.call 'reports/summary', _params
2079
+ end
2080
+
2081
+ # Get all unsubscribed email addresses for a given campaign
2082
+ # @param [String] cid the campaign id to pull bounces for (can be gathered using campaigns())
2083
+ # @param [Hash] opts various options for controlling returned data
2084
+ # - [Int] start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
2085
+ # - [Int] limit optional for large data sets, the number of results to return - defaults to 25, upper limit set at 100
2086
+ # @return [Hash] a total of all unsubscribed emails and the specific members for this page
2087
+ # - [Int] total the total number of unsubscribes for the campaign
2088
+ # - [Array] data structs for the email addresses that unsubscribed
2089
+ # - [String] member the member that unsubscribed as returned by lists/member-info
2090
+ # - [String] reason the reason collected for the unsubscribe. If populated, one of 'NORMAL','NOSIGNUP','INAPPROPRIATE','SPAM','OTHER'
2091
+ # - [String] reason_text if the reason is OTHER, the text entered.
2092
+ def unsubscribes(cid, opts=[])
2093
+ _params = {:cid => cid, :opts => opts}
2094
+ return @master.call 'reports/unsubscribes', _params
2095
+ end
2096
+
2097
+ end
2098
+ class Gallery
2099
+ attr_accessor :master
2100
+
2101
+ def initialize(master)
2102
+ @master = master
2103
+ end
2104
+
2105
+ # Return a section of the image gallery
2106
+ # @param [Hash] opts various options for controlling returned data
2107
+ # - [String] type optional the gallery type to return - images or files - default to images
2108
+ # - [Int] start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
2109
+ # - [Int] limit optional for large data sets, the number of results to return - defaults to 25, upper limit set at 100
2110
+ # - [String] sort_by optional field to sort by - one of size, time, name - defaults to time
2111
+ # - [String] sort_dir optional field to sort by - one of asc, desc - defaults to desc
2112
+ # - [String] search_term optional a term to search for in names
2113
+ # @return [Hash] the matching gallery items
2114
+ # - [Int] total the total matching items
2115
+ # - [Array] data structs for each item included in the set, including:
2116
+ # - [String] name the file name
2117
+ # - [String] time the creation date for the item
2118
+ # - [Int] size the file size in bytes
2119
+ # - [String] full the url to the actual item in the gallery
2120
+ # - [String] thumb a url for a thumbnail that can be used to represent the item, generally an image thumbnail or an icon for a file type
2121
+ def list(opts=[])
2122
+ _params = {:opts => opts}
2123
+ return @master.call 'gallery/list', _params
2124
+ end
2125
+
2126
+ end
2127
+ end
2128
+