mandrill-api 1.0.2 → 1.0.3

Sign up to get free protection for your applications and to get access to all the features.
Files changed (2) hide show
  1. data/lib/mandrill/api.rb +664 -0
  2. metadata +4 -3
data/lib/mandrill/api.rb CHANGED
@@ -1,5 +1,6 @@
1
1
  module Mandrill
2
2
 
3
+
3
4
  class Templates
4
5
  attr_accessor :master
5
6
 
@@ -7,38 +8,136 @@ module Mandrill
7
8
  @master = master
8
9
  end
9
10
 
11
+ # Add a new template
12
+ # @param [String] name the name for the new template - must be unique
13
+ # @param [String] code the HTML code for the template with mc:edit attributes for the editable elements
14
+ # @param [Boolean] publish set to false to add a draft template without publishing
15
+ # @return [Hash] the information saved about the new template
16
+ # - [String] name the name of the template - draft version
17
+ # - [String] code the full HTML code of the template, with mc:edit attributes marking the editable elements - draft version
18
+ # - [String] publish_name the name that the template was published as, if it has been published
19
+ # - [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
20
+ # - [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
21
+ # - [String] created_at the date and time the template was first created as a UTC string in YYYY-MM-DD HH:MM:SS format
22
+ # - [String] updated_at the date and time the template was last modified as a UTC string in YYYY-MM-DD HH:MM:SS format
10
23
  def add(name, code, publish=true)
11
24
  _params = {:name => name, :code => code, :publish => publish}
12
25
  return @master.call 'templates/add', _params
13
26
  end
27
+
28
+ # Get the information for an existing template
29
+ # @param [String] name the name of an existing template
30
+ # @return [Hash] the requested template information
31
+ # - [String] name the name of the template - draft version
32
+ # - [String] code the full HTML code of the template, with mc:edit attributes marking the editable elements - draft version
33
+ # - [String] publish_name the name that the template was published as, if it has been published
34
+ # - [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
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
14
38
  def info(name)
15
39
  _params = {:name => name}
16
40
  return @master.call 'templates/info', _params
17
41
  end
42
+
43
+ # Update the code for an existing template
44
+ # @param [String] name the name of an existing template
45
+ # @param [String] code the new code for the template
46
+ # @param [Boolean] publish set to false to update the draft version of the template without publishing
47
+ # @return [Hash] the template that was updated
48
+ # - [String] name the name of the template - draft version
49
+ # - [String] code the full HTML code of the template, with mc:edit attributes marking the editable elements - draft version
50
+ # - [String] publish_name the name that the template was published as, if it has been published
51
+ # - [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
52
+ # - [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
53
+ # - [String] created_at the date and time the template was first created as a UTC string in YYYY-MM-DD HH:MM:SS format
54
+ # - [String] updated_at the date and time the template was last modified as a UTC string in YYYY-MM-DD HH:MM:SS format
18
55
  def update(name, code, publish=true)
19
56
  _params = {:name => name, :code => code, :publish => publish}
20
57
  return @master.call 'templates/update', _params
21
58
  end
59
+
60
+ # Publish the content for the template. Any new messages sent using this template will start using the content that was previously in draft.
61
+ # @param [String] name the name of an existing template
62
+ # @return [Hash] the template that was published
63
+ # - [String] name the name of the template - draft version
64
+ # - [String] code the full HTML code of the template, with mc:edit attributes marking the editable elements - draft version
65
+ # - [String] publish_name the name that the template was published as, if it has been published
66
+ # - [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
67
+ # - [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
68
+ # - [String] created_at the date and time the template was first created as a UTC string in YYYY-MM-DD HH:MM:SS format
69
+ # - [String] updated_at the date and time the template was last modified as a UTC string in YYYY-MM-DD HH:MM:SS format
22
70
  def publish(name)
23
71
  _params = {:name => name}
24
72
  return @master.call 'templates/publish', _params
25
73
  end
74
+
75
+ # Delete a template
76
+ # @param [String] name the name of an existing template
77
+ # @return [Hash] the template that was deleted
78
+ # - [String] name the name of the template - draft version
79
+ # - [String] code the full HTML code of the template, with mc:edit attributes marking the editable elements - draft version
80
+ # - [String] publish_name the name that the template was published as, if it has been published
81
+ # - [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
82
+ # - [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
83
+ # - [String] created_at the date and time the template was first created as a UTC string in YYYY-MM-DD HH:MM:SS format
84
+ # - [String] updated_at the date and time the template was last modified as a UTC string in YYYY-MM-DD HH:MM:SS format
26
85
  def delete(name)
27
86
  _params = {:name => name}
28
87
  return @master.call 'templates/delete', _params
29
88
  end
89
+
90
+ # Return a list of all the templates available to this user
91
+ # @return [Array] an array of structs with information about each template
92
+ # - [Hash] return[] the information on each template in the account
93
+ # - [String] name the name of the template - draft version
94
+ # - [String] code the full HTML code of the template, with mc:edit attributes marking the editable elements - draft version
95
+ # - [String] publish_name the name that the template was published as, if it has been published
96
+ # - [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
97
+ # - [String] published_at the date and time the template was last published as a UTC string in YYYY-MM-DD HH:MM:SS format, or null if it has not been published
98
+ # - [String] created_at the date and time the template was first created as a UTC string in YYYY-MM-DD HH:MM:SS format
99
+ # - [String] updated_at the date and time the template was last modified as a UTC string in YYYY-MM-DD HH:MM:SS format
30
100
  def list()
31
101
  _params = {}
32
102
  return @master.call 'templates/list', _params
33
103
  end
104
+
105
+ # Return the recent history (hourly stats for the last 30 days) for a template
106
+ # @param [String] name the name of an existing template
107
+ # @return [Array] the array of history information
108
+ # - [Hash] return[] the stats for a single hour
109
+ # - [String] time the hour as a UTC date string in YYYY-MM-DD HH:MM:SS format
110
+ # - [Integer] sent the number of emails that were sent during the hour
111
+ # - [Integer] hard_bounces the number of emails that hard bounced during the hour
112
+ # - [Integer] soft_bounces the number of emails that soft bounced during the hour
113
+ # - [Integer] rejects the number of emails that were rejected during the hour
114
+ # - [Integer] complaints the number of spam complaints received during the hour
115
+ # - [Integer] opens the number of emails opened during the hour
116
+ # - [Integer] unique_opens the number of unique opens generated by messages sent during the hour
117
+ # - [Integer] clicks the number of tracked URLs clicked during the hour
118
+ # - [Integer] unique_clicks the number of unique clicks generated by messages sent during the hour
34
119
  def time_series(name)
35
120
  _params = {:name => name}
36
121
  return @master.call 'templates/time-series', _params
37
122
  end
