banshee/cloud-collection/cloud/mandrill/https/sending

Mailchimp Transactional sending

Returns, over a period, the emails a Mailchimp Transactional account (formerly Mandrill) sent, and the parts of them that hard bounced, soft bounced, were rejected or drew a spam complaint, read from its API with an API key that may only read the account. Four watches are offered, each one set on the probe. A rising part of bounces or complaints lowers the reputation of the account, and its quota with it.

Versions

Generic: the API of Mailchimp Transactional, version 1.4, the same for every account.

How it works

POST https://mandrillapp.com/api/1.4/users/info, the body {"key": "<the API key>"}, of type application/json. The statistics of the period chosen on the probe are read from stats:

{"stats": {"last_7_days": {"sent": 1200, "hard_bounces": 6, "soft_bounces": 15, "rejects": 3, "complaints": 1,
 "unsubs": 0, "opens": 640, "unique_opens": 410, "clicks": 90, "unique_clicks": 70}, …}, …}

hard-bounces, soft-bounces and complaints are parts of the emails sent; rejects is a part of the emails submitted, sent or rejected, a rejected email never being sent. Each is in percent, to two decimals.
A count the API leaves out is 0. Over a period with nothing sent, each part is 0.
A code 401 (the key wrong or revoked, or not allowed to call users/info) stops the collector misconfigured; any other code but 200 stops it unreachable.

Why the answer is declared free of tokens

The API takes its key in the JSON body only, and documents no other way to send it. A response to a body that carries a secret is secret, and nothing read from it could be returned: the call declares its answer free of tokens, public=true. The answer of users/info holds the figures of the account (its username, its public ID, its reputation, its quota and its statistics), and never the key. A part of the answer that held the key, as it is, in base64 or encoded for an address, would still be secret, and the collector would stop rather than return it.

Prerequisites

An API key of the account, made in Settings (+ New API Key), limited to the one API call users/info: a key may be restricted to a selection of calls, and with this one it can neither send an email nor read one. Its value goes in protocol:http:token, a secret variable: it only goes in the body of the request.
The poller reaches mandrillapp.com in HTTPS. Its certificate is issued by a public authority: the profile "Standard" trusts it.

Variables

Name	Label	Says	Default
`mandrill:period`	Period	the window of the statistics: `today`, `last_7_days` or `last_30_days`, as Mailchimp Transactional counts them	`last_7_days`

Outputs

Name	Label	Unit	Per instance
`sent`	Sent	emails	no
`hard-bounces`	Hard bounces	%	no
`soft-bounces`	Soft bounces	%	no
`rejects`	Rejected	%	no
`complaints`	Spam complaints	%	no

Watches

Name	Title	Kind	Defaults	Checked by default
`hard-bounces`	Hard bounces high	above, on `hard-bounces`	warning above 2 %, critical above 5 %	yes
`soft-bounces`	Soft bounces high	above, on `soft-bounces`	warning above 10 %	no: a full mailbox or a greylisting server bounces softly, and the email is tried again
`rejects`	Rejects high	above, on `rejects`	warning above 5 %, critical above 10 %	yes
`complaints`	Spam complaints high	above, on `complaints`	warning above 0.1 %, critical above 0.3 %	yes

The defaults are a starting point, to set on the probe after the account's usual figures. Over today, the parts of the first emails of the day move a lot: the last 7 days are steadier.

Limits

One account per probe, the account of the key; the statistics are those of the whole account, every sender and every subaccount together.
Not checked against a Mailchimp Transactional account. The route, its body, the fields of its answer and the code 401 are those of the public reference of the API (mailchimp.com/developer/transactional, "Get account info"), which says each count of a period may be left out; the restriction of a key to some calls is that of its "Fundamentals" page. Whether sent counts the rejected emails is not said there: the part of rejects is taken of the emails sent plus those rejected, and would read a little low if sent already counted them.