updated-mandrill-api 2.0.0

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