123
+
124
+ # Inject content and optionally merge fields into a template, returning the HTML that results
125
+ # @param [String] template_name the name of a template that exists in the user's account
126
+ # @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
127
+ # - [Hash] template_content[] the injection of a single piece of content into a single editable region
128
+ # - [String] name the name of the mc:edit editable region to inject into
129
+ # - [String] content the content to inject
130
+ # @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.
131
+ # - [Hash] merge_vars[] a single merge variable
132
+ # - [String] name the merge variable's name. Merge variable names are case-insensitive and may not start with _
133
+ # - [String] content the merge variable's content
134
+ # @return [Hash] the result of rendering the given template with the content and merge field values injected
135
+ # - [String] html the rendered HTML as a string
38
136
  def render(template_name, template_content, merge_vars=nil)
39
137
  _params = {:template_name => template_name, :template_content => template_content, :merge_vars => merge_vars}
40
138
  return @master.call 'templates/render', _params
41
139
  end
140
+
42
141
  end
43
142
  class Users
44
143
  attr_accessor :master
@@ -47,18 +146,111 @@ module Mandrill
47
146
  @master = master
48
147
  end
49
148
 
149
+ # Return the information about the API-connected user
150
+ # @return [Hash] the user information including username, key, reputation, quota, and historical sending stats
151
+ # - [String] username the username of the user (used for SMTP authentication)
152
+ # - [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
153
+ # - [String] public_id a unique, permanent identifier for this user
154
+ # - [Integer] reputation the reputation of the user on a scale from 0 to 100, with 75 generally being a "good" reputation
155
+ # - [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
156
+ # - [Integer] backlog the number of emails that are queued for delivery due to exceeding your monthly or hourly quotas
157
+ # - [Hash] stats an aggregate summary of the account's sending stats
158
+ # - [Hash] today stats for this user so far today
159
+ # - [Integer] sent the number of emails sent for this user so far today
160
+ # - [Integer] hard_bounces the number of emails hard bounced for this user so far today
161
+ # - [Integer] soft_bounces the number of emails soft bounced for this user so far today
162
+ # - [Integer] rejects the number of emails rejected for sending this user so far today
163
+ # - [Integer] complaints the number of spam complaints for this user so far today
164
+ # - [Integer] unsubs the number of unsubscribes for this user so far today
165
+ # - [Integer] opens the number of times emails have been opened for this user so far today
166
+ # - [Integer] unique_opens the number of unique opens for emails sent for this user so far today
167
+ # - [Integer] clicks the number of URLs that have been clicked for this user so far today
168
+ # - [Integer] unique_clicks the number of unique clicks for emails sent for this user so far today
169
+ # - [Hash] last_7_days stats for this user in the last 7 days
170
+ # - [Integer] sent the number of emails sent for this user in the last 7 days
171
+ # - [Integer] hard_bounces the number of emails hard bounced for this user in the last 7 days
172
+ # - [Integer] soft_bounces the number of emails soft bounced for this user in the last 7 days
173
+ # - [Integer] rejects the number of emails rejected for sending this user in the last 7 days
174
+ # - [Integer] complaints the number of spam complaints for this user in the last 7 days
175
+ # - [Integer] unsubs the number of unsubscribes for this user in the last 7 days
176
+ # - [Integer] opens the number of times emails have been opened for this user in the last 7 days
177
+ # - [Integer] unique_opens the number of unique opens for emails sent for this user in the last 7 days
178
+ # - [Integer] clicks the number of URLs that have been clicked for this user in the last 7 days
179
+ # - [Integer] unique_clicks the number of unique clicks for emails sent for this user in the last 7 days
180
+ # - [Hash] last_30_days stats for this user in the last 30 days
181
+ # - [Integer] sent the number of emails sent for this user in the last 30 days
182
+ # - [Integer] hard_bounces the number of emails hard bounced for this user in the last 30 days
183
+ # - [Integer] soft_bounces the number of emails soft bounced for this user in the last 30 days
184
+ # - [Integer] rejects the number of emails rejected for sending this user in the last 30 days
185
+ # - [Integer] complaints the number of spam complaints for this user in the last 30 days
186
+ # - [Integer] unsubs the number of unsubscribes for this user in the last 30 days
187
+ # - [Integer] opens the number of times emails have been opened for this user in the last 30 days
188
+ # - [Integer] unique_opens the number of unique opens for emails sent for this user in the last 30 days
189
+ # - [Integer] clicks the number of URLs that have been clicked for this user in the last 30 days
190
+ # - [Integer] unique_clicks the number of unique clicks for emails sent for this user in the last 30 days
191
+ # - [Hash] last_60_days stats for this user in the last 60 days
192
+ # - [Integer] sent the number of emails sent for this user in the last 60 days
193
+ # - [Integer] hard_bounces the number of emails hard bounced for this user in the last 60 days
194
+ # - [Integer] soft_bounces the number of emails soft bounced for this user in the last 60 days
195
+ # - [Integer] rejects the number of emails rejected for sending this user in the last 60 days
196
+ # - [Integer] complaints the number of spam complaints for this user in the last 60 days
197
+ # - [Integer] unsubs the number of unsubscribes for this user in the last 60 days
198
+ # - [Integer] opens the number of times emails have been opened for this user in the last 60 days
199
+ # - [Integer] unique_opens the number of unique opens for emails sent for this user in the last 60 days
200
+ # - [Integer] clicks the number of URLs that have been clicked for this user in the last 60 days
201
+ # - [Integer] unique_clicks the number of unique clicks for emails sent for this user in the last 60 days
202
+ # - [Hash] last_90_days stats for this user in the last 90 days
203
+ # - [Integer] sent the number of emails sent for this user in the last 90 days
204
+ # - [Integer] hard_bounces the number of emails hard bounced for this user in the last 90 days
205
+ # - [Integer] soft_bounces the number of emails soft bounced for this user in the last 90 days
206
+ # - [Integer] rejects the number of emails rejected for sending this user in the last 90 days
207
+ # - [Integer] complaints the number of spam complaints for this user in the last 90 days
208
+ # - [Integer] unsubs the number of unsubscribes for this user in the last 90 days
209
+ # - [Integer] opens the number of times emails have been opened for this user in the last 90 days
210
+ # - [Integer] unique_opens the number of unique opens for emails sent for this user in the last 90 days
211
+ # - [Integer] clicks the number of URLs that have been clicked for this user in the last 90 days
212
+ # - [Integer] unique_clicks the number of unique clicks for emails sent for this user in the last 90 days
213
+ # - [Hash] all_time stats for the lifetime of the user's account
214
+ # - [Integer] sent the number of emails sent in the lifetime of the user's account
215
+ # - [Integer] hard_bounces the number of emails hard bounced in the lifetime of the user's account
216
+ # - [Integer] soft_bounces the number of emails soft bounced in the lifetime of the user's account
217
+ # - [Integer] rejects the number of emails rejected for sending this user so far today
218
+ # - [Integer] complaints the number of spam complaints in the lifetime of the user's account
219
+ # - [Integer] unsubs the number of unsubscribes in the lifetime of the user's account
220
+ # - [Integer] opens the number of times emails have been opened in the lifetime of the user's account
221
+ # - [Integer] unique_opens the number of unique opens for emails sent in the lifetime of the user's account
222
+ # - [Integer] clicks the number of URLs that have been clicked in the lifetime of the user's account
223
+ # - [Integer] unique_clicks the number of unique clicks for emails sent in the lifetime of the user's account
50
224
  def info()
