mandrillus 2.0.0

Sign up to get free protection for your applications and to get access to all the features.
@@ -0,0 +1,7 @@
1
+ ---
2
+ SHA256:
3
+ metadata.gz: 2a6ad28a05e783d7c5fa519dba8dc1376862c57fe7505b81a96003c2585c80e0
4
+ data.tar.gz: 3513fbe97fe286826ef77cac5f0191d530d839512e585c3246fc3f575f39bb00
5
+ SHA512:
6
+ metadata.gz: fc9957e63ad4def4759caaa840ff7a46f53e222a80da361090be8fa3a34fc3c837b96633a6259a7f14af438375dd44d76a5b2365740639dcdd518caa22e625d3
7
+ data.tar.gz: 51770abab959038720ff2d67b0d24d2be83046c27ea77705eea8dda2d04086c3568bf2986247f17e06492fb7fc74f54126a81560c7d47094dbb0b80365a0e365
@@ -0,0 +1,148 @@
1
+ require 'rubygems'
2
+ require 'excon'
3
+ require 'json'
4
+
5
+ require 'mandrill/errors'
6
+ require 'mandrill/api'
7
+
8
+ module Mandrill
9
+ class API
10
+
11
+ attr_accessor :host, :path, :apikey, :debug, :session
12
+
13
+ def initialize(apikey=nil, debug=false)
14
+ @host = 'https://mandrillapp.com'
15
+ @path = '/api/1.0/'
16
+
17
+ @session = Excon.new @host
18
+ @debug = debug
19
+
20
+ if not apikey
21
+ if ENV['MANDRILL_APIKEY']
22
+ apikey = ENV['MANDRILL_APIKEY']
23
+ else
24
+ apikey = read_configs
25
+ end
26
+ end
27
+
28
+ raise Error, 'You must provide a Mandrill API key' if not apikey
29
+ @apikey = apikey
30
+ end
31
+
32
+ def call(url, params={})
33
+ params[:key] = @apikey
34
+ params = JSON.generate(params)
35
+ r = @session.post(:path => "#{@path}#{url}.json", :headers => {'Content-Type' => 'application/json'}, :body => params)
36
+
37
+ cast_error(r.body) if r.status != 200
38
+ return JSON.parse(r.body)
39
+ end
40
+
41
+ def read_configs()
42
+ [File.expand_path('~/.mandrill.key'), '/etc/mandrill.key'].delete_if{ |p| not File.exist? p}.each do |path|
43
+ f = File.new path
44
+ apikey = f.read.strip
45
+ f.close
46
+ return apikey if apikey != ''
47
+ end
48
+
49
+ return nil
50
+ end
51
+
52
+ def cast_error(body)
53
+
54
+ error_map = {
55
+ 'ValidationError' => ValidationError,
56
+ 'Invalid_Key' => InvalidKeyError,
57
+ 'PaymentRequired' => PaymentRequiredError,
58
+ 'Unknown_Subaccount' => UnknownSubaccountError,
59
+ 'Unknown_Template' => UnknownTemplateError,
60
+ 'ServiceUnavailable' => ServiceUnavailableError,
61
+ 'Unknown_Message' => UnknownMessageError,
62
+ 'Invalid_Tag_Name' => InvalidTagNameError,
63
+ 'Invalid_Reject' => InvalidRejectError,
64
+ 'Unknown_Sender' => UnknownSenderError,
65
+ 'Unknown_Url' => UnknownUrlError,
66
+ 'Unknown_TrackingDomain' => UnknownTrackingDomainError,
67
+ 'Invalid_Template' => InvalidTemplateError,
68
+ 'Unknown_Webhook' => UnknownWebhookError,
69
+ 'Unknown_InboundDomain' => UnknownInboundDomainError,
70
+ 'Unknown_InboundRoute' => UnknownInboundRouteError,
71
+ 'Unknown_Export' => UnknownExportError,
72
+ 'IP_ProvisionLimit' => IPProvisionLimitError,
73
+ 'Unknown_Pool' => UnknownPoolError,
74
+ 'NoSendingHistory' => NoSendingHistoryError,
75
+ 'PoorReputation' => PoorReputationError,
76
+ 'Unknown_IP' => UnknownIPError,
77
+ 'Invalid_EmptyDefaultPool' => InvalidEmptyDefaultPoolError,
78
+ 'Invalid_DeleteDefaultPool' => InvalidDeleteDefaultPoolError,
79
+ 'Invalid_DeleteNonEmptyPool' => InvalidDeleteNonEmptyPoolError,
80
+ 'Invalid_CustomDNS' => InvalidCustomDNSError,
81
+ 'Invalid_CustomDNSPending' => InvalidCustomDNSPendingError,
82
+ 'Metadata_FieldLimit' => MetadataFieldLimitError,
83
+ 'Unknown_MetadataField' => UnknownMetadataFieldError
84
+ }
85
+
86
+ begin
87
+ error_info = JSON.parse(body)
88
+ if error_info['status'] != 'error' or not error_info['name']
89
+ raise Error, "We received an unexpected error: #{body}"
90
+ end
91
+ if error_map[error_info['name']]
92
+ raise error_map[error_info['name']], error_info['message']
93
+ else
94
+ raise Error, error_info['message']
95
+ end
96
+ rescue JSON::ParserError
97
+ raise Error, "We received an unexpected error: #{body}"
98
+ end
99
+ end
100
+
101
+ def templates()
102
+ Templates.new self
103
+ end
104
+ def exports()
105
+ Exports.new self
106
+ end
107
+ def users()
108
+ Users.new self
109
+ end
110
+ def rejects()
111
+ Rejects.new self
112
+ end
113
+ def inbound()
114
+ Inbound.new self
115
+ end
116
+ def tags()
117
+ Tags.new self
118
+ end
119
+ def messages()
120
+ Messages.new self
121
+ end
122
+ def whitelists()
123
+ Whitelists.new self
124
+ end
125
+ def ips()
126
+ Ips.new self
127
+ end
128
+ def internal()
129
+ Internal.new self
130
+ end
131
+ def subaccounts()
132
+ Subaccounts.new self
133
+ end
134
+ def urls()
135
+ Urls.new self
136
+ end
137
+ def webhooks()
138
+ Webhooks.new self
139
+ end
140
+ def senders()
141
+ Senders.new self
142
+ end
143
+ def metadata()
144
+ Metadata.new self
145
+ end
146
+ end
147
+ end
148
+
@@ -0,0 +1,2055 @@
1
+ module Mandrill
2
+
3
+
4
+ class Templates
5
+ attr_accessor :master
6
+
7
+ def initialize(master)
8
+ @master = master
9
+ end
10
+
11
+ # Add a new template
12
+ # @param [String] name the name for the new template - must be unique
13
+ # @param [String] from_email a default sending address for emails sent using this template
14
+ # @param [String] from_name a default from name to be used
15
+ # @param [String] subject a default subject line to be used
16
+ # @param [String] code the HTML code for the template with mc:edit attributes for the editable elements
17
+ # @param [String] text a default text part to be used when sending with this template
18
+ # @param [Boolean] publish set to false to add a draft template without publishing
19
+ # @param [Array] labels an optional array of up to 10 labels to use for filtering templates
20
+ # - [String] labels[] a single label
21
+ # @return [Hash] the information saved about the new template
22
+ # - [String] slug the immutable unique code name of the template
23
+ # - [String] name the name of the template
24
+ # - [Array] labels the list of labels applied to the template
25
+ # - [String] labels[] a single label
26
+ # - [String] code the full HTML code of the template, with mc:edit attributes marking the editable elements - draft version
27
+ # - [String] subject the subject line of the template, if provided - draft version
28
+ # - [String] from_email the default sender address for the template, if provided - draft version
29
+ # - [String] from_name the default sender from name for the template, if provided - draft version
30
+ # - [String] text the default text part of messages sent with the template, if provided - draft version
31
+ # - [String] publish_name the same as the template name - kept as a separate field for backwards compatibility
32
+ # - [String] publish_code the full HTML code of the template, with mc:edit attributes marking the editable elements that are available as published, if it has been published
33
+ # - [String] publish_subject the subject line of the template, if provided
34
+ # - [String] publish_from_email the default sender address for the template, if provided
35
+ # - [String] publish_from_name the default sender from name for the template, if provided
36
+ # - [String] publish_text the default text part of messages sent with the template, if provided
37
+ # - [String] published_at the date and time the template was last published as a UTC string in YYYY-MM-DD HH:MM:SS format, or null if it has not been published
38
+ # - [String] created_at the date and time the template was first created as a UTC string in YYYY-MM-DD HH:MM:SS format
39
+ # - [String] updated_at the date and time the template was last modified as a UTC string in YYYY-MM-DD HH:MM:SS format
40
+ def add(name, from_email=nil, from_name=nil, subject=nil, code=nil, text=nil, publish=true, labels=[])
41
+ _params = {:name => name, :from_email => from_email, :from_name => from_name, :subject => subject, :code => code, :text => text, :publish => publish, :labels => labels}
42
+ return @master.call 'templates/add', _params
43
+ end
44
+
45
+ # Get the information for an existing template
46
+ # @param [String] name the immutable name of an existing template
47
+ # @return [Hash] the requested template information
48
+ # - [String] slug the immutable unique code name of the template
49
+ # - [String] name the name of the template
50
+ # - [Array] labels the list of labels applied to the template
51
+ # - [String] labels[] a single label
52
+ # - [String] code the full HTML code of the template, with mc:edit attributes marking the editable elements - draft version
53
+ # - [String] subject the subject line of the template, if provided - draft version
54
+ # - [String] from_email the default sender address for the template, if provided - draft version
55
+ # - [String] from_name the default sender from name for the template, if provided - draft version
56
+ # - [String] text the default text part of messages sent with the template, if provided - draft version
57
+ # - [String] publish_name the same as the template name - kept as a separate field for backwards compatibility
58
+ # - [String] publish_code the full HTML code of the template, with mc:edit attributes marking the editable elements that are available as published, if it has been published
59
+ # - [String] publish_subject the subject line of the template, if provided
60
+ # - [String] publish_from_email the default sender address for the template, if provided
61
+ # - [String] publish_from_name the default sender from name for the template, if provided
62
+ # - [String] publish_text the default text part of messages sent with the template, if provided
63
+ # - [String] published_at the date and time the template was last published as a UTC string in YYYY-MM-DD HH:MM:SS format, or null if it has not been published
64
+ # - [String] created_at the date and time the template was first created as a UTC string in YYYY-MM-DD HH:MM:SS format
65
+ # - [String] updated_at the date and time the template was last modified as a UTC string in YYYY-MM-DD HH:MM:SS format
66
+ def info(name)
67
+ _params = {:name => name}
68
+ return @master.call 'templates/info', _params
69
+ end
70
+
71
+ # Update the code for an existing template. If null is provided for any fields, the values will remain unchanged.
72
+ # @param [String] name the immutable name of an existing template
73
+ # @param [String] from_email the new default sending address
74
+ # @param [String] from_name the new default from name
75
+ # @param [String] subject the new default subject line
76
+ # @param [String] code the new code for the template
77
+ # @param [String] text the new default text part to be used
78
+ # @param [Boolean] publish set to false to update the draft version of the template without publishing
79
+ # @param [Array] labels an optional array of up to 10 labels to use for filtering templates
80
+ # - [String] labels[] a single label
81
+ # @return [Hash] the template that was updated
82
+ # - [String] slug the immutable unique code name of the template
83
+ # - [String] name the name of the template
84
+ # - [Array] labels the list of labels applied to the template
85
+ # - [String] labels[] a single label
86
+ # - [String] code the full HTML code of the template, with mc:edit attributes marking the editable elements - draft version
87
+ # - [String] subject the subject line of the template, if provided - draft version
88
+ # - [String] from_email the default sender address for the template, if provided - draft version
89
+ # - [String] from_name the default sender from name for the template, if provided - draft version
90
+ # - [String] text the default text part of messages sent with the template, if provided - draft version
91
+ # - [String] publish_name the same as the template name - kept as a separate field for backwards compatibility
92
+ # - [String] publish_code the full HTML code of the template, with mc:edit attributes marking the editable elements that are available as published, if it has been published
93
+ # - [String] publish_subject the subject line of the template, if provided
94
+ # - [String] publish_from_email the default sender address for the template, if provided
95
+ # - [String] publish_from_name the default sender from name for the template, if provided
96
+ # - [String] publish_text the default text part of messages sent with the template, if provided
97
+ # - [String] published_at the date and time the template was last published as a UTC string in YYYY-MM-DD HH:MM:SS format, or null if it has not been published
98
+ # - [String] created_at the date and time the template was first created as a UTC string in YYYY-MM-DD HH:MM:SS format
99
+ # - [String] updated_at the date and time the template was last modified as a UTC string in YYYY-MM-DD HH:MM:SS format
100
+ def update(name, from_email=nil, from_name=nil, subject=nil, code=nil, text=nil, publish=true, labels=nil)
101
+ _params = {:name => name, :from_email => from_email, :from_name => from_name, :subject => subject, :code => code, :text => text, :publish => publish, :labels => labels}
102
+ return @master.call 'templates/update', _params
103
+ end
104
+
105
+ # Publish the content for the template. Any new messages sent using this template will start using the content that was previously in draft.
106
+ # @param [String] name the immutable name of an existing template
107
+ # @return [Hash] the template that was published
108
+ # - [String] slug the immutable unique code name of the template
109
+ # - [String] name the name of the template
110
+ # - [Array] labels the list of labels applied to the template
111
+ # - [String] labels[] a single label
112
+ # - [String] code the full HTML code of the template, with mc:edit attributes marking the editable elements - draft version
113
+ # - [String] subject the subject line of the template, if provided - draft version
114
+ # - [String] from_email the default sender address for the template, if provided - draft version
115
+ # - [String] from_name the default sender from name for the template, if provided - draft version
116
+ # - [String] text the default text part of messages sent with the template, if provided - draft version
117
+ # - [String] publish_name the same as the template name - kept as a separate field for backwards compatibility
118
+ # - [String] publish_code the full HTML code of the template, with mc:edit attributes marking the editable elements that are available as published, if it has been published
119
+ # - [String] publish_subject the subject line of the template, if provided
120
+ # - [String] publish_from_email the default sender address for the template, if provided
121
+ # - [String] publish_from_name the default sender from name for the template, if provided
122
+ # - [String] publish_text the default text part of messages sent with the template, if provided
123
+ # - [String] published_at the date and time the template was last published as a UTC string in YYYY-MM-DD HH:MM:SS format, or null if it has not been published
124
+ # - [String] created_at the date and time the template was first created as a UTC string in YYYY-MM-DD HH:MM:SS format
125
+ # - [String] updated_at the date and time the template was last modified as a UTC string in YYYY-MM-DD HH:MM:SS format
126
+ def publish(name)
127
+ _params = {:name => name}
128
+ return @master.call 'templates/publish', _params
129
+ end
130
+
131
+ # Delete a template
132
+ # @param [String] name the immutable name of an existing template
133
+ # @return [Hash] the template that was deleted
134
+ # - [String] slug the immutable unique code name of the template
135
+ # - [String] name the name of the template
136
+ # - [Array] labels the list of labels applied to the template
137
+ # - [String] labels[] a single label
138
+ # - [String] code the full HTML code of the template, with mc:edit attributes marking the editable elements - draft version
139
+ # - [String] subject the subject line of the template, if provided - draft version
140
+ # - [String] from_email the default sender address for the template, if provided - draft version
141
+ # - [String] from_name the default sender from name for the template, if provided - draft version
142
+ # - [String] text the default text part of messages sent with the template, if provided - draft version
143
+ # - [String] publish_name the same as the template name - kept as a separate field for backwards compatibility
144
+ # - [String] publish_code the full HTML code of the template, with mc:edit attributes marking the editable elements that are available as published, if it has been published
145
+ # - [String] publish_subject the subject line of the template, if provided
146
+ # - [String] publish_from_email the default sender address for the template, if provided
147
+ # - [String] publish_from_name the default sender from name for the template, if provided
148
+ # - [String] publish_text the default text part of messages sent with the template, if provided
149
+ # - [String] published_at the date and time the template was last published as a UTC string in YYYY-MM-DD HH:MM:SS format, or null if it has not been published
150
+ # - [String] created_at the date and time the template was first created as a UTC string in YYYY-MM-DD HH:MM:SS format
151
+ # - [String] updated_at the date and time the template was last modified as a UTC string in YYYY-MM-DD HH:MM:SS format
152
+ def delete(name)
153
+ _params = {:name => name}
154
+ return @master.call 'templates/delete', _params
155
+ end
156
+
157
+ # Return a list of all the templates available to this user
158
+ # @param [String] label an optional label to filter the templates
159
+ # @return [Array] an array of structs with information about each template
160
+ # - [Hash] return[] the information on each template in the account
161
+ # - [String] slug the immutable unique code name of the template
162
+ # - [String] name the name of the template
163
+ # - [Array] labels the list of labels applied to the template
164
+ # - [String] labels[] a single label
165
+ # - [String] code the full HTML code of the template, with mc:edit attributes marking the editable elements - draft version
166
+ # - [String] subject the subject line of the template, if provided - draft version
167
+ # - [String] from_email the default sender address for the template, if provided - draft version
168
+ # - [String] from_name the default sender from name for the template, if provided - draft version
169
+ # - [String] text the default text part of messages sent with the template, if provided - draft version
170
+ # - [String] publish_name the same as the template name - kept as a separate field for backwards compatibility
171
+ # - [String] publish_code the full HTML code of the template, with mc:edit attributes marking the editable elements that are available as published, if it has been published
172
+ # - [String] publish_subject the subject line of the template, if provided
173
+ # - [String] publish_from_email the default sender address for the template, if provided
174
+ # - [String] publish_from_name the default sender from name for the template, if provided
175
+ # - [String] publish_text the default text part of messages sent with the template, if provided
176
+ # - [String] published_at the date and time the template was last published as a UTC string in YYYY-MM-DD HH:MM:SS format, or null if it has not been published
177
+ # - [String] created_at the date and time the template was first created as a UTC string in YYYY-MM-DD HH:MM:SS format
178
+ # - [String] updated_at the date and time the template was last modified as a UTC string in YYYY-MM-DD HH:MM:SS format
179
+ def list(label=nil)
180
+ _params = {:label => label}
181
+ return @master.call 'templates/list', _params
182
+ end
183
+
184
+ # Return the recent history (hourly stats for the last 30 days) for a template
185
+ # @param [String] name the name of an existing template
186
+ # @return [Array] the array of history information
187
+ # - [Hash] return[] the stats for a single hour
188
+ # - [String] time the hour as a UTC date string in YYYY-MM-DD HH:MM:SS format
189
+ # - [Integer] sent the number of emails that were sent during the hour
190
+ # - [Integer] hard_bounces the number of emails that hard bounced during the hour
191
+ # - [Integer] soft_bounces the number of emails that soft bounced during the hour
192
+ # - [Integer] rejects the number of emails that were rejected during the hour
193
+ # - [Integer] complaints the number of spam complaints received during the hour
194
+ # - [Integer] opens the number of emails opened during the hour
195
+ # - [Integer] unique_opens the number of unique opens generated by messages sent during the hour
196
+ # - [Integer] clicks the number of tracked URLs clicked during the hour
197
+ # - [Integer] unique_clicks the number of unique clicks generated by messages sent during the hour
198
+ def time_series(name)
199
+ _params = {:name => name}
200
+ return @master.call 'templates/time-series', _params
201
+ end
202
+
203
+ # Inject content and optionally merge fields into a template, returning the HTML that results
204
+ # @param [String] template_name the immutable name of a template that exists in the user's account
205
+ # @param [Array] template_content an array of template content to render. Each item in the array should be a struct with two keys - name: the name of the content block to set the content for, and content: the actual content to put into the block
206
+ # - [Hash] template_content[] the injection of a single piece of content into a single editable region
207
+ # - [String] name the name of the mc:edit editable region to inject into
208
+ # - [String] content the content to inject
209
+ # @param [Array] merge_vars optional merge variables to use for injecting merge field content. If this is not provided, no merge fields will be replaced.
210
+ # - [Hash] merge_vars[] a single merge variable
211
+ # - [String] name the merge variable's name. Merge variable names are case-insensitive and may not start with _
212
+ # - [String] content the merge variable's content
213
+ # @return [Hash] the result of rendering the given template with the content and merge field values injected
214
+ # - [String] html the rendered HTML as a string
215
+ def render(template_name, template_content, merge_vars=nil)
216
+ _params = {:template_name => template_name, :template_content => template_content, :merge_vars => merge_vars}
217
+ return @master.call 'templates/render', _params
218
+ end
219
+
220
+ end
221
+ class Exports
222
+ attr_accessor :master
223
+
224
+ def initialize(master)
225
+ @master = master
226
+ end
227
+
228
+ # Returns information about an export job. If the export job's state is 'complete', the returned data will include a URL you can use to fetch the results. Every export job produces a zip archive, but the format of the archive is distinct for each job type. The api calls that initiate exports include more details about the output format for that job type.
229
+ # @param [String] id an export job identifier
230
+ # @return [Hash] the information about the export
231
+ # - [String] id the unique identifier for this Export. Use this identifier when checking the export job's status
232
+ # - [String] created_at the date and time that the export job was created as a UTC string in YYYY-MM-DD HH:MM:SS format
233
+ # - [String] type the type of the export job - activity, reject, or whitelist
234
+ # - [String] finished_at the date and time that the export job was finished as a UTC string in YYYY-MM-DD HH:MM:SS format
235
+ # - [String] state the export job's state - waiting, working, complete, error, or expired.
236
+ # - [String] result_url the url for the export job's results, if the job is completed.
237
+ def info(id)
238
+ _params = {:id => id}
239
+ return @master.call 'exports/info', _params
240
+ end
241
+
242
+ # Returns a list of your exports.
243
+ # @return [Array] the account's exports
244
+ # - [Hash] return[] the individual export info
245
+ # - [String] id the unique identifier for this Export. Use this identifier when checking the export job's status
246
+ # - [String] created_at the date and time that the export job was created as a UTC string in YYYY-MM-DD HH:MM:SS format
247
+ # - [String] type the type of the export job - activity, reject, or whitelist
248
+ # - [String] finished_at the date and time that the export job was finished as a UTC string in YYYY-MM-DD HH:MM:SS format
249
+ # - [String] state the export job's state - waiting, working, complete, error, or expired.
250
+ # - [String] result_url the url for the export job's results, if the job is completed.
251
+ def list()
252
+ _params = {}
253
+ return @master.call 'exports/list', _params
254
+ end
255
+
256
+ # Begins an export of your rejection blacklist. The blacklist will be exported to a zip archive containing a single file named rejects.csv that includes the following fields: email, reason, detail, created_at, expires_at, last_event_at, expires_at.
257
+ # @param [String] notify_email an optional email address to notify when the export job has finished.
258
+ # @return [Hash] information about the rejects export job that was started
259
+ # - [String] id the unique identifier for this Export. Use this identifier when checking the export job's status
260
+ # - [String] created_at the date and time that the export job was created as a UTC string in YYYY-MM-DD HH:MM:SS format
261
+ # - [String] type the type of the export job
262
+ # - [String] finished_at the date and time that the export job was finished as a UTC string in YYYY-MM-DD HH:MM:SS format, or null for jobs that have not run
263
+ # - [String] state the export job's state
264
+ # - [String] result_url the url for the export job's results, if the job is complete
265
+ def rejects(notify_email=nil)
266
+ _params = {:notify_email => notify_email}
267
+ return @master.call 'exports/rejects', _params
268
+ end
269
+
270
+ # Begins an export of your rejection whitelist. The whitelist will be exported to a zip archive containing a single file named whitelist.csv that includes the following fields: email, detail, created_at.
271
+ # @param [String] notify_email an optional email address to notify when the export job has finished.
272
+ # @return [Hash] information about the whitelist export job that was started
273
+ # - [String] id the unique identifier for this Export. Use this identifier when checking the export job's status
274
+ # - [String] created_at the date and time that the export job was created as a UTC string in YYYY-MM-DD HH:MM:SS format
275
+ # - [String] type the type of the export job
276
+ # - [String] finished_at the date and time that the export job was finished as a UTC string in YYYY-MM-DD HH:MM:SS format, or null for jobs that have not run
277
+ # - [String] state the export job's state
278
+ # - [String] result_url the url for the export job's results, if the job is complete
279
+ def whitelist(notify_email=nil)
280
+ _params = {:notify_email => notify_email}
281
+ return @master.call 'exports/whitelist', _params
282
+ end
283
+
284
+ # Begins an export of your activity history. The activity will be exported to a zip archive containing a single file named activity.csv in the same format as you would be able to export from your account's activity view. It includes the following fields: Date, Email Address, Sender, Subject, Status, Tags, Opens, Clicks, Bounce Detail. If you have configured any custom metadata fields, they will be included in the exported data.
285
+ # @param [String] notify_email an optional email address to notify when the export job has finished
286
+ # @param [String] date_from start date as a UTC string in YYYY-MM-DD HH:MM:SS format
287
+ # @param [String] date_to end date as a UTC string in YYYY-MM-DD HH:MM:SS format
288
+ # @param [Array] tags an array of tag names to narrow the export to; will match messages that contain ANY of the tags
289
+ # - [String] tags[] a tag name
290
+ # @param [Array] senders an array of senders to narrow the export to
291
+ # - [String] senders[] a sender address
292
+ # @param [Array] states an array of states to narrow the export to; messages with ANY of the states will be included
293
+ # - [String] states[] a message state
294
+ # @param [Array] api_keys an array of api keys to narrow the export to; messsagse sent with ANY of the keys will be included
295
+ # - [String] api_keys[] an API key associated with your account
296
+ # @return [Hash] information about the activity export job that was started
297
+ # - [String] id the unique identifier for this Export. Use this identifier when checking the export job's status
298
+ # - [String] created_at the date and time that the export job was created as a UTC string in YYYY-MM-DD HH:MM:SS format
299
+ # - [String] type the type of the export job
300
+ # - [String] finished_at the date and time that the export job was finished as a UTC string in YYYY-MM-DD HH:MM:SS format, or null for jobs that have not run
301
+ # - [String] state the export job's state
302
+ # - [String] result_url the url for the export job's results, if the job is complete
303
+ def activity(notify_email=nil, date_from=nil, date_to=nil, tags=nil, senders=nil, states=nil, api_keys=nil)
304
+ _params = {:notify_email => notify_email, :date_from => date_from, :date_to => date_to, :tags => tags, :senders => senders, :states => states, :api_keys => api_keys}
305
+ return @master.call 'exports/activity', _params
306
+ end
307
+
308
+ end
309
+ class Users
310
+ attr_accessor :master
311
+
312
+ def initialize(master)
313
+ @master = master
314
+ end
315
+
316
+ # Return the information about the API-connected user
317
+ # @return [Hash] the user information including username, key, reputation, quota, and historical sending stats
318
+ # - [String] username the username of the user (used for SMTP authentication)
319
+ # - [String] created_at the date and time that the user's Mandrill account was created as a UTC string in YYYY-MM-DD HH:MM:SS format
320
+ # - [String] public_id a unique, permanent identifier for this user
321
+ # - [Integer] reputation the reputation of the user on a scale from 0 to 100, with 75 generally being a "good" reputation
322
+ # - [Integer] hourly_quota the maximum number of emails Mandrill will deliver for this user each hour. Any emails beyond that will be accepted and queued for later delivery. Users with higher reputations will have higher hourly quotas
323
+ # - [Integer] backlog the number of emails that are queued for delivery due to exceeding your monthly or hourly quotas
324
+ # - [Hash] stats an aggregate summary of the account's sending stats
325
+ # - [Hash] today stats for this user so far today
326
+ # - [Integer] sent the number of emails sent for this user so far today
327
+ # - [Integer] hard_bounces the number of emails hard bounced for this user so far today
328
+ # - [Integer] soft_bounces the number of emails soft bounced for this user so far today
329
+ # - [Integer] rejects the number of emails rejected for sending this user so far today
330
+ # - [Integer] complaints the number of spam complaints for this user so far today
331
+ # - [Integer] unsubs the number of unsubscribes for this user so far today
332
+ # - [Integer] opens the number of times emails have been opened for this user so far today
333
+ # - [Integer] unique_opens the number of unique opens for emails sent for this user so far today
334
+ # - [Integer] clicks the number of URLs that have been clicked for this user so far today
335
+ # - [Integer] unique_clicks the number of unique clicks for emails sent for this user so far today
336
+ # - [Hash] last_7_days stats for this user in the last 7 days
337
+ # - [Integer] sent the number of emails sent for this user in the last 7 days
338
+ # - [Integer] hard_bounces the number of emails hard bounced for this user in the last 7 days
339
+ # - [Integer] soft_bounces the number of emails soft bounced for this user in the last 7 days
340
+ # - [Integer] rejects the number of emails rejected for sending this user in the last 7 days
341
+ # - [Integer] complaints the number of spam complaints for this user in the last 7 days
342
+ # - [Integer] unsubs the number of unsubscribes for this user in the last 7 days
343
+ # - [Integer] opens the number of times emails have been opened for this user in the last 7 days
344
+ # - [Integer] unique_opens the number of unique opens for emails sent for this user in the last 7 days
345
+ # - [Integer] clicks the number of URLs that have been clicked for this user in the last 7 days
346
+ # - [Integer] unique_clicks the number of unique clicks for emails sent for this user in the last 7 days
347
+ # - [Hash] last_30_days stats for this user in the last 30 days
348
+ # - [Integer] sent the number of emails sent for this user in the last 30 days
349
+ # - [Integer] hard_bounces the number of emails hard bounced for this user in the last 30 days
350
+ # - [Integer] soft_bounces the number of emails soft bounced for this user in the last 30 days
351
+ # - [Integer] rejects the number of emails rejected for sending this user in the last 30 days
352
+ # - [Integer] complaints the number of spam complaints for this user in the last 30 days
353
+ # - [Integer] unsubs the number of unsubscribes for this user in the last 30 days
354
+ # - [Integer] opens the number of times emails have been opened for this user in the last 30 days
355
+ # - [Integer] unique_opens the number of unique opens for emails sent for this user in the last 30 days
356
+ # - [Integer] clicks the number of URLs that have been clicked for this user in the last 30 days
357
+ # - [Integer] unique_clicks the number of unique clicks for emails sent for this user in the last 30 days
358
+ # - [Hash] last_60_days stats for this user in the last 60 days
359
+ # - [Integer] sent the number of emails sent for this user in the last 60 days
360
+ # - [Integer] hard_bounces the number of emails hard bounced for this user in the last 60 days
361
+ # - [Integer] soft_bounces the number of emails soft bounced for this user in the last 60 days
362
+ # - [Integer] rejects the number of emails rejected for sending this user in the last 60 days
363
+ # - [Integer] complaints the number of spam complaints for this user in the last 60 days
364
+ # - [Integer] unsubs the number of unsubscribes for this user in the last 60 days
365
+ # - [Integer] opens the number of times emails have been opened for this user in the last 60 days
366
+ # - [Integer] unique_opens the number of unique opens for emails sent for this user in the last 60 days
367
+ # - [Integer] clicks the number of URLs that have been clicked for this user in the last 60 days
368
+ # - [Integer] unique_clicks the number of unique clicks for emails sent for this user in the last 60 days
369
+ # - [Hash] last_90_days stats for this user in the last 90 days
370
+ # - [Integer] sent the number of emails sent for this user in the last 90 days
371
+ # - [Integer] hard_bounces the number of emails hard bounced for this user in the last 90 days
372
+ # - [Integer] soft_bounces the number of emails soft bounced for this user in the last 90 days
373
+ # - [Integer] rejects the number of emails rejected for sending this user in the last 90 days
374
+ # - [Integer] complaints the number of spam complaints for this user in the last 90 days
375
+ # - [Integer] unsubs the number of unsubscribes for this user in the last 90 days
376
+ # - [Integer] opens the number of times emails have been opened for this user in the last 90 days
377
+ # - [Integer] unique_opens the number of unique opens for emails sent for this user in the last 90 days
378
+ # - [Integer] clicks the number of URLs that have been clicked for this user in the last 90 days
379
+ # - [Integer] unique_clicks the number of unique clicks for emails sent for this user in the last 90 days
380
+ # - [Hash] all_time stats for the lifetime of the user's account
381
+ # - [Integer] sent the number of emails sent in the lifetime of the user's account
382
+ # - [Integer] hard_bounces the number of emails hard bounced in the lifetime of the user's account
383
+ # - [Integer] soft_bounces the number of emails soft bounced in the lifetime of the user's account
384
+ # - [Integer] rejects the number of emails rejected for sending this user so far today
385
+ # - [Integer] complaints the number of spam complaints in the lifetime of the user's account
386
+ # - [Integer] unsubs the number of unsubscribes in the lifetime of the user's account
387
+ # - [Integer] opens the number of times emails have been opened in the lifetime of the user's account
388
+ # - [Integer] unique_opens the number of unique opens for emails sent in the lifetime of the user's account
389
+ # - [Integer] clicks the number of URLs that have been clicked in the lifetime of the user's account
390
+ # - [Integer] unique_clicks the number of unique clicks for emails sent in the lifetime of the user's account
391
+ def info()
392
+ _params = {}
393
+ return @master.call 'users/info', _params
394
+ end
395
+
396
+ # Validate an API key and respond to a ping (anal JSON parser version)
397
+ # @return [Hash] a struct with one key "PING" with a static value "PONG!"
398
+ def ping()
399
+ _params = {}
400
+ return @master.call 'users/ping2', _params
401
+ end
402
+
403
+ # Return the senders that have tried to use this account, both verified and unverified
404
+ # @return [Array] an array of sender data, one for each sending addresses used by the account
405
+ # - [Hash] return[] the information on each sending address in the account
406
+ # - [String] address the sender's email address
407
+ # - [String] created_at the date and time that the sender was first seen by Mandrill as a UTC date string in YYYY-MM-DD HH:MM:SS format
408
+ # - [Integer] sent the total number of messages sent by this sender
409
+ # - [Integer] hard_bounces the total number of hard bounces by messages by this sender
410
+ # - [Integer] soft_bounces the total number of soft bounces by messages by this sender
411
+ # - [Integer] rejects the total number of rejected messages by this sender
412
+ # - [Integer] complaints the total number of spam complaints received for messages by this sender
413
+ # - [Integer] unsubs the total number of unsubscribe requests received for messages by this sender
414
+ # - [Integer] opens the total number of times messages by this sender have been opened
415
+ # - [Integer] clicks the total number of times tracked URLs in messages by this sender have been clicked
416
+ # - [Integer] unique_opens the number of unique opens for emails sent for this sender
417
+ # - [Integer] unique_clicks the number of unique clicks for emails sent for this sender
418
+ def senders()
419
+ _params = {}
420
+ return @master.call 'users/senders', _params
421
+ end
422
+
423
+ end
424
+ class Rejects
425
+ attr_accessor :master
426
+
427
+ def initialize(master)
428
+ @master = master
429
+ end
430
+
431
+ # Adds an email to your email rejection blacklist. Addresses that you add manually will never expire and there is no reputation penalty for removing them from your blacklist. Attempting to blacklist an address that has been whitelisted will have no effect.
432
+ # @param [String] email an email address to block
433
+ # @param [String] comment an optional comment describing the rejection
434
+ # @param [String] subaccount an optional unique identifier for the subaccount to limit the blacklist entry
435
+ # @return [Hash] a status object containing the address and the result of the operation
436
+ # - [String] email the email address you provided
437
+ # - [Boolean] added whether the operation succeeded
438
+ def add(email, comment=nil, subaccount=nil)
439
+ _params = {:email => email, :comment => comment, :subaccount => subaccount}
440
+ return @master.call 'rejects/add', _params
441
+ end
442
+
443
+ # Retrieves your email rejection blacklist. You can provide an email address to limit the results. Returns up to 1000 results. By default, entries that have expired are excluded from the results; set include_expired to true to include them.
444
+ # @param [String] email an optional email address to search by
445
+ # @param [Boolean] include_expired whether to include rejections that have already expired.
446
+ # @param [String] subaccount an optional unique identifier for the subaccount to limit the blacklist
447
+ # @return [Array] Up to 1000 rejection entries
448
+ # - [Hash] return[] the information for each rejection blacklist entry
449
+ # - [String] email the email that is blocked
450
+ # - [String] reason the type of event (hard-bounce, soft-bounce, spam, unsub, custom) that caused this rejection
451
+ # - [String] detail extended details about the event, such as the SMTP diagnostic for bounces or the comment for manually-created rejections
452
+ # - [String] created_at when the email was added to the blacklist
453
+ # - [String] last_event_at the timestamp of the most recent event that either created or renewed this rejection
454
+ # - [String] expires_at when the blacklist entry will expire (this may be in the past)
455
+ # - [Boolean] expired whether the blacklist entry has expired
456
+ # - [Hash] sender the sender that this blacklist entry applies to, or null if none.
457
+ # - [String] address the sender's email address
458
+ # - [String] created_at the date and time that the sender was first seen by Mandrill as a UTC date string in YYYY-MM-DD HH:MM:SS format
459
+ # - [Integer] sent the total number of messages sent by this sender
460
+ # - [Integer] hard_bounces the total number of hard bounces by messages by this sender
461
+ # - [Integer] soft_bounces the total number of soft bounces by messages by this sender
462
+ # - [Integer] rejects the total number of rejected messages by this sender
463
+ # - [Integer] complaints the total number of spam complaints received for messages by this sender
464
+ # - [Integer] unsubs the total number of unsubscribe requests received for messages by this sender
465
+ # - [Integer] opens the total number of times messages by this sender have been opened
466
+ # - [Integer] clicks the total number of times tracked URLs in messages by this sender have been clicked
467
+ # - [Integer] unique_opens the number of unique opens for emails sent for this sender
468
+ # - [Integer] unique_clicks the number of unique clicks for emails sent for this sender
469
+ # - [String] subaccount the subaccount that this blacklist entry applies to, or null if none.
470
+ def list(email=nil, include_expired=false, subaccount=nil)
471
+ _params = {:email => email, :include_expired => include_expired, :subaccount => subaccount}
472
+ return @master.call 'rejects/list', _params
473
+ end
474
+
475
+ # Deletes an email rejection. There is no limit to how many rejections you can remove from your blacklist, but keep in mind that each deletion has an affect on your reputation.
476
+ # @param [String] email an email address
477
+ # @param [String] subaccount an optional unique identifier for the subaccount to limit the blacklist deletion
478
+ # @return [Hash] a status object containing the address and whether the deletion succeeded.
479
+ # - [String] email the email address that was removed from the blacklist
480
+ # - [Boolean] deleted whether the address was deleted successfully.
481
+ # - [String] subaccount the subaccount blacklist that the address was removed from, if any
482
+ def delete(email, subaccount=nil)
483
+ _params = {:email => email, :subaccount => subaccount}
484
+ return @master.call 'rejects/delete', _params
485
+ end
486
+
487
+ end
488
+ class Inbound
489
+ attr_accessor :master
490
+
491
+ def initialize(master)
492
+ @master = master
493
+ end
494
+
495
+ # List the domains that have been configured for inbound delivery
496
+ # @return [Array] the inbound domains associated with the account
497
+ # - [Hash] return[] the individual domain info
498
+ # - [String] domain the domain name that is accepting mail
499
+ # - [String] created_at the date and time that the inbound domain was added as a UTC string in YYYY-MM-DD HH:MM:SS format
500
+ # - [Boolean] valid_mx true if this inbound domain has successfully set up an MX record to deliver mail to the Mandrill servers
501
+ def domains()
502
+ _params = {}
503
+ return @master.call 'inbound/domains', _params
504
+ end
505
+
506
+ # Add an inbound domain to your account
507
+ # @param [String] domain a domain name
508
+ # @return [Hash] information about the domain
509
+ # - [String] domain the domain name that is accepting mail
510
+ # - [String] created_at the date and time that the inbound domain was added as a UTC string in YYYY-MM-DD HH:MM:SS format
511
+ # - [Boolean] valid_mx true if this inbound domain has successfully set up an MX record to deliver mail to the Mandrill servers
512
+ def add_domain(domain)
513
+ _params = {:domain => domain}
514
+ return @master.call 'inbound/add-domain', _params
515
+ end
516
+
517
+ # Check the MX settings for an inbound domain. The domain must have already been added with the add-domain call
518
+ # @param [String] domain an existing inbound domain
519
+ # @return [Hash] information about the inbound domain
520
+ # - [String] domain the domain name that is accepting mail
521
+ # - [String] created_at the date and time that the inbound domain was added as a UTC string in YYYY-MM-DD HH:MM:SS format
522
+ # - [Boolean] valid_mx true if this inbound domain has successfully set up an MX record to deliver mail to the Mandrill servers
523
+ def check_domain(domain)
524
+ _params = {:domain => domain}
525
+ return @master.call 'inbound/check-domain', _params
526
+ end
527
+
528
+ # Delete an inbound domain from the account. All mail will stop routing for this domain immediately.
529
+ # @param [String] domain an existing inbound domain
530
+ # @return [Hash] information about the deleted domain
531
+ # - [String] domain the domain name that is accepting mail
532
+ # - [String] created_at the date and time that the inbound domain was added as a UTC string in YYYY-MM-DD HH:MM:SS format
533
+ # - [Boolean] valid_mx true if this inbound domain has successfully set up an MX record to deliver mail to the Mandrill servers
534
+ def delete_domain(domain)
535
+ _params = {:domain => domain}
536
+ return @master.call 'inbound/delete-domain', _params
537
+ end
538
+
539
+ # List the mailbox routes defined for an inbound domain
540
+ # @param [String] domain the domain to check
541
+ # @return [Array] the routes associated with the domain
542
+ # - [Hash] return[] the individual mailbox route
543
+ # - [String] id the unique identifier of the route
544
+ # - [String] pattern the search pattern that the mailbox name should match
545
+ # - [String] url the webhook URL where inbound messages will be published
546
+ def routes(domain)
547
+ _params = {:domain => domain}
548
+ return @master.call 'inbound/routes', _params
549
+ end
550
+
551
+ # Add a new mailbox route to an inbound domain
552
+ # @param [String] domain an existing inbound domain
553
+ # @param [String] pattern the search pattern that the mailbox name should match
554
+ # @param [String] url the webhook URL where the inbound messages will be published
555
+ # @return [Hash] the added mailbox route information
556
+ # - [String] id the unique identifier of the route
557
+ # - [String] pattern the search pattern that the mailbox name should match
558
+ # - [String] url the webhook URL where inbound messages will be published
559
+ def add_route(domain, pattern, url)
560
+ _params = {:domain => domain, :pattern => pattern, :url => url}
561
+ return @master.call 'inbound/add-route', _params
562
+ end
563
+
564
+ # Update the pattern or webhook of an existing inbound mailbox route. If null is provided for any fields, the values will remain unchanged.
565
+ # @param [String] id the unique identifier of an existing mailbox route
566
+ # @param [String] pattern the search pattern that the mailbox name should match
567
+ # @param [String] url the webhook URL where the inbound messages will be published
568
+ # @return [Hash] the updated mailbox route information
569
+ # - [String] id the unique identifier of the route
570
+ # - [String] pattern the search pattern that the mailbox name should match
571
+ # - [String] url the webhook URL where inbound messages will be published
572
+ def update_route(id, pattern=nil, url=nil)
573
+ _params = {:id => id, :pattern => pattern, :url => url}
574
+ return @master.call 'inbound/update-route', _params
575
+ end
576
+
577
+ # Delete an existing inbound mailbox route
578
+ # @param [String] id the unique identifier of an existing route
579
+ # @return [Hash] the deleted mailbox route information
580
+ # - [String] id the unique identifier of the route
581
+ # - [String] pattern the search pattern that the mailbox name should match
582
+ # - [String] url the webhook URL where inbound messages will be published
583
+ def delete_route(id)
584
+ _params = {:id => id}
585
+ return @master.call 'inbound/delete-route', _params
586
+ end
587
+
588
+ # Take a raw MIME document destined for a domain with inbound domains set up, and send it to the inbound hook exactly as if it had been sent over SMTP
589
+ # @param [String] raw_message the full MIME document of an email message
590
+ # @param [Array, nil] to optionally define the recipients to receive the message - otherwise we'll use the To, Cc, and Bcc headers provided in the document
591
+ # - [String] to[] the email address of the recipient
592
+ # @param [String] mail_from the address specified in the MAIL FROM stage of the SMTP conversation. Required for the SPF check.
593
+ # @param [String] helo the identification provided by the client mta in the MTA state of the SMTP conversation. Required for the SPF check.
594
+ # @param [String] client_address the remote MTA's ip address. Optional; required for the SPF check.
595
+ # @return [Array] an array of the information for each recipient in the message (usually one) that matched an inbound route
596
+ # - [Hash] return[] the individual recipient information
597
+ # - [String] email the email address of the matching recipient
598
+ # - [String] pattern the mailbox route pattern that the recipient matched
599
+ # - [String] url the webhook URL that the message was posted to
600
+ def send_raw(raw_message, to=nil, mail_from=nil, helo=nil, client_address=nil)
601
+ _params = {:raw_message => raw_message, :to => to, :mail_from => mail_from, :helo => helo, :client_address => client_address}
602
+ return @master.call 'inbound/send-raw', _params
603
+ end
604
+
605
+ end
606
+ class Tags
607
+ attr_accessor :master
608
+
609
+ def initialize(master)
610
+ @master = master
611
+ end
612
+
613
+ # Return all of the user-defined tag information
614
+ # @return [Array] a list of user-defined tags
615
+ # - [Hash] return[] a user-defined tag
616
+ # - [String] tag the actual tag as a string
617
+ # - [Integer] reputation the tag's current reputation on a scale from 0 to 100.
618
+ # - [Integer] sent the total number of messages sent with this tag
619
+ # - [Integer] hard_bounces the total number of hard bounces by messages with this tag
620
+ # - [Integer] soft_bounces the total number of soft bounces by messages with this tag
621
+ # - [Integer] rejects the total number of rejected messages with this tag
622
+ # - [Integer] complaints the total number of spam complaints received for messages with this tag
623
+ # - [Integer] unsubs the total number of unsubscribe requests received for messages with this tag
624
+ # - [Integer] opens the total number of times messages with this tag have been opened
625
+ # - [Integer] clicks the total number of times tracked URLs in messages with this tag have been clicked
626
+ # - [Integer] unique_opens the number of unique opens for emails sent with this tag
627
+ # - [Integer] unique_clicks the number of unique clicks for emails sent with this tag
628
+ def list()
629
+ _params = {}
630
+ return @master.call 'tags/list', _params
631
+ end
632
+
633
+ # Deletes a tag permanently. Deleting a tag removes the tag from any messages that have been sent, and also deletes the tag's stats. There is no way to undo this operation, so use it carefully.
634
+ # @param [String] tag a tag name
635
+ # @return [Hash] the tag that was deleted
636
+ # - [String] tag the actual tag as a string
637
+ # - [Integer] reputation the tag's current reputation on a scale from 0 to 100.
638
+ # - [Integer] sent the total number of messages sent with this tag
639
+ # - [Integer] hard_bounces the total number of hard bounces by messages with this tag
640
+ # - [Integer] soft_bounces the total number of soft bounces by messages with this tag
641
+ # - [Integer] rejects the total number of rejected messages with this tag
642
+ # - [Integer] complaints the total number of spam complaints received for messages with this tag
643
+ # - [Integer] unsubs the total number of unsubscribe requests received for messages with this tag
644
+ # - [Integer] opens the total number of times messages with this tag have been opened
645
+ # - [Integer] clicks the total number of times tracked URLs in messages with this tag have been clicked
646
+ # - [Integer] unique_opens the number of unique opens for emails sent with this tag
647
+ # - [Integer] unique_clicks the number of unique clicks for emails sent with this tag
648
+ def delete(tag)
649
+ _params = {:tag => tag}
650
+ return @master.call 'tags/delete', _params
651
+ end
652
+
653
+ # Return more detailed information about a single tag, including aggregates of recent stats
654
+ # @param [String] tag an existing tag name
655
+ # @return [Hash] the detailed information on the tag
656
+ # - [String] tag the actual tag as a string
657
+ # - [Integer] sent the total number of messages sent with this tag
658
+ # - [Integer] hard_bounces the total number of hard bounces by messages with this tag
659
+ # - [Integer] soft_bounces the total number of soft bounces by messages with this tag
660
+ # - [Integer] rejects the total number of rejected messages with this tag
661
+ # - [Integer] complaints the total number of spam complaints received for messages with this tag
662
+ # - [Integer] unsubs the total number of unsubscribe requests received for messages with this tag
663
+ # - [Integer] opens the total number of times messages with this tag have been opened
664
+ # - [Integer] clicks the total number of times tracked URLs in messages with this tag have been clicked
665
+ # - [Hash] stats an aggregate summary of the tag's sending stats
666
+ # - [Hash] today stats with this tag so far today
667
+ # - [Integer] sent the number of emails sent with this tag so far today
668
+ # - [Integer] hard_bounces the number of emails hard bounced with this tag so far today
669
+ # - [Integer] soft_bounces the number of emails soft bounced with this tag so far today
670
+ # - [Integer] rejects the number of emails rejected for sending this tag so far today
671
+ # - [Integer] complaints the number of spam complaints with this tag so far today
672
+ # - [Integer] unsubs the number of unsubscribes with this tag so far today
673
+ # - [Integer] opens the number of times emails have been opened with this tag so far today
674
+ # - [Integer] unique_opens the number of unique opens for emails sent with this tag so far today
675
+ # - [Integer] clicks the number of URLs that have been clicked with this tag so far today
676
+ # - [Integer] unique_clicks the number of unique clicks for emails sent with this tag so far today
677
+ # - [Hash] last_7_days stats with this tag in the last 7 days
678
+ # - [Integer] sent the number of emails sent with this tag in the last 7 days
679
+ # - [Integer] hard_bounces the number of emails hard bounced with this tag in the last 7 days
680
+ # - [Integer] soft_bounces the number of emails soft bounced with this tag in the last 7 days
681
+ # - [Integer] rejects the number of emails rejected for sending this tag in the last 7 days
682
+ # - [Integer] complaints the number of spam complaints with this tag in the last 7 days
683
+ # - [Integer] unsubs the number of unsubscribes with this tag in the last 7 days
684
+ # - [Integer] opens the number of times emails have been opened with this tag in the last 7 days
685
+ # - [Integer] unique_opens the number of unique opens for emails sent with this tag in the last 7 days
686
+ # - [Integer] clicks the number of URLs that have been clicked with this tag in the last 7 days
687
+ # - [Integer] unique_clicks the number of unique clicks for emails sent with this tag in the last 7 days
688
+ # - [Hash] last_30_days stats with this tag in the last 30 days
689
+ # - [Integer] sent the number of emails sent with this tag in the last 30 days
690
+ # - [Integer] hard_bounces the number of emails hard bounced with this tag in the last 30 days
691
+ # - [Integer] soft_bounces the number of emails soft bounced with this tag in the last 30 days
692
+ # - [Integer] rejects the number of emails rejected for sending this tag in the last 30 days
693
+ # - [Integer] complaints the number of spam complaints with this tag in the last 30 days
694
+ # - [Integer] unsubs the number of unsubscribes with this tag in the last 30 days
695
+ # - [Integer] opens the number of times emails have been opened with this tag in the last 30 days
696
+ # - [Integer] unique_opens the number of unique opens for emails sent with this tag in the last 30 days
697
+ # - [Integer] clicks the number of URLs that have been clicked with this tag in the last 30 days
698
+ # - [Integer] unique_clicks the number of unique clicks for emails sent with this tag in the last 30 days
699
+ # - [Hash] last_60_days stats with this tag in the last 60 days
700
+ # - [Integer] sent the number of emails sent with this tag in the last 60 days
701
+ # - [Integer] hard_bounces the number of emails hard bounced with this tag in the last 60 days
702
+ # - [Integer] soft_bounces the number of emails soft bounced with this tag in the last 60 days
703
+ # - [Integer] rejects the number of emails rejected for sending this tag in the last 60 days
704
+ # - [Integer] complaints the number of spam complaints with this tag in the last 60 days
705
+ # - [Integer] unsubs the number of unsubscribes with this tag in the last 60 days
706
+ # - [Integer] opens the number of times emails have been opened with this tag in the last 60 days
707
+ # - [Integer] unique_opens the number of unique opens for emails sent with this tag in the last 60 days
708
+ # - [Integer] clicks the number of URLs that have been clicked with this tag in the last 60 days
709
+ # - [Integer] unique_clicks the number of unique clicks for emails sent with this tag in the last 60 days
710
+ # - [Hash] last_90_days stats with this tag in the last 90 days
711
+ # - [Integer] sent the number of emails sent with this tag in the last 90 days
712
+ # - [Integer] hard_bounces the number of emails hard bounced with this tag in the last 90 days
713
+ # - [Integer] soft_bounces the number of emails soft bounced with this tag in the last 90 days
714
+ # - [Integer] rejects the number of emails rejected for sending this tag in the last 90 days
715
+ # - [Integer] complaints the number of spam complaints with this tag in the last 90 days
716
+ # - [Integer] unsubs the number of unsubscribes with this tag in the last 90 days
717
+ # - [Integer] opens the number of times emails have been opened with this tag in the last 90 days
718
+ # - [Integer] unique_opens the number of unique opens for emails sent with this tag in the last 90 days
719
+ # - [Integer] clicks the number of URLs that have been clicked with this tag in the last 90 days
720
+ # - [Integer] unique_clicks the number of unique clicks for emails sent with this tag in the last 90 days
721
+ def info(tag)
722
+ _params = {:tag => tag}
723
+ return @master.call 'tags/info', _params
724
+ end
725
+
726
+ # Return the recent history (hourly stats for the last 30 days) for a tag
727
+ # @param [String] tag an existing tag name
728
+ # @return [Array] the array of history information
729
+ # - [Hash] return[] the stats for a single hour
730
+ # - [String] time the hour as a UTC date string in YYYY-MM-DD HH:MM:SS format
731
+ # - [Integer] sent the number of emails that were sent during the hour
732
+ # - [Integer] hard_bounces the number of emails that hard bounced during the hour
733
+ # - [Integer] soft_bounces the number of emails that soft bounced during the hour
734
+ # - [Integer] rejects the number of emails that were rejected during the hour
735
+ # - [Integer] complaints the number of spam complaints received during the hour
736
+ # - [Integer] unsubs the number of unsubscribes received during the hour
737
+ # - [Integer] opens the number of emails opened during the hour
738
+ # - [Integer] unique_opens the number of unique opens generated by messages sent during the hour
739
+ # - [Integer] clicks the number of tracked URLs clicked during the hour
740
+ # - [Integer] unique_clicks the number of unique clicks generated by messages sent during the hour
741
+ def time_series(tag)
742
+ _params = {:tag => tag}
743
+ return @master.call 'tags/time-series', _params
744
+ end
745
+
746
+ # Return the recent history (hourly stats for the last 30 days) for all tags
747
+ # @return [Array] the array of history information
748
+ # - [Hash] return[] the stats for a single hour
749
+ # - [String] time the hour as a UTC date string in YYYY-MM-DD HH:MM:SS format
750
+ # - [Integer] sent the number of emails that were sent during the hour
751
+ # - [Integer] hard_bounces the number of emails that hard bounced during the hour
752
+ # - [Integer] soft_bounces the number of emails that soft bounced during the hour
753
+ # - [Integer] rejects the number of emails that were rejected during the hour
754
+ # - [Integer] complaints the number of spam complaints received during the hour
755
+ # - [Integer] unsubs the number of unsubscribes received during the hour
756
+ # - [Integer] opens the number of emails opened during the hour
757
+ # - [Integer] unique_opens the number of unique opens generated by messages sent during the hour
758
+ # - [Integer] clicks the number of tracked URLs clicked during the hour
759
+ # - [Integer] unique_clicks the number of unique clicks generated by messages sent during the hour
760
+ def all_time_series()
761
+ _params = {}
762
+ return @master.call 'tags/all-time-series', _params
763
+ end
764
+
765
+ end
766
+ class Messages
767
+ attr_accessor :master
768
+
769
+ def initialize(master)
770
+ @master = master
771
+ end
772
+
773
+ # Send a new transactional message through Mandrill
774
+ # @param [Hash] message the information on the message to send
775
+ # - [String] html the full HTML content to be sent
776
+ # - [String] text optional full text content to be sent
777
+ # - [String] subject the message subject
778
+ # - [String] from_email the sender email address.
779
+ # - [String] from_name optional from name to be used
780
+ # - [Array] to an array of recipient information.
781
+ # - [Hash] to[] a single recipient's information.
782
+ # - [String] email the email address of the recipient
783
+ # - [String] name the optional display name to use for the recipient
784
+ # - [String] type the header type to use for the recipient, defaults to "to" if not provided
785
+ # - [Hash] headers optional extra headers to add to the message (most headers are allowed)
786
+ # - [Boolean] important whether or not this message is important, and should be delivered ahead of non-important messages
787
+ # - [Boolean] track_opens whether or not to turn on open tracking for the message
788
+ # - [Boolean] track_clicks whether or not to turn on click tracking for the message
789
+ # - [Boolean] auto_text whether or not to automatically generate a text part for messages that are not given text
790
+ # - [Boolean] auto_html whether or not to automatically generate an HTML part for messages that are not given HTML
791
+ # - [Boolean] inline_css whether or not to automatically inline all CSS styles provided in the message HTML - only for HTML documents less than 256KB in size
792
+ # - [Boolean] url_strip_qs whether or not to strip the query string from URLs when aggregating tracked URL data
793
+ # - [Boolean] preserve_recipients whether or not to expose all recipients in to "To" header for each email
794
+ # - [Boolean] view_content_link set to false to remove content logging for sensitive emails
795
+ # - [String] bcc_address an optional address to receive an exact copy of each recipient's email
796
+ # - [String] tracking_domain a custom domain to use for tracking opens and clicks instead of mandrillapp.com
797
+ # - [String] signing_domain a custom domain to use for SPF/DKIM signing instead of mandrill (for "via" or "on behalf of" in email clients)
798
+ # - [String] return_path_domain a custom domain to use for the messages's return-path
799
+ # - [Boolean] merge whether to evaluate merge tags in the message. Will automatically be set to true if either merge_vars or global_merge_vars are provided.
800
+ # - [String] merge_language the merge tag language to use when evaluating merge tags, either mailchimp or handlebars
801
+ # - [Array] global_merge_vars global merge variables to use for all recipients. You can override these per recipient.
802
+ # - [Hash] global_merge_vars[] a single global merge variable
803
+ # - [String] name the global merge variable's name. Merge variable names are case-insensitive and may not start with _
804
+ # - [Mixed] content the global merge variable's content
805
+ # - [Array] merge_vars per-recipient merge variables, which override global merge variables with the same name.
806
+ # - [Hash] merge_vars[] per-recipient merge variables
807
+ # - [String] rcpt the email address of the recipient that the merge variables should apply to
808
+ # - [Array] vars the recipient's merge variables
809
+ # - [Hash] vars[] a single merge variable
810
+ # - [String] name the merge variable's name. Merge variable names are case-insensitive and may not start with _
811
+ # - [Mixed] content the merge variable's content
812
+ # - [Array] tags an array of string to tag the message with. Stats are accumulated using tags, though we only store the first 100 we see, so this should not be unique or change frequently. Tags should be 50 characters or less. Any tags starting with an underscore are reserved for internal use and will cause errors.
813
+ # - [String] tags[] a single tag - must not start with an underscore
814
+ # - [String] subaccount the unique id of a subaccount for this message - must already exist or will fail with an error
815
+ # - [Array] google_analytics_domains an array of strings indicating for which any matching URLs will automatically have Google Analytics parameters appended to their query string automatically.
816
+ # - [Array, String] google_analytics_campaign optional string indicating the value to set for the utm_campaign tracking parameter. If this isn't provided the email's from address will be used instead.
817
+ # - [Array] metadata metadata an associative array of user metadata. Mandrill will store this metadata and make it available for retrieval. In addition, you can select up to 10 metadata fields to index and make searchable using the Mandrill search api.
818
+ # - [Array] recipient_metadata Per-recipient metadata that will override the global values specified in the metadata parameter.
819
+ # - [Hash] recipient_metadata[] metadata for a single recipient
820
+ # - [String] rcpt the email address of the recipient that the metadata is associated with
821
+ # - [Array] values an associated array containing the recipient's unique metadata. If a key exists in both the per-recipient metadata and the global metadata, the per-recipient metadata will be used.
822
+ # - [Array] attachments an array of supported attachments to add to the message
823
+ # - [Hash] attachments[] a single supported attachment
824
+ # - [String] type the MIME type of the attachment
825
+ # - [String] name the file name of the attachment
826
+ # - [String] content the content of the attachment as a base64-encoded string
827
+ # - [Array] images an array of embedded images to add to the message
828
+ # - [Hash] images[] a single embedded image
829
+ # - [String] type the MIME type of the image - must start with "image/"
830
+ # - [String] name the Content ID of the image - use <img src="cid:THIS_VALUE"> to reference the image in your HTML content
831
+ # - [String] content the content of the image as a base64-encoded string
832
+ # @param [Boolean] async enable a background sending mode that is optimized for bulk sending. In async mode, messages/send will immediately return a status of "queued" for every recipient. To handle rejections when sending in async mode, set up a webhook for the 'reject' event. Defaults to false for messages with no more than 10 recipients; messages with more than 10 recipients are always sent asynchronously, regardless of the value of async.
833
+ # @param [String] ip_pool the name of the dedicated ip pool that should be used to send the message. If you do not have any dedicated IPs, this parameter has no effect. If you specify a pool that does not exist, your default pool will be used instead.
834
+ # @param [String] send_at when this message should be sent as a UTC timestamp in YYYY-MM-DD HH:MM:SS format. If you specify a time in the past, the message will be sent immediately. An additional fee applies for scheduled email, and this feature is only available to accounts with a positive balance.
835
+ # @return [Array] of structs for each recipient containing the key "email" with the email address, and details of the message status for that recipient
836
+ # - [Hash] return[] the sending results for a single recipient
837
+ # - [String] email the email address of the recipient
838
+ # - [String] status the sending status of the recipient - either "sent", "queued", "scheduled", "rejected", or "invalid"
839
+ # - [String] reject_reason the reason for the rejection if the recipient status is "rejected" - one of "hard-bounce", "soft-bounce", "spam", "unsub", "custom", "invalid-sender", "invalid", "test-mode-limit", or "rule"
840
+ # - [String] _id the message's unique id
841
+ def send(message, async=false, ip_pool=nil, send_at=nil)
842
+ _params = {:message => message, :async => async, :ip_pool => ip_pool, :send_at => send_at}
843
+ return @master.call 'messages/send', _params
844
+ end
845
+
846
+ # Send a new transactional message through Mandrill using a template
847
+ # @param [String] template_name the immutable name or slug of a template that exists in the user's account. For backwards-compatibility, the template name may also be used but the immutable slug is preferred.
848
+ # @param [Array] template_content an array of template content to send. Each item in the array should be a struct with two keys - name: the name of the content block to set the content for, and content: the actual content to put into the block
849
+ # - [Hash] template_content[] the injection of a single piece of content into a single editable region
850
+ # - [String] name the name of the mc:edit editable region to inject into
851
+ # - [String] content the content to inject
852
+ # @param [Hash] message the other information on the message to send - same as /messages/send, but without the html content
853
+ # - [String] html optional full HTML content to be sent if not in template
854
+ # - [String] text optional full text content to be sent
855
+ # - [String] subject the message subject
856
+ # - [String] from_email the sender email address.
857
+ # - [String] from_name optional from name to be used
858
+ # - [Array] to an array of recipient information.
859
+ # - [Hash] to[] a single recipient's information.
860
+ # - [String] email the email address of the recipient
861
+ # - [String] name the optional display name to use for the recipient
862
+ # - [String] type the header type to use for the recipient, defaults to "to" if not provided
863
+ # - [Hash] headers optional extra headers to add to the message (most headers are allowed)
864
+ # - [Boolean] important whether or not this message is important, and should be delivered ahead of non-important messages
865
+ # - [Boolean] track_opens whether or not to turn on open tracking for the message
866
+ # - [Boolean] track_clicks whether or not to turn on click tracking for the message
867
+ # - [Boolean] auto_text whether or not to automatically generate a text part for messages that are not given text
868
+ # - [Boolean] auto_html whether or not to automatically generate an HTML part for messages that are not given HTML
869
+ # - [Boolean] inline_css whether or not to automatically inline all CSS styles provided in the message HTML - only for HTML documents less than 256KB in size
870
+ # - [Boolean] url_strip_qs whether or not to strip the query string from URLs when aggregating tracked URL data
871
+ # - [Boolean] preserve_recipients whether or not to expose all recipients in to "To" header for each email
872
+ # - [Boolean] view_content_link set to false to remove content logging for sensitive emails
873
+ # - [String] bcc_address an optional address to receive an exact copy of each recipient's email
874
+ # - [String] tracking_domain a custom domain to use for tracking opens and clicks instead of mandrillapp.com
875
+ # - [String] signing_domain a custom domain to use for SPF/DKIM signing instead of mandrill (for "via" or "on behalf of" in email clients)
876
+ # - [String] return_path_domain a custom domain to use for the messages's return-path
877
+ # - [Boolean] merge whether to evaluate merge tags in the message. Will automatically be set to true if either merge_vars or global_merge_vars are provided.
878
+ # - [String] merge_language the merge tag language to use when evaluating merge tags, either mailchimp or handlebars
879
+ # - [Array] global_merge_vars global merge variables to use for all recipients. You can override these per recipient.
880
+ # - [Hash] global_merge_vars[] a single global merge variable
881
+ # - [String] name the global merge variable's name. Merge variable names are case-insensitive and may not start with _
882
+ # - [Mixed] content the global merge variable's content
883
+ # - [Array] merge_vars per-recipient merge variables, which override global merge variables with the same name.
884
+ # - [Hash] merge_vars[] per-recipient merge variables
885
+ # - [String] rcpt the email address of the recipient that the merge variables should apply to
886
+ # - [Array] vars the recipient's merge variables
887
+ # - [Hash] vars[] a single merge variable
888
+ # - [String] name the merge variable's name. Merge variable names are case-insensitive and may not start with _
889
+ # - [Mixed] content the merge variable's content
890
+ # - [Array] tags an array of string to tag the message with. Stats are accumulated using tags, though we only store the first 100 we see, so this should not be unique or change frequently. Tags should be 50 characters or less. Any tags starting with an underscore are reserved for internal use and will cause errors.
891
+ # - [String] tags[] a single tag - must not start with an underscore
892
+ # - [String] subaccount the unique id of a subaccount for this message - must already exist or will fail with an error
893
+ # - [Array] google_analytics_domains an array of strings indicating for which any matching URLs will automatically have Google Analytics parameters appended to their query string automatically.
894
+ # - [Array, String] google_analytics_campaign optional string indicating the value to set for the utm_campaign tracking parameter. If this isn't provided the email's from address will be used instead.
895
+ # - [Array] metadata metadata an associative array of user metadata. Mandrill will store this metadata and make it available for retrieval. In addition, you can select up to 10 metadata fields to index and make searchable using the Mandrill search api.
896
+ # - [Array] recipient_metadata Per-recipient metadata that will override the global values specified in the metadata parameter.
897
+ # - [Hash] recipient_metadata[] metadata for a single recipient
898
+ # - [String] rcpt the email address of the recipient that the metadata is associated with
899
+ # - [Array] values an associated array containing the recipient's unique metadata. If a key exists in both the per-recipient metadata and the global metadata, the per-recipient metadata will be used.
900
+ # - [Array] attachments an array of supported attachments to add to the message
901
+ # - [Hash] attachments[] a single supported attachment
902
+ # - [String] type the MIME type of the attachment
903
+ # - [String] name the file name of the attachment
904
+ # - [String] content the content of the attachment as a base64-encoded string
905
+ # - [Array] images an array of embedded images to add to the message
906
+ # - [Hash] images[] a single embedded image
907
+ # - [String] type the MIME type of the image - must start with "image/"
908
+ # - [String] name the Content ID of the image - use <img src="cid:THIS_VALUE"> to reference the image in your HTML content
909
+ # - [String] content the content of the image as a base64-encoded string
910
+ # @param [Boolean] async enable a background sending mode that is optimized for bulk sending. In async mode, messages/send will immediately return a status of "queued" for every recipient. To handle rejections when sending in async mode, set up a webhook for the 'reject' event. Defaults to false for messages with no more than 10 recipients; messages with more than 10 recipients are always sent asynchronously, regardless of the value of async.
911
+ # @param [String] ip_pool the name of the dedicated ip pool that should be used to send the message. If you do not have any dedicated IPs, this parameter has no effect. If you specify a pool that does not exist, your default pool will be used instead.
912
+ # @param [String] send_at when this message should be sent as a UTC timestamp in YYYY-MM-DD HH:MM:SS format. If you specify a time in the past, the message will be sent immediately. An additional fee applies for scheduled email, and this feature is only available to accounts with a positive balance.
913
+ # @return [Array] of structs for each recipient containing the key "email" with the email address, and details of the message status for that recipient
914
+ # - [Hash] return[] the sending results for a single recipient
915
+ # - [String] email the email address of the recipient
916
+ # - [String] status the sending status of the recipient - either "sent", "queued", "rejected", or "invalid"
917
+ # - [String] reject_reason the reason for the rejection if the recipient status is "rejected" - one of "hard-bounce", "soft-bounce", "spam", "unsub", "custom", "invalid-sender", "invalid", "test-mode-limit", or "rule"
918
+ # - [String] _id the message's unique id
919
+ def send_template(template_name, template_content, message, async=false, ip_pool=nil, send_at=nil)
920
+ _params = {:template_name => template_name, :template_content => template_content, :message => message, :async => async, :ip_pool => ip_pool, :send_at => send_at}
921
+ return @master.call 'messages/send-template', _params
922
+ end
923
+
924
+ # Search recently sent messages and optionally narrow by date range, tags, senders, and API keys. If no date range is specified, results within the last 7 days are returned. This method may be called up to 20 times per minute. If you need the data more often, you can use <a href="/api/docs/messages.html#method=info">/messages/info.json</a> to get the information for a single message, or <a href="http://help.mandrill.com/entries/21738186-Introduction-to-Webhooks">webhooks</a> to push activity to your own application for querying.
925
+ # @param [String] query <a href="http://help.mandrill.com/entries/22211902">search terms</a> to find matching messages
926
+ # @param [String] date_from start date
927
+ # @param [String] date_to end date
928
+ # @param [Array] tags an array of tag names to narrow the search to, will return messages that contain ANY of the tags
929
+ # @param [Array] senders an array of sender addresses to narrow the search to, will return messages sent by ANY of the senders
930
+ # @param [Array] api_keys an array of API keys to narrow the search to, will return messages sent by ANY of the keys
931
+ # @param [Integer] limit the maximum number of results to return, defaults to 100, 1000 is the maximum
932
+ # @return [Array] of structs for each matching message
933
+ # - [Hash] return[] the information for a single matching message
934
+ # - [Integer] ts the Unix timestamp from when this message was sent
935
+ # - [String] _id the message's unique id
936
+ # - [String] sender the email address of the sender
937
+ # - [String] template the unique name of the template used, if any
938
+ # - [String] subject the message's subject line
939
+ # - [String] email the recipient email address
940
+ # - [Array] tags list of tags on this message
941
+ # - [String] tags[] individual tag on this message
942
+ # - [Integer] opens how many times has this message been opened
943
+ # - [Array] opens_detail list of individual opens for the message
944
+ # - [Hash] opens_detail[] information on an individual open
945
+ # - [Integer] ts the unix timestamp from when the message was opened
946
+ # - [String] ip the IP address that generated the open
947
+ # - [String] location the approximate region and country that the opening IP is located
948
+ # - [String] ua the email client or browser data of the open
949
+ # - [Integer] clicks how many times has a link been clicked in this message
950
+ # - [Array] clicks_detail list of individual clicks for the message
951
+ # - [Hash] clicks_detail[] information on an individual click
952
+ # - [Integer] ts the unix timestamp from when the message was clicked
953
+ # - [String] url the URL that was clicked on
954
+ # - [String] ip the IP address that generated the click
955
+ # - [String] location the approximate region and country that the clicking IP is located
956
+ # - [String] ua the email client or browser data of the click
957
+ # - [String] state sending status of this message: sent, bounced, rejected
958
+ # - [Hash] metadata any custom metadata provided when the message was sent
959
+ # - [Array] smtp_events a log of up to 3 smtp events for the message
960
+ # - [Hash] smtp_events[] information about a specific smtp event
961
+ # - [Integer] ts the Unix timestamp when the event occured
962
+ # - [String] type the message's state as a result of this event
963
+ # - [String] diag the SMTP response from the recipient's server
964
+ def search(query='*', date_from=nil, date_to=nil, tags=nil, senders=nil, api_keys=nil, limit=100)
965
+ _params = {:query => query, :date_from => date_from, :date_to => date_to, :tags => tags, :senders => senders, :api_keys => api_keys, :limit => limit}
966
+ return @master.call 'messages/search', _params
967
+ end
968
+
969
+ # Search the content of recently sent messages and return the aggregated hourly stats for matching messages
970
+ # @param [String] query the search terms to find matching messages for
971
+ # @param [String] date_from start date
972
+ # @param [String] date_to end date
973
+ # @param [Array] tags an array of tag names to narrow the search to, will return messages that contain ANY of the tags
974
+ # @param [Array] senders an array of sender addresses to narrow the search to, will return messages sent by ANY of the senders
975
+ # @return [Array] the array of history information
976
+ # - [Hash] return[] the stats for a single hour
977
+ # - [String] time the hour as a UTC date string in YYYY-MM-DD HH:MM:SS format
978
+ # - [Integer] sent the number of emails that were sent during the hour
979
+ # - [Integer] hard_bounces the number of emails that hard bounced during the hour
980
+ # - [Integer] soft_bounces the number of emails that soft bounced during the hour
981
+ # - [Integer] rejects the number of emails that were rejected during the hour
982
+ # - [Integer] complaints the number of spam complaints received during the hour
983
+ # - [Integer] unsubs the number of unsubscribes received during the hour
984
+ # - [Integer] opens the number of emails opened during the hour
985
+ # - [Integer] unique_opens the number of unique opens generated by messages sent during the hour
986
+ # - [Integer] clicks the number of tracked URLs clicked during the hour
987
+ # - [Integer] unique_clicks the number of unique clicks generated by messages sent during the hour
988
+ def search_time_series(query='*', date_from=nil, date_to=nil, tags=nil, senders=nil)
989
+ _params = {:query => query, :date_from => date_from, :date_to => date_to, :tags => tags, :senders => senders}
990
+ return @master.call 'messages/search-time-series', _params
991
+ end
992
+
993
+ # Get the information for a single recently sent message
994
+ # @param [String] id the unique id of the message to get - passed as the "_id" field in webhooks, send calls, or search calls
995
+ # @return [Hash] the information for the message
996
+ # - [Integer] ts the Unix timestamp from when this message was sent
997
+ # - [String] _id the message's unique id
998
+ # - [String] sender the email address of the sender
999
+ # - [String] template the unique name of the template used, if any
1000
+ # - [String] subject the message's subject line
1001
+ # - [String] email the recipient email address
1002
+ # - [Array] tags list of tags on this message
1003
+ # - [String] tags[] individual tag on this message
1004
+ # - [Integer] opens how many times has this message been opened
1005
+ # - [Array] opens_detail list of individual opens for the message
1006
+ # - [Hash] opens_detail[] information on an individual open
1007
+ # - [Integer] ts the unix timestamp from when the message was opened
1008
+ # - [String] ip the IP address that generated the open
1009
+ # - [String] location the approximate region and country that the opening IP is located
1010
+ # - [String] ua the email client or browser data of the open
1011
+ # - [Integer] clicks how many times has a link been clicked in this message
1012
+ # - [Array] clicks_detail list of individual clicks for the message
1013
+ # - [Hash] clicks_detail[] information on an individual click
1014
+ # - [Integer] ts the unix timestamp from when the message was clicked
1015
+ # - [String] url the URL that was clicked on
1016
+ # - [String] ip the IP address that generated the click
1017
+ # - [String] location the approximate region and country that the clicking IP is located
1018
+ # - [String] ua the email client or browser data of the click
1019
+ # - [String] state sending status of this message: sent, bounced, rejected
1020
+ # - [Hash] metadata any custom metadata provided when the message was sent
1021
+ # - [Array] smtp_events a log of up to 3 smtp events for the message
1022
+ # - [Hash] smtp_events[] information about a specific smtp event
1023
+ # - [Integer] ts the Unix timestamp when the event occured
1024
+ # - [String] type the message's state as a result of this event
1025
+ # - [String] diag the SMTP response from the recipient's server
1026
+ def info(id)
1027
+ _params = {:id => id}
1028
+ return @master.call 'messages/info', _params
1029
+ end
1030
+
1031
+ # Get the full content of a recently sent message
1032
+ # @param [String] id the unique id of the message to get - passed as the "_id" field in webhooks, send calls, or search calls
1033
+ # @return [Hash] the content of the message
1034
+ # - [Integer] ts the Unix timestamp from when this message was sent
1035
+ # - [String] _id the message's unique id
1036
+ # - [String] from_email the email address of the sender
1037
+ # - [String] from_name the alias of the sender (if any)
1038
+ # - [String] subject the message's subject line
1039
+ # - [Hash] to the message recipient's information
1040
+ # - [String] email the email address of the recipient
1041
+ # - [String] name the alias of the recipient (if any)
1042
+ # - [Array] tags list of tags on this message
1043
+ # - [String] tags[] individual tag on this message
1044
+ # - [Hash] headers the key-value pairs of the custom MIME headers for the message's main document
1045
+ # - [String] text the text part of the message, if any
1046
+ # - [String] html the HTML part of the message, if any
1047
+ # - [Array] attachments an array of any attachments that can be found in the message
1048
+ # - [Hash] attachments[] information about an individual attachment
1049
+ # - [String] name the file name of the attachment
1050
+ # - [String] type the MIME type of the attachment
1051
+ # - [String] content the content of the attachment as a base64 encoded string
1052
+ def content(id)
1053
+ _params = {:id => id}
1054
+ return @master.call 'messages/content', _params
1055
+ end
1056
+
1057
+ # Parse the full MIME document for an email message, returning the content of the message broken into its constituent pieces
1058
+ # @param [String] raw_message the full MIME document of an email message
1059
+ # @return [Hash] the parsed message
1060
+ # - [String] subject the subject of the message
1061
+ # - [String] from_email the email address of the sender
1062
+ # - [String] from_name the alias of the sender (if any)
1063
+ # - [Array] to an array of any recipients in the message
1064
+ # - [Hash] to[] the information on a single recipient
1065
+ # - [String] email the email address of the recipient
1066
+ # - [String] name the alias of the recipient (if any)
1067
+ # - [Hash] headers the key-value pairs of the MIME headers for the message's main document
1068
+ # - [String] text the text part of the message, if any
1069
+ # - [String] html the HTML part of the message, if any
1070
+ # - [Array] attachments an array of any attachments that can be found in the message
1071
+ # - [Hash] attachments[] information about an individual attachment
1072
+ # - [String] name the file name of the attachment
1073
+ # - [String] type the MIME type of the attachment
1074
+ # - [Boolean] binary if this is set to true, the attachment is not pure-text, and the content will be base64 encoded
1075
+ # - [String] content the content of the attachment as a text string or a base64 encoded string based on the attachment type
1076
+ # - [Array] images an array of any embedded images that can be found in the message
1077
+ # - [Hash] images[] information about an individual image
1078
+ # - [String] name the Content-ID of the embedded image
1079
+ # - [String] type the MIME type of the image
1080
+ # - [String] content the content of the image as a base64 encoded string
1081
+ def parse(raw_message)
1082
+ _params = {:raw_message => raw_message}
1083
+ return @master.call 'messages/parse', _params
1084
+ end
1085
+
1086
+ # Take a raw MIME document for a message, and send it exactly as if it were sent through Mandrill's SMTP servers
1087
+ # @param [String] raw_message the full MIME document of an email message
1088
+ # @param [String, nil] from_email optionally define the sender address - otherwise we'll use the address found in the provided headers
1089
+ # @param [String, nil] from_name optionally define the sender alias
1090
+ # @param [Array, nil] to optionally define the recipients to receive the message - otherwise we'll use the To, Cc, and Bcc headers provided in the document
1091
+ # - [String] to[] the email address of the recipient
1092
+ # @param [Boolean] async enable a background sending mode that is optimized for bulk sending. In async mode, messages/sendRaw will immediately return a status of "queued" for every recipient. To handle rejections when sending in async mode, set up a webhook for the 'reject' event. Defaults to false for messages with no more than 10 recipients; messages with more than 10 recipients are always sent asynchronously, regardless of the value of async.
1093
+ # @param [String] ip_pool the name of the dedicated ip pool that should be used to send the message. If you do not have any dedicated IPs, this parameter has no effect. If you specify a pool that does not exist, your default pool will be used instead.
1094
+ # @param [String] send_at when this message should be sent as a UTC timestamp in YYYY-MM-DD HH:MM:SS format. If you specify a time in the past, the message will be sent immediately.
1095
+ # @param [String] return_path_domain a custom domain to use for the messages's return-path
1096
+ # @return [Array] of structs for each recipient containing the key "email" with the email address, and details of the message status for that recipient
1097
+ # - [Hash] return[] the sending results for a single recipient
1098
+ # - [String] email the email address of the recipient
1099
+ # - [String] status the sending status of the recipient - either "sent", "queued", "scheduled", "rejected", or "invalid"
1100
+ # - [String] reject_reason the reason for the rejection if the recipient status is "rejected" - one of "hard-bounce", "soft-bounce", "spam", "unsub", "custom", "invalid-sender", "invalid", "test-mode-limit", or "rule"
1101
+ # - [String] _id the message's unique id
1102
+ def send_raw(raw_message, from_email=nil, from_name=nil, to=nil, async=false, ip_pool=nil, send_at=nil, return_path_domain=nil)
1103
+ _params = {:raw_message => raw_message, :from_email => from_email, :from_name => from_name, :to => to, :async => async, :ip_pool => ip_pool, :send_at => send_at, :return_path_domain => return_path_domain}
1104
+ return @master.call 'messages/send-raw', _params
1105
+ end
1106
+
1107
+ # Queries your scheduled emails.
1108
+ # @param [String] to an optional recipient address to restrict results to
1109
+ # @return [Array] a list of up to 1000 scheduled emails
1110
+ # - [Hash] return[] a scheduled email
1111
+ # - [String] _id the scheduled message id
1112
+ # - [String] created_at the UTC timestamp when the message was created, in YYYY-MM-DD HH:MM:SS format
1113
+ # - [String] send_at the UTC timestamp when the message will be sent, in YYYY-MM-DD HH:MM:SS format
1114
+ # - [String] from_email the email's sender address
1115
+ # - [String] to the email's recipient
1116
+ # - [String] subject the email's subject
1117
+ def list_scheduled(to=nil)
1118
+ _params = {:to => to}
1119
+ return @master.call 'messages/list-scheduled', _params
1120
+ end
1121
+
1122
+ # Cancels a scheduled email.
1123
+ # @param [String] id a scheduled email id, as returned by any of the messages/send calls or messages/list-scheduled
1124
+ # @return [Hash] information about the scheduled email that was cancelled.
1125
+ # - [String] _id the scheduled message id
1126
+ # - [String] created_at the UTC timestamp when the message was created, in YYYY-MM-DD HH:MM:SS format
1127
+ # - [String] send_at the UTC timestamp when the message will be sent, in YYYY-MM-DD HH:MM:SS format
1128
+ # - [String] from_email the email's sender address
1129
+ # - [String] to the email's recipient
1130
+ # - [String] subject the email's subject
1131
+ def cancel_scheduled(id)
1132
+ _params = {:id => id}
1133
+ return @master.call 'messages/cancel-scheduled', _params
1134
+ end
1135
+
1136
+ # Reschedules a scheduled email.
1137
+ # @param [String] id a scheduled email id, as returned by any of the messages/send calls or messages/list-scheduled
1138
+ # @param [String] send_at the new UTC timestamp when the message should sent. Mandrill can't time travel, so if you specify a time in past the message will be sent immediately
1139
+ # @return [Hash] information about the scheduled email that was rescheduled.
1140
+ # - [String] _id the scheduled message id
1141
+ # - [String] created_at the UTC timestamp when the message was created, in YYYY-MM-DD HH:MM:SS format
1142
+ # - [String] send_at the UTC timestamp when the message will be sent, in YYYY-MM-DD HH:MM:SS format
1143
+ # - [String] from_email the email's sender address
1144
+ # - [String] to the email's recipient
1145
+ # - [String] subject the email's subject
1146
+ def reschedule(id, send_at)
1147
+ _params = {:id => id, :send_at => send_at}
1148
+ return @master.call 'messages/reschedule', _params
1149
+ end
1150
+
1151
+ end
1152
+ class Whitelists
1153
+ attr_accessor :master
1154
+
1155
+ def initialize(master)
1156
+ @master = master
1157
+ end
1158
+
1159
+ # Adds an email to your email rejection whitelist. If the address is currently on your blacklist, that blacklist entry will be removed automatically.
1160
+ # @param [String] email an email address to add to the whitelist
1161
+ # @param [String] comment an optional description of why the email was whitelisted
1162
+ # @return [Hash] a status object containing the address and the result of the operation
1163
+ # - [String] email the email address you provided
1164
+ # - [Boolean] added whether the operation succeeded
1165
+ def add(email, comment=nil)
1166
+ _params = {:email => email, :comment => comment}
1167
+ return @master.call 'whitelists/add', _params
1168
+ end
1169
+
1170
+ # Retrieves your email rejection whitelist. You can provide an email address or search prefix to limit the results. Returns up to 1000 results.
1171
+ # @param [String] email an optional email address or prefix to search by
1172
+ # @return [Array] up to 1000 whitelist entries
1173
+ # - [Hash] return[] the information for each whitelist entry
1174
+ # - [String] email the email that is whitelisted
1175
+ # - [String] detail a description of why the email was whitelisted
1176
+ # - [String] created_at when the email was added to the whitelist
1177
+ def list(email=nil)
1178
+ _params = {:email => email}
1179
+ return @master.call 'whitelists/list', _params
1180
+ end
1181
+
1182
+ # Removes an email address from the whitelist.
1183
+ # @param [String] email the email address to remove from the whitelist
1184
+ # @return [Hash] a status object containing the address and whether the deletion succeeded
1185
+ # - [String] email the email address that was removed from the blacklist
1186
+ # - [Boolean] deleted whether the address was deleted successfully
1187
+ def delete(email)
1188
+ _params = {:email => email}
1189
+ return @master.call 'whitelists/delete', _params
1190
+ end
1191
+
1192
+ end
1193
+ class Ips
1194
+ attr_accessor :master
1195
+
1196
+ def initialize(master)
1197
+ @master = master
1198
+ end
1199
+
1200
+ # Lists your dedicated IPs.
1201
+ # @return [Array] an array of structs for each dedicated IP
1202
+ # - [Hash] return[] information about a single dedicated IP
1203
+ # - [String] ip the ip address
1204
+ # - [String] created_at the date and time that the dedicated IP was created as a UTC string in YYYY-MM-DD HH:MM:SS format
1205
+ # - [String] pool the name of the pool that this dedicated IP belongs to
1206
+ # - [String] domain the domain name (reverse dns) of this dedicated IP
1207
+ # - [Hash] custom_dns information about the ip's custom dns, if it has been configured
1208
+ # - [Boolean] enabled a boolean indicating whether custom dns has been configured for this ip
1209
+ # - [Boolean] valid whether the ip's custom dns is currently valid
1210
+ # - [String] error if the ip's custom dns is invalid, this will include details about the error
1211
+ # - [Hash] warmup information about the ip's warmup status
1212
+ # - [Boolean] warming_up whether the ip is currently in warmup mode
1213
+ # - [String] start_at the start time for the warmup process as a UTC string in YYYY-MM-DD HH:MM:SS format
1214
+ # - [String] end_at the end date and time for the warmup process as a UTC string in YYYY-MM-DD HH:MM:SS format
1215
+ def list()
1216
+ _params = {}
1217
+ return @master.call 'ips/list', _params
1218
+ end
1219
+
1220
+ # Retrieves information about a single dedicated ip.
1221
+ # @param [String] ip a dedicated IP address
1222
+ # @return [Hash] Information about the dedicated ip
1223
+ # - [String] ip the ip address
1224
+ # - [String] created_at the date and time that the dedicated IP was created as a UTC string in YYYY-MM-DD HH:MM:SS format
1225
+ # - [String] pool the name of the pool that this dedicated IP belongs to
1226
+ # - [String] domain the domain name (reverse dns) of this dedicated IP
1227
+ # - [Hash] custom_dns information about the ip's custom dns, if it has been configured
1228
+ # - [Boolean] enabled a boolean indicating whether custom dns has been configured for this ip
1229
+ # - [Boolean] valid whether the ip's custom dns is currently valid
1230
+ # - [String] error if the ip's custom dns is invalid, this will include details about the error
1231
+ # - [Hash] warmup information about the ip's warmup status
1232
+ # - [Boolean] warming_up whether the ip is currently in warmup mode
1233
+ # - [String] start_at the start time for the warmup process as a UTC string in YYYY-MM-DD HH:MM:SS format
1234
+ # - [String] end_at the end date and time for the warmup process as a UTC string in YYYY-MM-DD HH:MM:SS format
1235
+ def info(ip)
1236
+ _params = {:ip => ip}
1237
+ return @master.call 'ips/info', _params
1238
+ end
1239
+
1240
+ # Requests an additional dedicated IP for your account. Accounts may have one outstanding request at any time, and provisioning requests are processed within 24 hours.
1241
+ # @param [Boolean] warmup whether to enable warmup mode for the ip
1242
+ # @param [String] pool the id of the pool to add the dedicated ip to, or null to use your account's default pool
1243
+ # @return [Hash] a description of the provisioning request that was created
1244
+ # - [String] requested_at the date and time that the request was created as a UTC timestamp in YYYY-MM-DD HH:MM:SS format
1245
+ def provision(warmup=false, pool=nil)
1246
+ _params = {:warmup => warmup, :pool => pool}
1247
+ return @master.call 'ips/provision', _params
1248
+ end
1249
+
1250
+ # Begins the warmup process for a dedicated IP. During the warmup process, Mandrill will gradually increase the percentage of your mail that is sent over the warming-up IP, over a period of roughly 30 days. The rest of your mail will be sent over shared IPs or other dedicated IPs in the same pool.
1251
+ # @param [String] ip a dedicated ip address
1252
+ # @return [Hash] Information about the dedicated IP
1253
+ # - [String] ip the ip address
1254
+ # - [String] created_at the date and time that the dedicated IP was created as a UTC string in YYYY-MM-DD HH:MM:SS format
1255
+ # - [String] pool the name of the pool that this dedicated IP belongs to
1256
+ # - [String] domain the domain name (reverse dns) of this dedicated IP
1257
+ # - [Hash] custom_dns information about the ip's custom dns, if it has been configured
1258
+ # - [Boolean] enabled a boolean indicating whether custom dns has been configured for this ip
1259
+ # - [Boolean] valid whether the ip's custom dns is currently valid
1260
+ # - [String] error if the ip's custom dns is invalid, this will include details about the error
1261
+ # - [Hash] warmup information about the ip's warmup status
1262
+ # - [Boolean] warming_up whether the ip is currently in warmup mode
1263
+ # - [String] start_at the start time for the warmup process as a UTC string in YYYY-MM-DD HH:MM:SS format
1264
+ # - [String] end_at the end date and time for the warmup process as a UTC string in YYYY-MM-DD HH:MM:SS format
1265
+ def start_warmup(ip)
1266
+ _params = {:ip => ip}
1267
+ return @master.call 'ips/start-warmup', _params
1268
+ end
1269
+
1270
+ # Cancels the warmup process for a dedicated IP.
1271
+ # @param [String] ip a dedicated ip address
1272
+ # @return [Hash] Information about the dedicated IP
1273
+ # - [String] ip the ip address
1274
+ # - [String] created_at the date and time that the dedicated IP was created as a UTC string in YYYY-MM-DD HH:MM:SS format
1275
+ # - [String] pool the name of the pool that this dedicated IP belongs to
1276
+ # - [String] domain the domain name (reverse dns) of this dedicated IP
1277
+ # - [Hash] custom_dns information about the ip's custom dns, if it has been configured
1278
+ # - [Boolean] enabled a boolean indicating whether custom dns has been configured for this ip
1279
+ # - [Boolean] valid whether the ip's custom dns is currently valid
1280
+ # - [String] error if the ip's custom dns is invalid, this will include details about the error
1281
+ # - [Hash] warmup information about the ip's warmup status
1282
+ # - [Boolean] warming_up whether the ip is currently in warmup mode
1283
+ # - [String] start_at the start time for the warmup process as a UTC string in YYYY-MM-DD HH:MM:SS format
1284
+ # - [String] end_at the end date and time for the warmup process as a UTC string in YYYY-MM-DD HH:MM:SS format
1285
+ def cancel_warmup(ip)
1286
+ _params = {:ip => ip}
1287
+ return @master.call 'ips/cancel-warmup', _params
1288
+ end
1289
+
1290
+ # Moves a dedicated IP to a different pool.
1291
+ # @param [String] ip a dedicated ip address
1292
+ # @param [String] pool the name of the new pool to add the dedicated ip to
1293
+ # @param [Boolean] create_pool whether to create the pool if it does not exist; if false and the pool does not exist, an Unknown_Pool will be thrown.
1294
+ # @return [Hash] Information about the updated state of the dedicated IP
1295
+ # - [String] ip the ip address
1296
+ # - [String] created_at the date and time that the dedicated IP was created as a UTC string in YYYY-MM-DD HH:MM:SS format
1297
+ # - [String] pool the name of the pool that this dedicated IP belongs to
1298
+ # - [String] domain the domain name (reverse dns) of this dedicated IP
1299
+ # - [Hash] custom_dns information about the ip's custom dns, if it has been configured
1300
+ # - [Boolean] enabled a boolean indicating whether custom dns has been configured for this ip
1301
+ # - [Boolean] valid whether the ip's custom dns is currently valid
1302
+ # - [String] error if the ip's custom dns is invalid, this will include details about the error
1303
+ # - [Hash] warmup information about the ip's warmup status
1304
+ # - [Boolean] warming_up whether the ip is currently in warmup mode
1305
+ # - [String] start_at the start time for the warmup process as a UTC string in YYYY-MM-DD HH:MM:SS format
1306
+ # - [String] end_at the end date and time for the warmup process as a UTC string in YYYY-MM-DD HH:MM:SS format
1307
+ def set_pool(ip, pool, create_pool=false)
1308
+ _params = {:ip => ip, :pool => pool, :create_pool => create_pool}
1309
+ return @master.call 'ips/set-pool', _params
1310
+ end
1311
+
1312
+ # Deletes a dedicated IP. This is permanent and cannot be undone.
1313
+ # @param [String] ip the dedicated ip to remove from your account
1314
+ # @return [Hash] a description of the ip that was removed from your account.
1315
+ # - [String] ip the ip address
1316
+ # - [String] deleted a boolean indicating whether the ip was successfully deleted
1317
+ def delete(ip)
1318
+ _params = {:ip => ip}
1319
+ return @master.call 'ips/delete', _params
1320
+ end
1321
+
1322
+ # Lists your dedicated IP pools.
1323
+ # @return [Array] the dedicated IP pools for your account, up to a maximum of 1,000
1324
+ # - [Hash] return[] information about each dedicated IP pool
1325
+ # - [String] name this pool's name
1326
+ # - [String] created_at the date and time that this pool was created as a UTC timestamp in YYYY-MM-DD HH:MM:SS format
1327
+ # - [Array] ips the dedicated IPs in this pool
1328
+ # - [Hash] ips[] information about each dedicated IP
1329
+ # - [String] ip the ip address
1330
+ # - [String] created_at the date and time that the dedicated IP was created as a UTC string in YYYY-MM-DD HH:MM:SS format
1331
+ # - [String] pool the name of the pool that this dedicated IP belongs to
1332
+ # - [String] domain the domain name (reverse dns) of this dedicated IP
1333
+ # - [Hash] custom_dns information about the ip's custom dns, if it has been configured
1334
+ # - [Boolean] enabled a boolean indicating whether custom dns has been configured for this ip
1335
+ # - [Boolean] valid whether the ip's custom dns is currently valid
1336
+ # - [String] error if the ip's custom dns is invalid, this will include details about the error
1337
+ # - [Hash] warmup information about the ip's warmup status
1338
+ # - [Boolean] warming_up whether the ip is currently in warmup mode
1339
+ # - [String] start_at the start time for the warmup process as a UTC string in YYYY-MM-DD HH:MM:SS format
1340
+ # - [String] end_at the end date and time for the warmup process as a UTC string in YYYY-MM-DD HH:MM:SS format
1341
+ def list_pools()
1342
+ _params = {}
1343
+ return @master.call 'ips/list-pools', _params
1344
+ end
1345
+
1346
+ # Describes a single dedicated IP pool.
1347
+ # @param [String] pool a pool name
1348
+ # @return [Hash] Information about the dedicated ip pool
1349
+ # - [String] name this pool's name
1350
+ # - [String] created_at the date and time that this pool was created as a UTC timestamp in YYYY-MM-DD HH:MM:SS format
1351
+ # - [Array] ips the dedicated IPs in this pool
1352
+ # - [Hash] ips[] information about each dedicated IP
1353
+ # - [String] ip the ip address
1354
+ # - [String] created_at the date and time that the dedicated IP was created as a UTC string in YYYY-MM-DD HH:MM:SS format
1355
+ # - [String] pool the name of the pool that this dedicated IP belongs to
1356
+ # - [String] domain the domain name (reverse dns) of this dedicated IP
1357
+ # - [Hash] custom_dns information about the ip's custom dns, if it has been configured
1358
+ # - [Boolean] enabled a boolean indicating whether custom dns has been configured for this ip
1359
+ # - [Boolean] valid whether the ip's custom dns is currently valid
1360
+ # - [String] error if the ip's custom dns is invalid, this will include details about the error
1361
+ # - [Hash] warmup information about the ip's warmup status
1362
+ # - [Boolean] warming_up whether the ip is currently in warmup mode
1363
+ # - [String] start_at the start time for the warmup process as a UTC string in YYYY-MM-DD HH:MM:SS format
1364
+ # - [String] end_at the end date and time for the warmup process as a UTC string in YYYY-MM-DD HH:MM:SS format
1365
+ def pool_info(pool)
1366
+ _params = {:pool => pool}
1367
+ return @master.call 'ips/pool-info', _params
1368
+ end
1369
+
1370
+ # Creates a pool and returns it. If a pool already exists with this name, no action will be performed.
1371
+ # @param [String] pool the name of a pool to create
1372
+ # @return [Hash] Information about the dedicated ip pool
1373
+ # - [String] name this pool's name
1374
+ # - [String] created_at the date and time that this pool was created as a UTC timestamp in YYYY-MM-DD HH:MM:SS format
1375
+ # - [Array] ips the dedicated IPs in this pool
1376
+ # - [Hash] ips[] information about each dedicated IP
1377
+ # - [String] ip the ip address
1378
+ # - [String] created_at the date and time that the dedicated IP was created as a UTC string in YYYY-MM-DD HH:MM:SS format
1379
+ # - [String] pool the name of the pool that this dedicated IP belongs to
1380
+ # - [String] domain the domain name (reverse dns) of this dedicated IP
1381
+ # - [Hash] custom_dns information about the ip's custom dns, if it has been configured
1382
+ # - [Boolean] enabled a boolean indicating whether custom dns has been configured for this ip
1383
+ # - [Boolean] valid whether the ip's custom dns is currently valid
1384
+ # - [String] error if the ip's custom dns is invalid, this will include details about the error
1385
+ # - [Hash] warmup information about the ip's warmup status
1386
+ # - [Boolean] warming_up whether the ip is currently in warmup mode
1387
+ # - [String] start_at the start time for the warmup process as a UTC string in YYYY-MM-DD HH:MM:SS format
1388
+ # - [String] end_at the end date and time for the warmup process as a UTC string in YYYY-MM-DD HH:MM:SS format
1389
+ def create_pool(pool)
1390
+ _params = {:pool => pool}
1391
+ return @master.call 'ips/create-pool', _params
1392
+ end
1393
+
1394
+ # Deletes a pool. A pool must be empty before you can delete it, and you cannot delete your default pool.
1395
+ # @param [String] pool the name of the pool to delete
1396
+ # @return [Hash] information about the status of the pool that was deleted
1397
+ # - [String] pool the name of the pool
1398
+ # - [Boolean] deleted whether the pool was deleted
1399
+ def delete_pool(pool)
1400
+ _params = {:pool => pool}
1401
+ return @master.call 'ips/delete-pool', _params
1402
+ end
1403
+
1404
+ # Tests whether a domain name is valid for use as the custom reverse DNS for a dedicated IP.
1405
+ # @param [String] ip a dedicated ip address
1406
+ # @param [String] domain the domain name to test
1407
+ # @return [Hash] validation results for the domain
1408
+ # - [String] valid whether the domain name has a correctly-configured A record pointing to the ip address
1409
+ # - [String] error if valid is false, this will contain details about why the domain's A record is incorrect
1410
+ def check_custom_dns(ip, domain)
1411
+ _params = {:ip => ip, :domain => domain}
1412
+ return @master.call 'ips/check-custom-dns', _params
1413
+ end
1414
+
1415
+ # Configures the custom DNS name for a dedicated IP.
1416
+ # @param [String] ip a dedicated ip address
1417
+ # @param [String] domain a domain name to set as the dedicated IP's custom dns name.
1418
+ # @return [Hash] information about the dedicated IP's new configuration
1419
+ # - [String] ip the ip address
1420
+ # - [String] created_at the date and time that the dedicated IP was created as a UTC string in YYYY-MM-DD HH:MM:SS format
1421
+ # - [String] pool the name of the pool that this dedicated IP belongs to
1422
+ # - [String] domain the domain name (reverse dns) of this dedicated IP
1423
+ # - [Hash] custom_dns information about the ip's custom dns, if it has been configured
1424
+ # - [Boolean] enabled a boolean indicating whether custom dns has been configured for this ip
1425
+ # - [Boolean] valid whether the ip's custom dns is currently valid
1426
+ # - [String] error if the ip's custom dns is invalid, this will include details about the error
1427
+ # - [Hash] warmup information about the ip's warmup status
1428
+ # - [Boolean] warming_up whether the ip is currently in warmup mode
1429
+ # - [String] start_at the start time for the warmup process as a UTC string in YYYY-MM-DD HH:MM:SS format
1430
+ # - [String] end_at the end date and time for the warmup process as a UTC string in YYYY-MM-DD HH:MM:SS format
1431
+ def set_custom_dns(ip, domain)
1432
+ _params = {:ip => ip, :domain => domain}
1433
+ return @master.call 'ips/set-custom-dns', _params
1434
+ end
1435
+
1436
+ end
1437
+ class Internal
1438
+ attr_accessor :master
1439
+
1440
+ def initialize(master)
1441
+ @master = master
1442
+ end
1443
+
1444
+ end
1445
+ class Subaccounts
1446
+ attr_accessor :master
1447
+
1448
+ def initialize(master)
1449
+ @master = master
1450
+ end
1451
+
1452
+ # Get the list of subaccounts defined for the account, optionally filtered by a prefix
1453
+ # @param [String] q an optional prefix to filter the subaccounts' ids and names
1454
+ # @return [Array] the subaccounts for the account, up to a maximum of 1,000
1455
+ # - [Hash] return[] the individual subaccount info
1456
+ # - [String] id a unique indentifier for the subaccount
1457
+ # - [String] name an optional display name for the subaccount
1458
+ # - [Integer] custom_quota an optional manual hourly quota for the subaccount. If not specified, the hourly quota will be managed based on reputation
1459
+ # - [String] status the current sending status of the subaccount, one of "active" or "paused"
1460
+ # - [Integer] reputation the subaccount's current reputation on a scale from 0 to 100
1461
+ # - [String] created_at the date and time that the subaccount was created as a UTC string in YYYY-MM-DD HH:MM:SS format
1462
+ # - [String] first_sent_at the date and time that the subaccount first sent as a UTC string in YYYY-MM-DD HH:MM:SS format
1463
+ # - [Integer] sent_weekly the number of emails the subaccount has sent so far this week (weeks start on midnight Monday, UTC)
1464
+ # - [Integer] sent_monthly the number of emails the subaccount has sent so far this month (months start on midnight of the 1st, UTC)
1465
+ # - [Integer] sent_total the number of emails the subaccount has sent since it was created
1466
+ def list(q=nil)
1467
+ _params = {:q => q}
1468
+ return @master.call 'subaccounts/list', _params
1469
+ end
1470
+
1471
+ # Add a new subaccount
1472
+ # @param [String] id a unique identifier for the subaccount to be used in sending calls
1473
+ # @param [String] name an optional display name to further identify the subaccount
1474
+ # @param [String] notes optional extra text to associate with the subaccount
1475
+ # @param [Integer] custom_quota an optional manual hourly quota for the subaccount. If not specified, Mandrill will manage this based on reputation
1476
+ # @return [Hash] the information saved about the new subaccount
1477
+ # - [String] id a unique indentifier for the subaccount
1478
+ # - [String] name an optional display name for the subaccount
1479
+ # - [Integer] custom_quota an optional manual hourly quota for the subaccount. If not specified, the hourly quota will be managed based on reputation
1480
+ # - [String] status the current sending status of the subaccount, one of "active" or "paused"
1481
+ # - [Integer] reputation the subaccount's current reputation on a scale from 0 to 100
1482
+ # - [String] created_at the date and time that the subaccount was created as a UTC string in YYYY-MM-DD HH:MM:SS format
1483
+ # - [String] first_sent_at the date and time that the subaccount first sent as a UTC string in YYYY-MM-DD HH:MM:SS format
1484
+ # - [Integer] sent_weekly the number of emails the subaccount has sent so far this week (weeks start on midnight Monday, UTC)
1485
+ # - [Integer] sent_monthly the number of emails the subaccount has sent so far this month (months start on midnight of the 1st, UTC)
1486
+ # - [Integer] sent_total the number of emails the subaccount has sent since it was created
1487
+ def add(id, name=nil, notes=nil, custom_quota=nil)
1488
+ _params = {:id => id, :name => name, :notes => notes, :custom_quota => custom_quota}
1489
+ return @master.call 'subaccounts/add', _params
1490
+ end
1491
+
1492
+ # Given the ID of an existing subaccount, return the data about it
1493
+ # @param [String] id the unique identifier of the subaccount to query
1494
+ # @return [Hash] the information about the subaccount
1495
+ # - [String] id a unique indentifier for the subaccount
1496
+ # - [String] name an optional display name for the subaccount
1497
+ # - [String] notes optional extra text to associate with the subaccount
1498
+ # - [Integer] custom_quota an optional manual hourly quota for the subaccount. If not specified, the hourly quota will be managed based on reputation
1499
+ # - [String] status the current sending status of the subaccount, one of "active" or "paused"
1500
+ # - [Integer] reputation the subaccount's current reputation on a scale from 0 to 100
1501
+ # - [String] created_at the date and time that the subaccount was created as a UTC string in YYYY-MM-DD HH:MM:SS format
1502
+ # - [String] first_sent_at the date and time that the subaccount first sent as a UTC string in YYYY-MM-DD HH:MM:SS format
1503
+ # - [Integer] sent_weekly the number of emails the subaccount has sent so far this week (weeks start on midnight Monday, UTC)
1504
+ # - [Integer] sent_monthly the number of emails the subaccount has sent so far this month (months start on midnight of the 1st, UTC)
1505
+ # - [Integer] sent_total the number of emails the subaccount has sent since it was created
1506
+ # - [Integer] sent_hourly the number of emails the subaccount has sent in the last hour
1507
+ # - [Integer] hourly_quota the current hourly quota for the subaccount, either manual or reputation-based
1508
+ # - [Hash] last_30_days stats for this subaccount in the last 30 days
1509
+ # - [Integer] sent the number of emails sent for this subaccount in the last 30 days
1510
+ # - [Integer] hard_bounces the number of emails hard bounced for this subaccount in the last 30 days
1511
+ # - [Integer] soft_bounces the number of emails soft bounced for this subaccount in the last 30 days
1512
+ # - [Integer] rejects the number of emails rejected for sending this subaccount in the last 30 days
1513
+ # - [Integer] complaints the number of spam complaints for this subaccount in the last 30 days
1514
+ # - [Integer] unsubs the number of unsbuscribes for this subaccount in the last 30 days
1515
+ # - [Integer] opens the number of times emails have been opened for this subaccount in the last 30 days
1516
+ # - [Integer] unique_opens the number of unique opens for emails sent for this subaccount in the last 30 days
1517
+ # - [Integer] clicks the number of URLs that have been clicked for this subaccount in the last 30 days
1518
+ # - [Integer] unique_clicks the number of unique clicks for emails sent for this subaccount in the last 30 days
1519
+ def info(id)
1520
+ _params = {:id => id}
1521
+ return @master.call 'subaccounts/info', _params
1522
+ end
1523
+
1524
+ # Update an existing subaccount
1525
+ # @param [String] id the unique identifier of the subaccount to update
1526
+ # @param [String] name an optional display name to further identify the subaccount
1527
+ # @param [String] notes optional extra text to associate with the subaccount
1528
+ # @param [Integer] custom_quota an optional manual hourly quota for the subaccount. If not specified, Mandrill will manage this based on reputation
1529
+ # @return [Hash] the information for the updated subaccount
1530
+ # - [String] id a unique indentifier for the subaccount
1531
+ # - [String] name an optional display name for the subaccount
1532
+ # - [Integer] custom_quota an optional manual hourly quota for the subaccount. If not specified, the hourly quota will be managed based on reputation
1533
+ # - [String] status the current sending status of the subaccount, one of "active" or "paused"
1534
+ # - [Integer] reputation the subaccount's current reputation on a scale from 0 to 100
1535
+ # - [String] created_at the date and time that the subaccount was created as a UTC string in YYYY-MM-DD HH:MM:SS format
1536
+ # - [String] first_sent_at the date and time that the subaccount first sent as a UTC string in YYYY-MM-DD HH:MM:SS format
1537
+ # - [Integer] sent_weekly the number of emails the subaccount has sent so far this week (weeks start on midnight Monday, UTC)
1538
+ # - [Integer] sent_monthly the number of emails the subaccount has sent so far this month (months start on midnight of the 1st, UTC)
1539
+ # - [Integer] sent_total the number of emails the subaccount has sent since it was created
1540
+ def update(id, name=nil, notes=nil, custom_quota=nil)
1541
+ _params = {:id => id, :name => name, :notes => notes, :custom_quota => custom_quota}
1542
+ return @master.call 'subaccounts/update', _params
1543
+ end
1544
+
1545
+ # Delete an existing subaccount. Any email related to the subaccount will be saved, but stats will be removed and any future sending calls to this subaccount will fail.
1546
+ # @param [String] id the unique identifier of the subaccount to delete
1547
+ # @return [Hash] the information for the deleted subaccount
1548
+ # - [String] id a unique indentifier for the subaccount
1549
+ # - [String] name an optional display name for the subaccount
1550
+ # - [Integer] custom_quota an optional manual hourly quota for the subaccount. If not specified, the hourly quota will be managed based on reputation
1551
+ # - [String] status the current sending status of the subaccount, one of "active" or "paused"
1552
+ # - [Integer] reputation the subaccount's current reputation on a scale from 0 to 100
1553
+ # - [String] created_at the date and time that the subaccount was created as a UTC string in YYYY-MM-DD HH:MM:SS format
1554
+ # - [String] first_sent_at the date and time that the subaccount first sent as a UTC string in YYYY-MM-DD HH:MM:SS format
1555
+ # - [Integer] sent_weekly the number of emails the subaccount has sent so far this week (weeks start on midnight Monday, UTC)
1556
+ # - [Integer] sent_monthly the number of emails the subaccount has sent so far this month (months start on midnight of the 1st, UTC)
1557
+ # - [Integer] sent_total the number of emails the subaccount has sent since it was created
1558
+ def delete(id)
1559
+ _params = {:id => id}
1560
+ return @master.call 'subaccounts/delete', _params
1561
+ end
1562
+
1563
+ # Pause a subaccount's sending. Any future emails delivered to this subaccount will be queued for a maximum of 3 days until the subaccount is resumed.
1564
+ # @param [String] id the unique identifier of the subaccount to pause
1565
+ # @return [Hash] the information for the paused subaccount
1566
+ # - [String] id a unique indentifier for the subaccount
1567
+ # - [String] name an optional display name for the subaccount
1568
+ # - [Integer] custom_quota an optional manual hourly quota for the subaccount. If not specified, the hourly quota will be managed based on reputation
1569
+ # - [String] status the current sending status of the subaccount, one of "active" or "paused"
1570
+ # - [Integer] reputation the subaccount's current reputation on a scale from 0 to 100
1571
+ # - [String] created_at the date and time that the subaccount was created as a UTC string in YYYY-MM-DD HH:MM:SS format
1572
+ # - [String] first_sent_at the date and time that the subaccount first sent as a UTC string in YYYY-MM-DD HH:MM:SS format
1573
+ # - [Integer] sent_weekly the number of emails the subaccount has sent so far this week (weeks start on midnight Monday, UTC)
1574
+ # - [Integer] sent_monthly the number of emails the subaccount has sent so far this month (months start on midnight of the 1st, UTC)
1575
+ # - [Integer] sent_total the number of emails the subaccount has sent since it was created
1576
+ def pause(id)
1577
+ _params = {:id => id}
1578
+ return @master.call 'subaccounts/pause', _params
1579
+ end
1580
+
1581
+ # Resume a paused subaccount's sending
1582
+ # @param [String] id the unique identifier of the subaccount to resume
1583
+ # @return [Hash] the information for the resumed subaccount
1584
+ # - [String] id a unique indentifier for the subaccount
1585
+ # - [String] name an optional display name for the subaccount
1586
+ # - [Integer] custom_quota an optional manual hourly quota for the subaccount. If not specified, the hourly quota will be managed based on reputation
1587
+ # - [String] status the current sending status of the subaccount, one of "active" or "paused"
1588
+ # - [Integer] reputation the subaccount's current reputation on a scale from 0 to 100
1589
+ # - [String] created_at the date and time that the subaccount was created as a UTC string in YYYY-MM-DD HH:MM:SS format
1590
+ # - [String] first_sent_at the date and time that the subaccount first sent as a UTC string in YYYY-MM-DD HH:MM:SS format
1591
+ # - [Integer] sent_weekly the number of emails the subaccount has sent so far this week (weeks start on midnight Monday, UTC)
1592
+ # - [Integer] sent_monthly the number of emails the subaccount has sent so far this month (months start on midnight of the 1st, UTC)
1593
+ # - [Integer] sent_total the number of emails the subaccount has sent since it was created
1594
+ def resume(id)
1595
+ _params = {:id => id}
1596
+ return @master.call 'subaccounts/resume', _params
1597
+ end
1598
+
1599
+ end
1600
+ class Urls
1601
+ attr_accessor :master
1602
+
1603
+ def initialize(master)
1604
+ @master = master
1605
+ end
1606
+
1607
+ # Get the 100 most clicked URLs
1608
+ # @return [Array] the 100 most clicked URLs and their stats
1609
+ # - [Hash] return[] the individual URL stats
1610
+ # - [String] url the URL to be tracked
1611
+ # - [Integer] sent the number of emails that contained the URL
1612
+ # - [Integer] clicks the number of times the URL has been clicked from a tracked email
1613
+ # - [Integer] unique_clicks the number of unique emails that have generated clicks for this URL
1614
+ def list()
1615
+ _params = {}
1616
+ return @master.call 'urls/list', _params
1617
+ end
1618
+
1619
+ # Return the 100 most clicked URLs that match the search query given
1620
+ # @param [String] q a search query
1621
+ # @return [Array] the 100 most clicked URLs matching the search query
1622
+ # - [Hash] return[] the URL matching the query
1623
+ # - [String] url the URL to be tracked
1624
+ # - [Integer] sent the number of emails that contained the URL
1625
+ # - [Integer] clicks the number of times the URL has been clicked from a tracked email
1626
+ # - [Integer] unique_clicks the number of unique emails that have generated clicks for this URL
1627
+ def search(q)
1628
+ _params = {:q => q}
1629
+ return @master.call 'urls/search', _params
1630
+ end
1631
+
1632
+ # Return the recent history (hourly stats for the last 30 days) for a url
1633
+ # @param [String] url an existing URL
1634
+ # @return [Array] the array of history information
1635
+ # - [Hash] return[] the information for a single hour
1636
+ # - [String] time the hour as a UTC date string in YYYY-MM-DD HH:MM:SS format
1637
+ # - [Integer] sent the number of emails that were sent with the URL during the hour
1638
+ # - [Integer] clicks the number of times the URL was clicked during the hour
1639
+ # - [Integer] unique_clicks the number of unique clicks generated for emails sent with this URL during the hour
1640
+ def time_series(url)
1641
+ _params = {:url => url}
1642
+ return @master.call 'urls/time-series', _params
1643
+ end
1644
+
1645
+ # Get the list of tracking domains set up for this account
1646
+ # @return [Array] the tracking domains and their status
1647
+ # - [Hash] return[] the individual tracking domain
1648
+ # - [String] domain the tracking domain name
1649
+ # - [String] created_at the date and time that the tracking domain was added as a UTC string in YYYY-MM-DD HH:MM:SS format
1650
+ # - [String] last_tested_at when the domain's DNS settings were last tested as a UTC string in YYYY-MM-DD HH:MM:SS format
1651
+ # - [Hash] cname details about the domain's CNAME record
1652
+ # - [Boolean] valid whether the domain's CNAME record is valid for use with Mandrill
1653
+ # - [String] valid_after when the domain's CNAME record will be considered valid for use with Mandrill as a UTC string in YYYY-MM-DD HH:MM:SS format. If set, this indicates that the record is valid now, but was previously invalid, and Mandrill will wait until the record's TTL elapses to start using it.
1654
+ # - [String] error an error describing the CNAME record, or null if the record is correct
1655
+ # - [Boolean] valid_tracking whether this domain can be used as a tracking domain for email.
1656
+ def tracking_domains()
1657
+ _params = {}
1658
+ return @master.call 'urls/tracking-domains', _params
1659
+ end
1660
+
1661
+ # Add a tracking domain to your account
1662
+ # @param [String] domain a domain name
1663
+ # @return [Hash] information about the domain
1664
+ # - [String] domain the tracking domain name
1665
+ # - [String] created_at the date and time that the tracking domain was added as a UTC string in YYYY-MM-DD HH:MM:SS format
1666
+ # - [String] last_tested_at when the domain's DNS settings were last tested as a UTC string in YYYY-MM-DD HH:MM:SS format
1667
+ # - [Hash] cname details about the domain's CNAME record
1668
+ # - [Boolean] valid whether the domain's CNAME record is valid for use with Mandrill
1669
+ # - [String] valid_after when the domain's CNAME record will be considered valid for use with Mandrill as a UTC string in YYYY-MM-DD HH:MM:SS format. If set, this indicates that the record is valid now, but was previously invalid, and Mandrill will wait until the record's TTL elapses to start using it.
1670
+ # - [String] error an error describing the CNAME record, or null if the record is correct
1671
+ # - [Boolean] valid_tracking whether this domain can be used as a tracking domain for email.
1672
+ def add_tracking_domain(domain)
1673
+ _params = {:domain => domain}
1674
+ return @master.call 'urls/add-tracking-domain', _params
1675
+ end
1676
+
1677
+ # Checks the CNAME settings for a tracking domain. The domain must have been added already with the add-tracking-domain call
1678
+ # @param [String] domain an existing tracking domain name
1679
+ # @return [Hash] information about the tracking domain
1680
+ # - [String] domain the tracking domain name
1681
+ # - [String] created_at the date and time that the tracking domain was added as a UTC string in YYYY-MM-DD HH:MM:SS format
1682
+ # - [String] last_tested_at when the domain's DNS settings were last tested as a UTC string in YYYY-MM-DD HH:MM:SS format
1683
+ # - [Hash] cname details about the domain's CNAME record
1684
+ # - [Boolean] valid whether the domain's CNAME record is valid for use with Mandrill
1685
+ # - [String] valid_after when the domain's CNAME record will be considered valid for use with Mandrill as a UTC string in YYYY-MM-DD HH:MM:SS format. If set, this indicates that the record is valid now, but was previously invalid, and Mandrill will wait until the record's TTL elapses to start using it.
1686
+ # - [String] error an error describing the CNAME record, or null if the record is correct
1687
+ # - [Boolean] valid_tracking whether this domain can be used as a tracking domain for email.
1688
+ def check_tracking_domain(domain)
1689
+ _params = {:domain => domain}
1690
+ return @master.call 'urls/check-tracking-domain', _params
1691
+ end
1692
+
1693
+ end
1694
+ class Webhooks
1695
+ attr_accessor :master
1696
+
1697
+ def initialize(master)
1698
+ @master = master
1699
+ end
1700
+
1701
+ # Get the list of all webhooks defined on the account
1702
+ # @return [Array] the webhooks associated with the account
1703
+ # - [Hash] return[] the individual webhook info
1704
+ # - [Integer] id a unique integer indentifier for the webhook
1705
+ # - [String] url The URL that the event data will be posted to
1706
+ # - [String] description a description of the webhook
1707
+ # - [String] auth_key the key used to requests for this webhook
1708
+ # - [Array] events The message events that will be posted to the hook
1709
+ # - [String] events[] the individual message event (send, hard_bounce, soft_bounce, open, click, spam, unsub, or reject)
1710
+ # - [String] created_at the date and time that the webhook was created as a UTC string in YYYY-MM-DD HH:MM:SS format
1711
+ # - [String] last_sent_at the date and time that the webhook last successfully received events as a UTC string in YYYY-MM-DD HH:MM:SS format
1712
+ # - [Integer] batches_sent the number of event batches that have ever been sent to this webhook
1713
+ # - [Integer] events_sent the total number of events that have ever been sent to this webhook
1714
+ # - [String] last_error if we've ever gotten an error trying to post to this webhook, the last error that we've seen
1715
+ def list()
1716
+ _params = {}
1717
+ return @master.call 'webhooks/list', _params
1718
+ end
1719
+
1720
+ # Add a new webhook
1721
+ # @param [String] url the URL to POST batches of events
1722
+ # @param [String] description an optional description of the webhook
1723
+ # @param [Array] events an optional list of events that will be posted to the webhook
1724
+ # - [String] events[] the individual event to listen for
1725
+ # @return [Hash] the information saved about the new webhook
1726
+ # - [Integer] id a unique integer indentifier for the webhook
1727
+ # - [String] url The URL that the event data will be posted to
1728
+ # - [String] description a description of the webhook
1729
+ # - [String] auth_key the key used to requests for this webhook
1730
+ # - [Array] events The message events that will be posted to the hook
1731
+ # - [String] events[] the individual message event (send, hard_bounce, soft_bounce, open, click, spam, unsub, or reject)
1732
+ # - [String] created_at the date and time that the webhook was created as a UTC string in YYYY-MM-DD HH:MM:SS format
1733
+ # - [String] last_sent_at the date and time that the webhook last successfully received events as a UTC string in YYYY-MM-DD HH:MM:SS format
1734
+ # - [Integer] batches_sent the number of event batches that have ever been sent to this webhook
1735
+ # - [Integer] events_sent the total number of events that have ever been sent to this webhook
1736
+ # - [String] last_error if we've ever gotten an error trying to post to this webhook, the last error that we've seen
1737
+ def add(url, description=nil, events=[])
1738
+ _params = {:url => url, :description => description, :events => events}
1739
+ return @master.call 'webhooks/add', _params
1740
+ end
1741
+
1742
+ # Given the ID of an existing webhook, return the data about it
1743
+ # @param [Integer] id the unique identifier of a webhook belonging to this account
1744
+ # @return [Hash] the information about the webhook
1745
+ # - [Integer] id a unique integer indentifier for the webhook
1746
+ # - [String] url The URL that the event data will be posted to
1747
+ # - [String] description a description of the webhook
1748
+ # - [String] auth_key the key used to requests for this webhook
1749
+ # - [Array] events The message events that will be posted to the hook
1750
+ # - [String] events[] the individual message event (send, hard_bounce, soft_bounce, open, click, spam, unsub, or reject)
1751
+ # - [String] created_at the date and time that the webhook was created as a UTC string in YYYY-MM-DD HH:MM:SS format
1752
+ # - [String] last_sent_at the date and time that the webhook last successfully received events as a UTC string in YYYY-MM-DD HH:MM:SS format
1753
+ # - [Integer] batches_sent the number of event batches that have ever been sent to this webhook
1754
+ # - [Integer] events_sent the total number of events that have ever been sent to this webhook
1755
+ # - [String] last_error if we've ever gotten an error trying to post to this webhook, the last error that we've seen
1756
+ def info(id)
1757
+ _params = {:id => id}
1758
+ return @master.call 'webhooks/info', _params
1759
+ end
1760
+
1761
+ # Update an existing webhook
1762
+ # @param [Integer] id the unique identifier of a webhook belonging to this account
1763
+ # @param [String] url the URL to POST batches of events
1764
+ # @param [String] description an optional description of the webhook
1765
+ # @param [Array] events an optional list of events that will be posted to the webhook
1766
+ # - [String] events[] the individual event to listen for
1767
+ # @return [Hash] the information for the updated webhook
1768
+ # - [Integer] id a unique integer indentifier for the webhook
1769
+ # - [String] url The URL that the event data will be posted to
1770
+ # - [String] description a description of the webhook
1771
+ # - [String] auth_key the key used to requests for this webhook
1772
+ # - [Array] events The message events that will be posted to the hook
1773
+ # - [String] events[] the individual message event (send, hard_bounce, soft_bounce, open, click, spam, unsub, or reject)
1774
+ # - [String] created_at the date and time that the webhook was created as a UTC string in YYYY-MM-DD HH:MM:SS format
1775
+ # - [String] last_sent_at the date and time that the webhook last successfully received events as a UTC string in YYYY-MM-DD HH:MM:SS format
1776
+ # - [Integer] batches_sent the number of event batches that have ever been sent to this webhook
1777
+ # - [Integer] events_sent the total number of events that have ever been sent to this webhook
1778
+ # - [String] last_error if we've ever gotten an error trying to post to this webhook, the last error that we've seen
1779
+ def update(id, url, description=nil, events=[])
1780
+ _params = {:id => id, :url => url, :description => description, :events => events}
1781
+ return @master.call 'webhooks/update', _params
1782
+ end
1783
+
1784
+ # Delete an existing webhook
1785
+ # @param [Integer] id the unique identifier of a webhook belonging to this account
1786
+ # @return [Hash] the information for the deleted webhook
1787
+ # - [Integer] id a unique integer indentifier for the webhook
1788
+ # - [String] url The URL that the event data will be posted to
1789
+ # - [String] description a description of the webhook
1790
+ # - [String] auth_key the key used to requests for this webhook
1791
+ # - [Array] events The message events that will be posted to the hook
1792
+ # - [String] events[] the individual message event (send, hard_bounce, soft_bounce, open, click, spam, unsub, or reject)
1793
+ # - [String] created_at the date and time that the webhook was created as a UTC string in YYYY-MM-DD HH:MM:SS format
1794
+ # - [String] last_sent_at the date and time that the webhook last successfully received events as a UTC string in YYYY-MM-DD HH:MM:SS format
1795
+ # - [Integer] batches_sent the number of event batches that have ever been sent to this webhook
1796
+ # - [Integer] events_sent the total number of events that have ever been sent to this webhook
1797
+ # - [String] last_error if we've ever gotten an error trying to post to this webhook, the last error that we've seen
1798
+ def delete(id)
1799
+ _params = {:id => id}
1800
+ return @master.call 'webhooks/delete', _params
1801
+ end
1802
+
1803
+ end
1804
+ class Senders
1805
+ attr_accessor :master
1806
+
1807
+ def initialize(master)
1808
+ @master = master
1809
+ end
1810
+
1811
+ # Return the senders that have tried to use this account.
1812
+ # @return [Array] an array of sender data, one for each sending addresses used by the account
1813
+ # - [Hash] return[] the information on each sending address in the account
1814
+ # - [String] address the sender's email address
1815
+ # - [String] created_at the date and time that the sender was first seen by Mandrill as a UTC date string in YYYY-MM-DD HH:MM:SS format
1816
+ # - [Integer] sent the total number of messages sent by this sender
1817
+ # - [Integer] hard_bounces the total number of hard bounces by messages by this sender
1818
+ # - [Integer] soft_bounces the total number of soft bounces by messages by this sender
1819
+ # - [Integer] rejects the total number of rejected messages by this sender
1820
+ # - [Integer] complaints the total number of spam complaints received for messages by this sender
1821
+ # - [Integer] unsubs the total number of unsubscribe requests received for messages by this sender
1822
+ # - [Integer] opens the total number of times messages by this sender have been opened
1823
+ # - [Integer] clicks the total number of times tracked URLs in messages by this sender have been clicked
1824
+ # - [Integer] unique_opens the number of unique opens for emails sent for this sender
1825
+ # - [Integer] unique_clicks the number of unique clicks for emails sent for this sender
1826
+ def list()
1827
+ _params = {}
1828
+ return @master.call 'senders/list', _params
1829
+ end
1830
+
1831
+ # Returns the sender domains that have been added to this account.
1832
+ # @return [Array] an array of sender domain data, one for each sending domain used by the account
1833
+ # - [Hash] return[] the information on each sending domain for the account
1834
+ # - [String] domain the sender domain name
1835
+ # - [String] created_at the date and time that the sending domain was first seen as a UTC string in YYYY-MM-DD HH:MM:SS format
1836
+ # - [String] last_tested_at when the domain's DNS settings were last tested as a UTC string in YYYY-MM-DD HH:MM:SS format
1837
+ # - [Hash] spf details about the domain's SPF record
1838
+ # - [Boolean] valid whether the domain's SPF record is valid for use with Mandrill
1839
+ # - [String] valid_after when the domain's SPF record will be considered valid for use with Mandrill as a UTC string in YYYY-MM-DD HH:MM:SS format. If set, this indicates that the record is valid now, but was previously invalid, and Mandrill will wait until the record's TTL elapses to start using it.
1840
+ # - [String] error an error describing the spf record, or null if the record is correct
1841
+ # - [Hash] dkim details about the domain's DKIM record
1842
+ # - [Boolean] valid whether the domain's DKIM record is valid for use with Mandrill
1843
+ # - [String] valid_after when the domain's DKIM record will be considered valid for use with Mandrill as a UTC string in YYYY-MM-DD HH:MM:SS format. If set, this indicates that the record is valid now, but was previously invalid, and Mandrill will wait until the record's TTL elapses to start using it.
1844
+ # - [String] error an error describing the DKIM record, or null if the record is correct
1845
+ # - [String] verified_at if the domain has been verified, this indicates when that verification occurred as a UTC string in YYYY-MM-DD HH:MM:SS format
1846
+ # - [Boolean] valid_signing whether this domain can be used to authenticate mail, either for itself or as a custom signing domain. If this is false but spf and dkim are both valid, you will need to verify the domain before using it to authenticate mail
1847
+ def domains()
1848
+ _params = {}
1849
+ return @master.call 'senders/domains', _params
1850
+ end
1851
+
1852
+ # Adds a sender domain to your account. Sender domains are added automatically as you send, but you can use this call to add them ahead of time.
1853
+ # @param [String] domain a domain name
1854
+ # @return [Hash] information about the domain
1855
+ # - [String] domain the sender domain name
1856
+ # - [String] created_at the date and time that the sending domain was first seen as a UTC string in YYYY-MM-DD HH:MM:SS format
1857
+ # - [String] last_tested_at when the domain's DNS settings were last tested as a UTC string in YYYY-MM-DD HH:MM:SS format
1858
+ # - [Hash] spf details about the domain's SPF record
1859
+ # - [Boolean] valid whether the domain's SPF record is valid for use with Mandrill
1860
+ # - [String] valid_after when the domain's SPF record will be considered valid for use with Mandrill as a UTC string in YYYY-MM-DD HH:MM:SS format. If set, this indicates that the record is valid now, but was previously invalid, and Mandrill will wait until the record's TTL elapses to start using it.
1861
+ # - [String] error an error describing the spf record, or null if the record is correct
1862
+ # - [Hash] dkim details about the domain's DKIM record
1863
+ # - [Boolean] valid whether the domain's DKIM record is valid for use with Mandrill
1864
+ # - [String] valid_after when the domain's DKIM record will be considered valid for use with Mandrill as a UTC string in YYYY-MM-DD HH:MM:SS format. If set, this indicates that the record is valid now, but was previously invalid, and Mandrill will wait until the record's TTL elapses to start using it.
1865
+ # - [String] error an error describing the DKIM record, or null if the record is correct
1866
+ # - [String] verified_at if the domain has been verified, this indicates when that verification occurred as a UTC string in YYYY-MM-DD HH:MM:SS format
1867
+ # - [Boolean] valid_signing whether this domain can be used to authenticate mail, either for itself or as a custom signing domain. If this is false but spf and dkim are both valid, you will need to verify the domain before using it to authenticate mail
1868
+ def add_domain(domain)
1869
+ _params = {:domain => domain}
1870
+ return @master.call 'senders/add-domain', _params
1871
+ end
1872
+
1873
+ # Checks the SPF and DKIM settings for a domain. If you haven't already added this domain to your account, it will be added automatically.
1874
+ # @param [String] domain a domain name
1875
+ # @return [Hash] information about the sender domain
1876
+ # - [String] domain the sender domain name
1877
+ # - [String] created_at the date and time that the sending domain was first seen as a UTC string in YYYY-MM-DD HH:MM:SS format
1878
+ # - [String] last_tested_at when the domain's DNS settings were last tested as a UTC string in YYYY-MM-DD HH:MM:SS format
1879
+ # - [Hash] spf details about the domain's SPF record
1880
+ # - [Boolean] valid whether the domain's SPF record is valid for use with Mandrill
1881
+ # - [String] valid_after when the domain's SPF record will be considered valid for use with Mandrill as a UTC string in YYYY-MM-DD HH:MM:SS format. If set, this indicates that the record is valid now, but was previously invalid, and Mandrill will wait until the record's TTL elapses to start using it.
1882
+ # - [String] error an error describing the spf record, or null if the record is correct
1883
+ # - [Hash] dkim details about the domain's DKIM record
1884
+ # - [Boolean] valid whether the domain's DKIM record is valid for use with Mandrill
1885
+ # - [String] valid_after when the domain's DKIM record will be considered valid for use with Mandrill as a UTC string in YYYY-MM-DD HH:MM:SS format. If set, this indicates that the record is valid now, but was previously invalid, and Mandrill will wait until the record's TTL elapses to start using it.
1886
+ # - [String] error an error describing the DKIM record, or null if the record is correct
1887
+ # - [String] verified_at if the domain has been verified, this indicates when that verification occurred as a UTC string in YYYY-MM-DD HH:MM:SS format
1888
+ # - [Boolean] valid_signing whether this domain can be used to authenticate mail, either for itself or as a custom signing domain. If this is false but spf and dkim are both valid, you will need to verify the domain before using it to authenticate mail
1889
+ def check_domain(domain)
1890
+ _params = {:domain => domain}
1891
+ return @master.call 'senders/check-domain', _params
1892
+ end
1893
+
1894
+ # Sends a verification email in order to verify ownership of a domain. Domain verification is a required step to confirm ownership of a domain. Once a domain has been verified in a Mandrill account, other accounts may not have their messages signed by that domain unless they also verify the domain. This prevents other Mandrill accounts from sending mail signed by your domain.
1895
+ # @param [String] domain a domain name at which you can receive email
1896
+ # @param [String] mailbox a mailbox at the domain where the verification email should be sent
1897
+ # @return [Hash] information about the verification that was sent
1898
+ # - [String] status "sent" indicates that the verification has been sent, "already_verified" indicates that the domain has already been verified with your account
1899
+ # - [String] domain the domain name you provided
1900
+ # - [String] email the email address the verification email was sent to
1901
+ def verify_domain(domain, mailbox)
1902
+ _params = {:domain => domain, :mailbox => mailbox}
1903
+ return @master.call 'senders/verify-domain', _params
1904
+ end
1905
+
1906
+ # Return more detailed information about a single sender, including aggregates of recent stats
1907
+ # @param [String] address the email address of the sender
1908
+ # @return [Hash] the detailed information on the sender
1909
+ # - [String] address the sender's email address
1910
+ # - [String] created_at the date and time that the sender was first seen by Mandrill as a UTC date string in YYYY-MM-DD HH:MM:SS format
1911
+ # - [Integer] sent the total number of messages sent by this sender
1912
+ # - [Integer] hard_bounces the total number of hard bounces by messages by this sender
1913
+ # - [Integer] soft_bounces the total number of soft bounces by messages by this sender
1914
+ # - [Integer] rejects the total number of rejected messages by this sender
1915
+ # - [Integer] complaints the total number of spam complaints received for messages by this sender
1916
+ # - [Integer] unsubs the total number of unsubscribe requests received for messages by this sender
1917
+ # - [Integer] opens the total number of times messages by this sender have been opened
1918
+ # - [Integer] clicks the total number of times tracked URLs in messages by this sender have been clicked
1919
+ # - [Hash] stats an aggregate summary of the sender's sending stats
1920
+ # - [Hash] today stats for this sender so far today
1921
+ # - [Integer] sent the number of emails sent for this sender so far today
1922
+ # - [Integer] hard_bounces the number of emails hard bounced for this sender so far today
1923
+ # - [Integer] soft_bounces the number of emails soft bounced for this sender so far today
1924
+ # - [Integer] rejects the number of emails rejected for sending this sender so far today
1925
+ # - [Integer] complaints the number of spam complaints for this sender so far today
1926
+ # - [Integer] unsubs the number of unsubscribes for this sender so far today
1927
+ # - [Integer] opens the number of times emails have been opened for this sender so far today
1928
+ # - [Integer] unique_opens the number of unique opens for emails sent for this sender so far today
1929
+ # - [Integer] clicks the number of URLs that have been clicked for this sender so far today
1930
+ # - [Integer] unique_clicks the number of unique clicks for emails sent for this sender so far today
1931
+ # - [Hash] last_7_days stats for this sender in the last 7 days
1932
+ # - [Integer] sent the number of emails sent for this sender in the last 7 days
1933
+ # - [Integer] hard_bounces the number of emails hard bounced for this sender in the last 7 days
1934
+ # - [Integer] soft_bounces the number of emails soft bounced for this sender in the last 7 days
1935
+ # - [Integer] rejects the number of emails rejected for sending this sender in the last 7 days
1936
+ # - [Integer] complaints the number of spam complaints for this sender in the last 7 days
1937
+ # - [Integer] unsubs the number of unsubscribes for this sender in the last 7 days
1938
+ # - [Integer] opens the number of times emails have been opened for this sender in the last 7 days
1939
+ # - [Integer] unique_opens the number of unique opens for emails sent for this sender in the last 7 days
1940
+ # - [Integer] clicks the number of URLs that have been clicked for this sender in the last 7 days
1941
+ # - [Integer] unique_clicks the number of unique clicks for emails sent for this sender in the last 7 days
1942
+ # - [Hash] last_30_days stats for this sender in the last 30 days
1943
+ # - [Integer] sent the number of emails sent for this sender in the last 30 days
1944
+ # - [Integer] hard_bounces the number of emails hard bounced for this sender in the last 30 days
1945
+ # - [Integer] soft_bounces the number of emails soft bounced for this sender in the last 30 days
1946
+ # - [Integer] rejects the number of emails rejected for sending this sender in the last 30 days
1947
+ # - [Integer] complaints the number of spam complaints for this sender in the last 30 days
1948
+ # - [Integer] unsubs the number of unsubscribes for this sender in the last 30 days
1949
+ # - [Integer] opens the number of times emails have been opened for this sender in the last 30 days
1950
+ # - [Integer] unique_opens the number of unique opens for emails sent for this sender in the last 30 days
1951
+ # - [Integer] clicks the number of URLs that have been clicked for this sender in the last 30 days
1952
+ # - [Integer] unique_clicks the number of unique clicks for emails sent for this sender in the last 30 days
1953
+ # - [Hash] last_60_days stats for this sender in the last 60 days
1954
+ # - [Integer] sent the number of emails sent for this sender in the last 60 days
1955
+ # - [Integer] hard_bounces the number of emails hard bounced for this sender in the last 60 days
1956
+ # - [Integer] soft_bounces the number of emails soft bounced for this sender in the last 60 days
1957
+ # - [Integer] rejects the number of emails rejected for sending this sender in the last 60 days
1958
+ # - [Integer] complaints the number of spam complaints for this sender in the last 60 days
1959
+ # - [Integer] unsubs the number of unsubscribes for this sender in the last 60 days
1960
+ # - [Integer] opens the number of times emails have been opened for this sender in the last 60 days
1961
+ # - [Integer] unique_opens the number of unique opens for emails sent for this sender in the last 60 days
1962
+ # - [Integer] clicks the number of URLs that have been clicked for this sender in the last 60 days
1963
+ # - [Integer] unique_clicks the number of unique clicks for emails sent for this sender in the last 60 days
1964
+ # - [Hash] last_90_days stats for this sender in the last 90 days
1965
+ # - [Integer] sent the number of emails sent for this sender in the last 90 days
1966
+ # - [Integer] hard_bounces the number of emails hard bounced for this sender in the last 90 days
1967
+ # - [Integer] soft_bounces the number of emails soft bounced for this sender in the last 90 days
1968
+ # - [Integer] rejects the number of emails rejected for sending this sender in the last 90 days
1969
+ # - [Integer] complaints the number of spam complaints for this sender in the last 90 days
1970
+ # - [Integer] unsubs the number of unsubscribes for this sender in the last 90 days
1971
+ # - [Integer] opens the number of times emails have been opened for this sender in the last 90 days
1972
+ # - [Integer] unique_opens the number of unique opens for emails sent for this sender in the last 90 days
1973
+ # - [Integer] clicks the number of URLs that have been clicked for this sender in the last 90 days
1974
+ # - [Integer] unique_clicks the number of unique clicks for emails sent for this sender in the last 90 days
1975
+ def info(address)
1976
+ _params = {:address => address}
1977
+ return @master.call 'senders/info', _params
1978
+ end
1979
+
1980
+ # Return the recent history (hourly stats for the last 30 days) for a sender
1981
+ # @param [String] address the email address of the sender
1982
+ # @return [Array] the array of history information
1983
+ # - [Hash] return[] the stats for a single hour
1984
+ # - [String] time the hour as a UTC date string in YYYY-MM-DD HH:MM:SS format
1985
+ # - [Integer] sent the number of emails that were sent during the hour
1986
+ # - [Integer] hard_bounces the number of emails that hard bounced during the hour
1987
+ # - [Integer] soft_bounces the number of emails that soft bounced during the hour
1988
+ # - [Integer] rejects the number of emails that were rejected during the hour
1989
+ # - [Integer] complaints the number of spam complaints received during the hour
1990
+ # - [Integer] opens the number of emails opened during the hour
1991
+ # - [Integer] unique_opens the number of unique opens generated by messages sent during the hour
1992
+ # - [Integer] clicks the number of tracked URLs clicked during the hour
1993
+ # - [Integer] unique_clicks the number of unique clicks generated by messages sent during the hour
1994
+ def time_series(address)
1995
+ _params = {:address => address}
1996
+ return @master.call 'senders/time-series', _params
1997
+ end
1998
+
1999
+ end
2000
+ class Metadata
2001
+ attr_accessor :master
2002
+
2003
+ def initialize(master)
2004
+ @master = master
2005
+ end
2006
+
2007
+ # Get the list of custom metadata fields indexed for the account.
2008
+ # @return [Array] the custom metadata fields for the account
2009
+ # - [Hash] return[] the individual custom metadata field info
2010
+ # - [String] name the unique identifier of the metadata field to update
2011
+ # - [String] state the current state of the metadata field, one of "active", "delete", or "index"
2012
+ # - [String] view_template Mustache template to control how the metadata is rendered in your activity log
2013
+ def list()
2014
+ _params = {}
2015
+ return @master.call 'metadata/list', _params
2016
+ end
2017
+
2018
+ # Add a new custom metadata field to be indexed for the account.
2019
+ # @param [String] name a unique identifier for the metadata field
2020
+ # @param [String] view_template optional Mustache template to control how the metadata is rendered in your activity log
2021
+ # @return [Hash] the information saved about the new metadata field
2022
+ # - [String] name the unique identifier of the metadata field to update
2023
+ # - [String] state the current state of the metadata field, one of "active", "delete", or "index"
2024
+ # - [String] view_template Mustache template to control how the metadata is rendered in your activity log
2025
+ def add(name, view_template=nil)
2026
+ _params = {:name => name, :view_template => view_template}
2027
+ return @master.call 'metadata/add', _params
2028
+ end
2029
+
2030
+ # Update an existing custom metadata field.
2031
+ # @param [String] name the unique identifier of the metadata field to update
2032
+ # @param [String] view_template optional Mustache template to control how the metadata is rendered in your activity log
2033
+ # @return [Hash] the information for the updated metadata field
2034
+ # - [String] name the unique identifier of the metadata field to update
2035
+ # - [String] state the current state of the metadata field, one of "active", "delete", or "index"
2036
+ # - [String] view_template Mustache template to control how the metadata is rendered in your activity log
2037
+ def update(name, view_template)
2038
+ _params = {:name => name, :view_template => view_template}
2039
+ return @master.call 'metadata/update', _params
2040
+ end
2041
+
2042
+ # Delete an existing custom metadata field. Deletion isn't instataneous, and /metadata/list will continue to return the field until the asynchronous deletion process is complete.
2043
+ # @param [String] name the unique identifier of the metadata field to update
2044
+ # @return [Hash] the information for the deleted metadata field
2045
+ # - [String] name the unique identifier of the metadata field to update
2046
+ # - [String] state the current state of the metadata field, one of "active", "delete", or "index"
2047
+ # - [String] view_template Mustache template to control how the metadata is rendered in your activity log
2048
+ def delete(name)
2049
+ _params = {:name => name}
2050
+ return @master.call 'metadata/delete', _params
2051
+ end
2052
+
2053
+ end
2054
+ end