51
225
  _params = {}
52
226
  return @master.call 'users/info', _params
53
227
  end
228
+
229
+ # Validate an API key and respond to a ping (anal JSON parser version)
230
+ # @return [Hash] a struct with one key "PING" with a static value "PONG!"
54
231
  def ping()
55
232
  _params = {}
56
233
  return @master.call 'users/ping2', _params
57
234
  end
235
+
236
+ # Return the senders that have tried to use this account, both verified and unverified
237
+ # @return [Array] an array of sender data, one for each sending addresses used by the account
238
+ # - [Hash] return[] the information on each sending address in the account
239
+ # - [String] address the sender's email address
240
+ # - [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
241
+ # - [Integer] sent the total number of messages sent by this sender
242
+ # - [Integer] hard_bounces the total number of hard bounces by messages by this sender
243
+ # - [Integer] soft_bounces the total number of soft bounces by messages by this sender
244
+ # - [Integer] rejects the total number of rejected messages by this sender
245
+ # - [Integer] complaints the total number of spam complaints received for messages by this sender
246
+ # - [Integer] unsubs the total number of unsubscribe requests received for messages by this sender
247
+ # - [Integer] opens the total number of times messages by this sender have been opened
248
+ # - [Integer] clicks the total number of times tracked URLs in messages by this sender have been clicked
58
249
  def senders()
59
250
  _params = {}
60
251
  return @master.call 'users/senders', _params
61
252
  end
253
+
62
254
  end
63
255
  class Rejects
64
256
  attr_accessor :master
@@ -67,14 +259,31 @@ module Mandrill
67
259
  @master = master
68
260
  end
69
261
 
262
+ # Retrieves your email rejection blacklist. You can provide an email address to limit the results. Returns up to 1000 results.
263
+ # @param [String] email an optional email address to search by
264
+ # @return [Array] Up to 1000 rejection entries
265
+ # - [Hash] return[] the information for each rejection blacklist entry
266
+ # - [String] email the email that is blocked
267
+ # - [String] reason the type of event (hard-bounce, soft-bounce, spam, unsub) that caused this rejection
268
+ # - [String] created_at when the email was added to the blacklist
269
+ # - [String] expires_at when the blacklist entry will expire (this may be in the past)
270
+ # - [Boolean] expired whether the blacklist entry has expired
271
+ # - [Hash] Sender sender the sender that this blacklist entry applies to, or null if none.
70
272
  def list(email=nil)
71
273
  _params = {:email => email}
72
274
  return @master.call 'rejects/list', _params
73
275
  end
276
+
277
+ # 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.
278
+ # @param [String] email an email address
279
+ # @return [Hash] a status object containing the address and whether the deletion succeeded.
280
+ # - [String] email the email address that was removed from the blacklist
281
+ # - [Boolean] deleted whether the address was deleted successfully.
74
282
  def delete(email)
75
283
  _params = {:email => email}
76
284
  return @master.call 'rejects/delete', _params
77
285
  end
286
+
78
287
  end
79
288
  class Tags
80
289
  attr_accessor :master
@@ -83,22 +292,133 @@ module Mandrill
83
292
  @master = master
84
293
  end
85
294
 
295
+ # Return all of the user-defined tag information
296
+ # @return [Array] a list of user-defined tags
297
+ # - [Hash] return[] a user-defined tag
298
+ # - [String] tag the actual tag as a string
299
+ # - [Integer] sent the total number of messages sent with this tag
300
+ # - [Integer] hard_bounces the total number of hard bounces by messages with this tag
301
+ # - [Integer] soft_bounces the total number of soft bounces by messages with this tag
302
+ # - [Integer] rejects the total number of rejected messages with this tag
303
+ # - [Integer] complaints the total number of spam complaints received for messages with this tag
304
+ # - [Integer] unsubs the total number of unsubscribe requests received for messages with this tag
305
+ # - [Integer] opens the total number of times messages with this tag have been opened
306
+ # - [Integer] clicks the total number of times tracked URLs in messages with this tag have been clicked
86
307
  def list()
87
308
  _params = {}
88
309
  return @master.call 'tags/list', _params
89
310
  end
311
+
312
+ # Return more detailed information about a single tag, including aggregates of recent stats
313
+ # @param [String] tag an existing tag name
314
+ # @return [Hash] the detailed information on the tag
315
+ # - [String] tag the actual tag as a string
316
+ # - [Integer] sent the total number of messages sent with this tag
317
+ # - [Integer] hard_bounces the total number of hard bounces by messages with this tag
318
+ # - [Integer] soft_bounces the total number of soft bounces by messages with this tag
319
+ # - [Integer] rejects the total number of rejected messages with this tag
320
+ # - [Integer] complaints the total number of spam complaints received for messages with this tag
321
+ # - [Integer] unsubs the total number of unsubscribe requests received for messages with this tag
322
+ # - [Integer] opens the total number of times messages with this tag have been opened
323
+ # - [Integer] clicks the total number of times tracked URLs in messages with this tag have been clicked
324
+ # - [Hash] stats an aggregate summary of the tag's sending stats
325
+ # - [Hash] today stats with this tag so far today
326
+ # - [Integer] sent the number of emails sent with this tag so far today
327
+ # - [Integer] hard_bounces the number of emails hard bounced with this tag so far today
328
+ # - [Integer] soft_bounces the number of emails soft bounced with this tag so far today
329
+ # - [Integer] rejects the number of emails rejected for sending this tag so far today
330
+ # - [Integer] complaints the number of spam complaints with this tag so far today
331
+ # - [Integer] unsubs the number of unsubscribes with this tag so far today
332
+ # - [Integer] opens the number of times emails have been opened with this tag so far today
333
+ # - [Integer] unique_opens the number of unique opens for emails sent with this tag so far today
334
+ # - [Integer] clicks the number of URLs that have been clicked with this tag so far today
335
+ # - [Integer] unique_clicks the number of unique clicks for emails sent with this tag so far today
336
+ # - [Hash] last_7_days stats with this tag in the last 7 days
337
+ # - [Integer] sent the number of emails sent with this tag in the last 7 days
338
+ # - [Integer] hard_bounces the number of emails hard bounced with this tag in the last 7 days
339
+ # - [Integer] soft_bounces the number of emails soft bounced with this tag in the last 7 days
340
+ # - [Integer] rejects the number of emails rejected for sending this tag in the last 7 days
341
+ # - [Integer] complaints the number of spam complaints with this tag in the last 7 days
342
+ # - [Integer] unsubs the number of unsubscribes with this tag in the last 7 days
343
+ # - [Integer] opens the number of times emails have been opened with this tag in the last 7 days
344
+ # - [Integer] unique_opens the number of unique opens for emails sent with this tag in the last 7 days
345
+ # - [Integer] clicks the number of URLs that have been clicked with this tag in the last 7 days
346
+ # - [Integer] unique_clicks the number of unique clicks for emails sent with this tag in the last 7 days
347
+ # - [Hash] last_30_days stats with this tag in the last 30 days
348
+ # - [Integer] sent the number of emails sent with this tag in the last 30 days
349
+ # - [Integer] hard_bounces the number of emails hard bounced with this tag in the last 30 days
350
+ # - [Integer] soft_bounces the number of emails soft bounced with this tag in the last 30 days
351
+ # - [Integer] rejects the number of emails rejected for sending this tag in the last 30 days
352
+ # - [Integer] complaints the number of spam complaints with this tag in the last 30 days
353
+ # - [Integer] unsubs the number of unsubscribes with this tag in the last 30 days
354
+ # - [Integer] opens the number of times emails have been opened with this tag in the last 30 days
355
+ # - [Integer] unique_opens the number of unique opens for emails sent with this tag in the last 30 days
356
+ # - [Integer] clicks the number of URLs that have been clicked with this tag in the last 30 days
357
+ # - [Integer] unique_clicks the number of unique clicks for emails sent with this tag in the last 30 days
358
+ # - [Hash] last_60_days stats with this tag in the last 60 days
359
+ # - [Integer] sent the number of emails sent with this tag in the last 60 days
360
+ # - [Integer] hard_bounces the number of emails hard bounced with this tag in the last 60 days
361
+ # - [Integer] soft_bounces the number of emails soft bounced with this tag in the last 60 days
362
+ # - [Integer] rejects the number of emails rejected for sending this tag in the last 60 days
363
+ # - [Integer] complaints the number of spam complaints with this tag in the last 60 days
364
+ # - [Integer] unsubs the number of unsubscribes with this tag in the last 60 days
365
+ # - [Integer] opens the number of times emails have been opened with this tag in the last 60 days
366
+ # - [Integer] unique_opens the number of unique opens for emails sent with this tag in the last 60 days
367
+ # - [Integer] clicks the number of URLs that have been clicked with this tag in the last 60 days
368
+ # - [Integer] unique_clicks the number of unique clicks for emails sent with this tag in the last 60 days
369
+ # - [Hash] last_90_days stats with this tag in the last 90 days
370
+ # - [Integer] sent the number of emails sent with this tag in the last 90 days
371
+ # - [Integer] hard_bounces the number of emails hard bounced with this tag in the last 90 days
372
+ # - [Integer] soft_bounces the number of emails soft bounced with this tag in the last 90 days
373
+ # - [Integer] rejects the number of emails rejected for sending this tag in the last 90 days
374
+ # - [Integer] complaints the number of spam complaints with this tag in the last 90 days
375
+ # - [Integer] unsubs the number of unsubscribes with this tag in the last 90 days
376
+ # - [Integer] opens the number of times emails have been opened with this tag in the last 90 days
377
+ # - [Integer] unique_opens the number of unique opens for emails sent with this tag in the last 90 days
378
+ # - [Integer] clicks the number of URLs that have been clicked with this tag in the last 90 days
379
+ # - [Integer] unique_clicks the number of unique clicks for emails sent with this tag in the last 90 days
90
380
  def info(tag)
91
381
  _params = {:tag => tag}
92
382
  return @master.call 'tags/info', _params
93
383
  end
384
+
385
+ # Return the recent history (hourly stats for the last 30 days) for a tag
386
+ # @param [String] tag an existing tag name
387
+ # @return [Array] the array of history information
388
+ # - [Hash] return[] the stats for a single hour
389
+ # - [String] time the hour as a UTC date string in YYYY-MM-DD HH:MM:SS format
390
+ # - [Integer] sent the number of emails that were sent during the hour
391
+ # - [Integer] hard_bounces the number of emails that hard bounced during the hour
392
+ # - [Integer] soft_bounces the number of emails that soft bounced during the hour
393
+ # - [Integer] rejects the number of emails that were rejected during the hour
394
+ # - [Integer] complaints the number of spam complaints received during the hour
395
+ # - [Integer] opens the number of emails opened during the hour
396
+ # - [Integer] unique_opens the number of unique opens generated by messages sent during the hour
397
+ # - [Integer] clicks the number of tracked URLs clicked during the hour
398
+ # - [Integer] unique_clicks the number of unique clicks generated by messages sent during the hour
94
399
  def time_series(tag)
95
400
  _params = {:tag => tag}
96
401
  return @master.call 'tags/time-series', _params
97
402
  end
403
+
404
+ # Return the recent history (hourly stats for the last 30 days) for all tags
405
+ # @return [Array] the array of history information
406
+ # - [Hash] return[] the stats for a single hour
407
+ # - [String] time the hour as a UTC date string in YYYY-MM-DD HH:MM:SS format
408
+ # - [Integer] sent the number of emails that were sent during the hour
409
+ # - [Integer] hard_bounces the number of emails that hard bounced during the hour
410
+ # - [Integer] soft_bounces the number of emails that soft bounced during the hour
411
+ # - [Integer] rejects the number of emails that were rejected during the hour
412
+ # - [Integer] complaints the number of spam complaints received during the hour
413
+ # - [Integer] opens the number of emails opened during the hour
414
+ # - [Integer] unique_opens the number of unique opens generated by messages sent during the hour
415
+ # - [Integer] clicks the number of tracked URLs clicked during the hour
416
+ # - [Integer] unique_clicks the number of unique clicks generated by messages sent during the hour
98
417
  def all_time_series()
99
418
  _params = {}
100
419
  return @master.call 'tags/all-time-series', _params
101
420
  end
421
+
102
422
  end
103
423
  class Messages
104
424
  attr_accessor :master
@@ -107,26 +427,169 @@ module Mandrill
107
427
  @master = master
108
428
  end
109
429
 
430
+ # Send a new transactional message through Mandrill
431
+ # @param [Hash] message the information on the message to send
432
+ # - [String] html the full HTML content to be sent
433
+ # - [String] text optional full text content to be sent
434
+ # - [String] subject the message subject
435
+ # - [String] from_email the sender email address.
436
+ # - [String] from_name optional from name to be used
437
+ # - [Array] to an array of recipient information.
438
+ # - [Hash] to[] a single recipient's information.
439
+ # - [String] email the email address of the recipient
440
+ # - [String] name the optional display name to use for the recipient
441
+ # - [Hash] headers optional extra headers to add to the message (currently only Reply-To and X-* headers are allowed)
442
+ # - [Boolean] track_opens whether or not to turn on open tracking for the message
443
+ # - [Boolean] track_clicks whether or not to turn on click tracking for the message
444
+ # - [Boolean] auto_text whether or not to automatically generate a text part for messages that are not given text
445
+ # - [Boolean] url_strip_qs whether or not to strip the query string from URLs when aggregating tracked URL data
446
+ # - [Boolean] preserve_recipients whether or not to expose all recipients in to "To" header for each email
447
+ # - [String] bcc_address an optional address to receive an exact copy of each recipient's email
448
+ # - [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.
449
+ # - [Array] global_merge_vars global merge variables to use for all recipients. You can override these per recipient.
450
+ # - [Hash] global_merge_vars[] a single global merge variable
451
+ # - [String] name the global merge variable's name. Merge variable names are case-insensitive and may not start with _
452
+ # - [String] content the global merge variable's content
453
+ # - [Array] merge_vars per-recipient merge variables, which override global merge variables with the same name.
454
+ # - [Hash] merge_vars[] per-recipient merge variables
455
+ # - [String] rcpt the email address of the recipient that the merge variables should apply to
456
+ # - [Array] vars the recipient's merge variables
457
+ # - [Hash] vars[] a single merge variable
458
+ # - [String] name the merge variable's name. Merge variable names are case-insensitive and may not start with _
459
+ # - [String] content the merge variable's content
460
+ # - [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.
461
+ # - [String] tags[] a single tag - must not start with an underscore
462
+ # - [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.
463
+ # - [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.
464
+ # - [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.
465
+ # - [Array] attachments an array of supported attachments to add to the message
466
+ # - [Hash] attachments[] a single supported attachment
467
+ # - [String] type the MIME type of the attachment - allowed types are text/*, image/*, and application/pdf
468
+ # - [String] name the file name of the attachment
469
+ # - [String] content the content of the attachment as a base64-encoded string
470
+ # @return [Array] of structs for each recipient containing the key "email" with the email address and "status" as either "sent", "queued", or "rejected"
471
+ # - [Hash] return[] the sending results for a single recipient
472
+ # - [String] email the email address of the recipient
473
+ # - [String] status the sending status of the recipient - either "sent", "queued", "rejected", or "invalid"
110
474
  def send(message)
111
475
  _params = {:message => message}
112
476
  return @master.call 'messages/send', _params
113
477
  end
478
+
479
+ # Send a new transactional message through Mandrill using a template
480
+ # @param [String] template_name the name of a template that exists in the user's account
481
+ # @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
482
+ # - [Hash] template_content[] the injection of a single piece of content into a single editable region
483
+ # - [String] name the name of the mc:edit editable region to inject into
484
+ # - [String] content the content to inject
485
+ # @param [Hash] message the other information on the message to send - same as /messages/send, but without the html content
486
+ # - [String] text optional full text content to be sent
487
+ # - [String] subject the message subject
488
+ # - [String] from_email the sender email address.
489
+ # - [String] from_name optional from name to be used
490
+ # - [Array] to an array of recipient information.
491
+ # - [Hash] to[] a single recipient's information.
492
+ # - [String] email the email address of the recipient
493
+ # - [String] name the optional display name to use for the recipient
494
+ # - [Hash] headers optional extra headers to add to the message (currently only Reply-To and X-* headers are allowed)
495
+ # - [Boolean] track_opens whether or not to turn on open tracking for the message
496
+ # - [Boolean] track_clicks whether or not to turn on click tracking for the message
497
+ # - [Boolean] auto_text whether or not to automatically generate a text part for messages that are not given text
498
+ # - [Boolean] url_strip_qs whether or not to strip the query string from URLs when aggregating tracked URL data
499
+ # - [Boolean] preserve_recipients whether or not to expose all recipients in to "To" header for each email
500
+ # - [String] bcc_address an optional address to receive an exact copy of each recipient's email
501
+ # - [Array] global_merge_vars global merge variables to use for all recipients. You can override these per recipient.
502
+ # - [Hash] global_merge_vars[] a single global merge variable
503
+ # - [String] name the global merge variable's name. Merge variable names are case-insensitive and may not start with _
504
+ # - [String] content the global merge variable's content
505
+ # - [Array] merge_vars per-recipient merge variables, which override global merge variables with the same name.
506
+ # - [Hash] merge_vars[] per-recipient merge variables
507
+ # - [String] rcpt the email address of the recipient that the merge variables should apply to
508
+ # - [Array] vars the recipient's merge variables
509
+ # - [Hash] vars[] a single merge variable
510
+ # - [String] name the merge variable's name. Merge variable names are case-insensitive and may not start with _
511
+ # - [String] content the merge variable's content
512
+ # - [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.
513
+ # - [String] tags[] a single tag - must not start with an underscore
514
+ # - [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.
515
+ # - [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.
516
+ # - [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.
517
+ # - [Array] attachments an array of supported attachments to add to the message
518
+ # - [Hash] attachments[] a single supported attachment
519
+ # - [String] type the MIME type of the attachment - allowed types are text/*, image/*, and application/pdf
520
+ # - [String] name the file name of the attachment
521
+ # - [String] content the content of the attachment as a base64-encoded string
522
+ # @return [Array] of structs for each recipient containing the key "email" with the email address and "status" as either "sent", "queued", or "rejected"
523
+ # - [Hash] return[] the sending results for a single recipient
524
+ # - [String] email the email address of the recipient
525
+ # - [String] status the sending status of the recipient - either "sent", "queued", "rejected", or "invalid"
114
526
  def send_template(template_name, template_content, message)
115
527
  _params = {:template_name => template_name, :template_content => template_content, :message => message}
116
528
  return @master.call 'messages/send-template', _params
117
529
  end
530
+
531
+ # Search the content of recently sent messages and optionally narrow by date range, tags and senders
532
+ # @param [String] query the search terms to find matching messages for
533
+ # @param [String] date_from start date
534
+ # @param [String] date_to end date
535
+ # @param [Array] tags an array of tag names to narrow the search to, will return messages that contain ANY of the tags
536
+ # @param [Array] senders an array of sender addresses to narrow the search to, will return messages sent by ANY of the senders
537
+ # @param [Integer] limit the maximum number of results to return, defaults to 100, 1000 is the maximum
538
+ # @return [Array] of structs for each matching message
539
+ # - [Hash] return[] the information for a single matching message
540
+ # - [Integer] ts the Unix timestamp from when this message was sent
541
+ # - [String] sender the email address of the sender
542
+ # - [String] subject the message's subject link
543
+ # - [String] email the recipient email address
544
+ # - [Array] tags list of tags on this message
545
+ # - [String] tags[] individual tag on this message
546
+ # - [Integer] opens how many times has this message been opened
547
+ # - [Integer] clicks how many times has a link been clicked in this message
548
+ # - [String] state sending status of this message: sent, bounced, rejected
118
549
  def search(query='*', date_from=nil, date_to=nil, tags=nil, senders=nil, limit=100)
119
550
  _params = {:query => query, :date_from => date_from, :date_to => date_to, :tags => tags, :senders => senders, :limit => limit}
120
551
  return @master.call 'messages/search', _params
121
552
  end
553
+
554
+ # Parse the full MIME document for an email message, returning the content of the message broken into its constituent pieces
555
+ # @param [String] raw_message the full MIME document of an email message
556
+ # @return [Hash] the parsed message
557
+ # - [String] subject the subject of the message
558
+ # - [String] from_email the email address of the sender
559
+ # - [String] from_name the alias of the sender (if any)
560
+ # - [Array] to an array of any recipients in the message
561
+ # - [Hash] to[] the information on a single recipient
562
+ # - [String] email the email address of the recipient
563
+ # - [String] name the alias of the recipient (if any)
564
+ # - [Hash] headers the key-value pairs of the MIME headers for the message's main document
565
+ # - [String] text the text part of the message, if any
566
+ # - [String] html the HTML part of the message, if any
567
+ # - [Array] attachments an array of any attachments that can be found in the message
568
+ # - [Hash] attachments[] information about an individual attachment
569
+ # - [String] name the file name of the attachment
570
+ # - [String] type the MIME type of the attachment
571
+ # - [Boolean] binary if this is set to true, the attachment is not pure-text, and the content will be base64 encoded
572
+ # - [String] content the content of the attachment as a text string or a base64 encoded string based on the attachment type
122
573
  def parse(raw_message)
123
574
  _params = {:raw_message => raw_message}
124
575
  return @master.call 'messages/parse', _params
125
576
  end
577
+
578
+ # Take a raw MIME document for a message, and send it exactly as if it were sent over the SMTP protocol
579
+ # @param [String] raw_message the full MIME document of an email message
580
+ # @param [String, nil] from_email optionally define the sender address - otherwise we'll use the address found in the provided headers
581
+ # @param [String, nil] from_name optionally define the sender alias
582
+ # @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
583
+ # - [String] to[] the email address of the recipint
584
+ # @return [Array] of structs for each recipient containing the key "email" with the email address and "status" as either "sent", "queued", or "rejected"
585
+ # - [Hash] return[] the sending results for a single recipient
586
+ # - [String] email the email address of the recipient
587
+ # - [String] status the sending status of the recipient - either "sent", "queued", "rejected", or "invalid"
126
588
  def send_raw(raw_message, from_email=nil, from_name=nil, to=nil)
127
589
  _params = {:raw_message => raw_message, :from_email => from_email, :from_name => from_name, :to => to}
128
590
  return @master.call 'messages/send-raw', _params
129
591
  end
592
+
130
593
  end
131
594
  class Urls
132
595
  attr_accessor :master
@@ -135,18 +598,44 @@ module Mandrill
135
598
  @master = master
136
599
  end
137
600
 
601
+ # Get the 100 most clicked URLs
602
+ # @return [Array] the 100 most clicked URLs and their stats
603
+ # - [Hash] return[] the individual URL stats
604
+ # - [String] url the URL to be tracked
605
+ # - [Integer] sent the number of emails that contained the URL
606
+ # - [Integer] clicks the number of times the URL has been clicked from a tracked email
607
+ # - [Integer] unique_clicks the number of unique emails that have benerated clicks for this URL
138
608
  def list()
139
609
  _params = {}
140
610
  return @master.call 'urls/list', _params
141
611
  end
612
+
613
+ # Return the 100 most clicked URLs that match the search query given
614
+ # @param [String] q a search query
615
+ # @return [Array] the 100 most clicked URLs matching the search query
616
+ # - [Hash] return[] the URL matching the query
617
+ # - [String] url the URL to be tracked
618
+ # - [Integer] sent the number of emails that contained the URL
619
+ # - [Integer] clicks the number of times the URL has been clicked from a tracked email
620
+ # - [Integer] unique_clicks the number of unique emails that have benerated clicks for this URL
142
621
  def search(q)
143
622
  _params = {:q => q}
144
623
  return @master.call 'urls/search', _params
145
624
  end
625
+
626
+ # Return the recent history (hourly stats for the last 30 days) for a url
627
+ # @param [String] url an existing URL
628
+ # @return [Array] the array of history information
629
+ # - [Hash] return[] the information for a single hour
630
+ # - [String] time the hour as a UTC date string in YYYY-MM-DD HH:MM:SS format
631
+ # - [Integer] sent the number of emails that were sent with the URL during the hour
632
+ # - [Integer] clicks the number of times the URL was clicked during the hour
633
+ # - [Integer] unique_clicks the number of unique clicks generated for emails sent with this URL during the hour
146
634
  def time_series(url)
147
635
  _params = {:url => url}
148
636
  return @master.call 'urls/time-series', _params
149
637
  end
638
+
150
639
  end
151
640
  class Webhooks
152
641
  attr_accessor :master
@@ -155,26 +644,96 @@ module Mandrill
155
644
  @master = master
156
645
  end
157
646
 
647
+ # Get the list of all webhooks defined on the account
648
+ # @return [Array] the webhooks associated with the account
649
+ # - [Hash] return[] the inidividual webhook info
650
+ # - [Integer] id a unique integer indentifier for the webhook
651
+ # - [String] url The URL that the event data will be posted to
652
+ # - [Array] events The message events that will be posted to the hook
653
+ # - [String] events[] the individual message event (send, hard_bounce, soft_bounce, open, click, spam, unsub, or reject)
654
+ # - [String] created_at the date and time that the webhook was created as a UTC string in YYYY-MM-DD HH:MM:SS format
655
+ # - [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
656
+ # - [Integer] batches_sent the number of event batches that have ever been sent to this webhook
657
+ # - [Integer] events_sent the total number of events that have ever been sent to this webhook
658
+ # - [String] last_error if we've ever gotten an error trying to post to this webhook, the last error that we've seen
158
659
  def list()
159
660
  _params = {}
160
661
  return @master.call 'webhooks/list', _params
161
662
  end
663
+
664
+ # Add a new webhook
665
+ # @param [String] url the URL to POST batches of events
666
+ # @param [Array] events an optional list of events that will be posted to the webhook
667
+ # - [String] events[] the individual event to listen for
668
+ # @return [Hash] the information saved about the new webhook
669
+ # - [Integer] id a unique integer indentifier for the webhook
670
+ # - [String] url The URL that the event data will be posted to
671
+ # - [Array] events The message events that will be posted to the hook
672
+ # - [String] events[] the individual message event (send, hard_bounce, soft_bounce, open, click, spam, unsub, or reject)
673
+ # - [String] created_at the date and time that the webhook was created as a UTC string in YYYY-MM-DD HH:MM:SS format
674
+ # - [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
675
+ # - [Integer] batches_sent the number of event batches that have ever been sent to this webhook
676
+ # - [Integer] events_sent the total number of events that have ever been sent to this webhook
677
+ # - [String] last_error if we've ever gotten an error trying to post to this webhook, the last error that we've seen
162
678
  def add(url, events=[])
163
679
  _params = {:url => url, :events => events}
164
680
  return @master.call 'webhooks/add', _params
165
681
  end
682
+
683
+ # Given the ID of an existing webhook, return the data about it
684
+ # @param [Integer] id the unique identifier of a webhook belonging to this account
685
+ # @return [Hash] the information about the webhook
686
+ # - [Integer] id a unique integer indentifier for the webhook
687
+ # - [String] url The URL that the event data will be posted to
688
+ # - [Array] events The message events that will be posted to the hook
689
+ # - [String] events[] the individual message event (send, hard_bounce, soft_bounce, open, click, spam, unsub, or reject)
690
+ # - [String] created_at the date and time that the webhook was created as a UTC string in YYYY-MM-DD HH:MM:SS format
691
+ # - [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
692
+ # - [Integer] batches_sent the number of event batches that have ever been sent to this webhook
693
+ # - [Integer] events_sent the total number of events that have ever been sent to this webhook
694
+ # - [String] last_error if we've ever gotten an error trying to post to this webhook, the last error that we've seen
166
695
  def info(id)
167
696
  _params = {:id => id}
168
697
  return @master.call 'webhooks/info', _params
169
698
  end
699
+
700
+ # Update an existing webhook
701
+ # @param [Integer] id the unique identifier of a webhook belonging to this account
702
+ # @param [String] url the URL to POST batches of events
703
+ # @param [Array] events an optional list of events that will be posted to the webhook
704
+ # - [String] events[] the individual event to listen for
705
+ # @return [Hash] the information for the updated webhook
706
+ # - [Integer] id a unique integer indentifier for the webhook
707
+ # - [String] url The URL that the event data will be posted to
708
+ # - [Array] events The message events that will be posted to the hook
709
+ # - [String] events[] the individual message event (send, hard_bounce, soft_bounce, open, click, spam, unsub, or reject)
710
+ # - [String] created_at the date and time that the webhook was created as a UTC string in YYYY-MM-DD HH:MM:SS format
711
+ # - [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
712
+ # - [Integer] batches_sent the number of event batches that have ever been sent to this webhook
713
+ # - [Integer] events_sent the total number of events that have ever been sent to this webhook
714
+ # - [String] last_error if we've ever gotten an error trying to post to this webhook, the last error that we've seen
170
715
  def update(id, url, events=[])
171
716
  _params = {:id => id, :url => url, :events => events}
172
717
  return @master.call 'webhooks/update', _params
173
718
  end
719
+
720
+ # Delete an existing webhook
721
+ # @param [Integer] id the unique identifier of a webhook belonging to this account
722
+ # @return [Hash] the information for the deleted webhook
723
+ # - [Integer] id a unique integer indentifier for the webhook
724
+ # - [String] url The URL that the event data will be posted to
725
+ # - [Array] events The message events that will be posted to the hook
726
+ # - [String] events[] the individual message event (send, hard_bounce, soft_bounce, open, click, spam, unsub, or reject)
727
+ # - [String] created_at the date and time that the webhook was created as a UTC string in YYYY-MM-DD HH:MM:SS format
728
+ # - [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
729
+ # - [Integer] batches_sent the number of event batches that have ever been sent to this webhook
730
+ # - [Integer] events_sent the total number of events that have ever been sent to this webhook
731
+ # - [String] last_error if we've ever gotten an error trying to post to this webhook, the last error that we've seen
174
732
  def delete(id)
175
733
  _params = {:id => id}
176
734
  return @master.call 'webhooks/delete', _params
177
735
  end
736
+
178
737
  end
179
738
  class Senders
180
739
  attr_accessor :master
@@ -183,22 +742,127 @@ module Mandrill
183
742
  @master = master
184
743
  end
185
744
 
745
+ # Return the senders that have tried to use this account.
746
+ # @return [Array] an array of sender data, one for each sending addresses used by the account
747
+ # - [Hash] return[] the information on each sending address in the account
748
+ # - [String] address the sender's email address
749
+ # - [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
750
+ # - [Integer] sent the total number of messages sent by this sender
751
+ # - [Integer] hard_bounces the total number of hard bounces by messages by this sender
752
+ # - [Integer] soft_bounces the total number of soft bounces by messages by this sender
753
+ # - [Integer] rejects the total number of rejected messages by this sender
754
+ # - [Integer] complaints the total number of spam complaints received for messages by this sender
755
+ # - [Integer] unsubs the total number of unsubscribe requests received for messages by this sender
756
+ # - [Integer] opens the total number of times messages by this sender have been opened
757
+ # - [Integer] clicks the total number of times tracked URLs in messages by this sender have been clicked
186
758
  def list()
187
759
  _params = {}
188
760
  return @master.call 'senders/list', _params
189
761
  end
762
+
763
+ # Returns the sender domains that have been added to this account.
764
+ # @return [Array] an array of sender domain data, one for each sending domain used by the account
765
+ # - [Hash] return[] the information on each sending domain for the account
766
+ # - [String] domain the sender domain name
767
+ # - [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
190
768
  def domains()
191
769
  _params = {}
192
770
  return @master.call 'senders/domains', _params
193
771
  end
772
+
773
+ # Return more detailed information about a single sender, including aggregates of recent stats
774
+ # @param [String] address the email address of the sender
775
+ # @return [Hash] the detailed information on the sender
776
+ # - [String] address the sender's email address
777
+ # - [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
778
+ # - [Integer] sent the total number of messages sent by this sender
779
+ # - [Integer] hard_bounces the total number of hard bounces by messages by this sender
780
+ # - [Integer] soft_bounces the total number of soft bounces by messages by this sender
781
+ # - [Integer] rejects the total number of rejected messages by this sender
782
+ # - [Integer] complaints the total number of spam complaints received for messages by this sender
783
+ # - [Integer] unsubs the total number of unsubscribe requests received for messages by this sender
784
+ # - [Integer] opens the total number of times messages by this sender have been opened
785
+ # - [Integer] clicks the total number of times tracked URLs in messages by this sender have been clicked
786
+ # - [Hash] stats an aggregate summary of the sender's sending stats
787
+ # - [Hash] today stats for this sender so far today
788
+ # - [Integer] sent the number of emails sent for this sender so far today
789
+ # - [Integer] hard_bounces the number of emails hard bounced for this sender so far today
790
+ # - [Integer] soft_bounces the number of emails soft bounced for this sender so far today
791
+ # - [Integer] rejects the number of emails rejected for sending this sender so far today
792
+ # - [Integer] complaints the number of spam complaints for this sender so far today
793
+ # - [Integer] unsubs the number of unsubscribes for this sender so far today
794
+ # - [Integer] opens the number of times emails have been opened for this sender so far today
795
+ # - [Integer] unique_opens the number of unique opens for emails sent for this sender so far today
796
+ # - [Integer] clicks the number of URLs that have been clicked for this sender so far today
797
+ # - [Integer] unique_clicks the number of unique clicks for emails sent for this sender so far today
798
+ # - [Hash] last_7_days stats for this sender in the last 7 days
799
+ # - [Integer] sent the number of emails sent for this sender in the last 7 days
800
+ # - [Integer] hard_bounces the number of emails hard bounced for this sender in the last 7 days
801
+ # - [Integer] soft_bounces the number of emails soft bounced for this sender in the last 7 days
802
+ # - [Integer] rejects the number of emails rejected for sending this sender in the last 7 days
803
+ # - [Integer] complaints the number of spam complaints for this sender in the last 7 days
804
+ # - [Integer] unsubs the number of unsubscribes for this sender in the last 7 days
805
+ # - [Integer] opens the number of times emails have been opened for this sender in the last 7 days
806
+ # - [Integer] unique_opens the number of unique opens for emails sent for this sender in the last 7 days
807
+ # - [Integer] clicks the number of URLs that have been clicked for this sender in the last 7 days
808
+ # - [Integer] unique_clicks the number of unique clicks for emails sent for this sender in the last 7 days
809
+ # - [Hash] last_30_days stats for this sender in the last 30 days
810
+ # - [Integer] sent the number of emails sent for this sender in the last 30 days
811
+ # - [Integer] hard_bounces the number of emails hard bounced for this sender in the last 30 days
812
+ # - [Integer] soft_bounces the number of emails soft bounced for this sender in the last 30 days
813
+ # - [Integer] rejects the number of emails rejected for sending this sender in the last 30 days
814
+ # - [Integer] complaints the number of spam complaints for this sender in the last 30 days
815
+ # - [Integer] unsubs the number of unsubscribes for this sender in the last 30 days
816
+ # - [Integer] opens the number of times emails have been opened for this sender in the last 30 days
817
+ # - [Integer] unique_opens the number of unique opens for emails sent for this sender in the last 30 days
818
+ # - [Integer] clicks the number of URLs that have been clicked for this sender in the last 30 days
819
+ # - [Integer] unique_clicks the number of unique clicks for emails sent for this sender in the last 30 days
820
+ # - [Hash] last_60_days stats for this sender in the last 60 days
821
+ # - [Integer] sent the number of emails sent for this sender in the last 60 days
822
+ # - [Integer] hard_bounces the number of emails hard bounced for this sender in the last 60 days
823
+ # - [Integer] soft_bounces the number of emails soft bounced for this sender in the last 60 days
824
+ # - [Integer] rejects the number of emails rejected for sending this sender in the last 60 days
825
+ # - [Integer] complaints the number of spam complaints for this sender in the last 60 days
826
+ # - [Integer] unsubs the number of unsubscribes for this sender in the last 60 days
827
+ # - [Integer] opens the number of times emails have been opened for this sender in the last 60 days
828
+ # - [Integer] unique_opens the number of unique opens for emails sent for this sender in the last 60 days
829
+ # - [Integer] clicks the number of URLs that have been clicked for this sender in the last 60 days
830
+ # - [Integer] unique_clicks the number of unique clicks for emails sent for this sender in the last 60 days
831
+ # - [Hash] last_90_days stats for this sender in the last 90 days
832
+ # - [Integer] sent the number of emails sent for this sender in the last 90 days
833
+ # - [Integer] hard_bounces the number of emails hard bounced for this sender in the last 90 days
834
+ # - [Integer] soft_bounces the number of emails soft bounced for this sender in the last 90 days
835
+ # - [Integer] rejects the number of emails rejected for sending this sender in the last 90 days
836
+ # - [Integer] complaints the number of spam complaints for this sender in the last 90 days
837
+ # - [Integer] unsubs the number of unsubscribes for this sender in the last 90 days
838
+ # - [Integer] opens the number of times emails have been opened for this sender in the last 90 days
839
+ # - [Integer] unique_opens the number of unique opens for emails sent for this sender in the last 90 days
840
+ # - [Integer] clicks the number of URLs that have been clicked for this sender in the last 90 days
841
+ # - [Integer] unique_clicks the number of unique clicks for emails sent for this sender in the last 90 days
194
842
  def info(address)
195
843
  _params = {:address => address}
196
844
  return @master.call 'senders/info', _params
197
845
  end
846
+
847
+ # Return the recent history (hourly stats for the last 30 days) for a sender
848
+ # @param [String] address the email address of the sender
849
+ # @return [Array] the array of history information
850
+ # - [Hash] return[] the stats for a single hour
851
+ # - [String] time the hour as a UTC date string in YYYY-MM-DD HH:MM:SS format
852
+ # - [Integer] sent the number of emails that were sent during the hour
853
+ # - [Integer] hard_bounces the number of emails that hard bounced during the hour
854
+ # - [Integer] soft_bounces the number of emails that soft bounced during the hour
855
+ # - [Integer] rejects the number of emails that were rejected during the hour
856
+ # - [Integer] complaints the number of spam complaints received during the hour
857
+ # - [Integer] opens the number of emails opened during the hour
858
+ # - [Integer] unique_opens the number of unique opens generated by messages sent during the hour
859
+ # - [Integer] clicks the number of tracked URLs clicked during the hour
860
+ # - [Integer] unique_clicks the number of unique clicks generated by messages sent during the hour
198
861
  def time_series(address)
199
862
  _params = {:address => address}
200
863
  return @master.call 'senders/time-series', _params
201
864
  end
865
+
202
866
  end
203
867
  end
204
868
 
metadata CHANGED
@@ -1,13 +1,13 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: mandrill-api
3
3
  version: !ruby/object:Gem::Version
4
- hash: 19
4
+ hash: 17
5
5
  prerelease:
6
6
  segments:
7
7
  - 1
8
8
  - 0
9
- - 2
10
- version: 1.0.2
9
+ - 3
10
+ version: 1.0.3
11
11
  platform: ruby
12
12
  authors:
13
13
  - Mandrill Devs
@@ -96,3 +96,4 @@ specification_version: 3
96
96
  summary: A Ruby API library for the Mandrill email as a service platform.
97
97
  test_files: []
98
98
 
99
+ has_rdoc: