Logging without leaking
Mail integrations log more personal data than almost anything else in a system, usually by accident: the natural thing to log when a send fails is the thing you sent.
Never log these
The API key. Not even a prefix plus a few characters, which is enough to confirm a guess. Log the key’s label if you need to know which credential was used.
The message body or template variables. They are the payload, so they are the thing most likely to be dumped in an error handler. If you must log something to debug a render, log the template id and the variable names, never the values.
The webhook signing secret, for the same reason as the key.
Full recipient addresses, by default. This one is a judgement rather than an absolute, because an address is often exactly what you need in order to investigate. If you log them, know that you have put personal data in a system whose retention and access controls were probably designed for debugging rather than for personal data.
Log these instead
| Log | Why |
|---|---|
request_id from the response |
the one identifier that ties your call to our logs |
message_id |
ties your record to delivery events and the message explorer |
Idempotency-Key |
tells you whether a retry was a replay |
HTTP status and the error code |
enough to branch and to aggregate |
| key label | which credential, without the credential |
A failed send logged as request_id, status, code and message_id is
fully diagnosable by us and contains nothing you would mind in a log
aggregator.
Error handlers are where this goes wrong
The usual shape is a catch-all that logs the request body on any exception. It works, it is one line, and on the day something breaks it writes every recipient address and every rendered body into your logs at ERROR level, where alerting copies them somewhere else again.
If you want the body on failure, redact before logging rather than after, and keep the redaction in the logging path rather than at each call site, so a new call site cannot forget.
Third parties see your logs too
Error trackers, log aggregators and APM tools are processors in their own right. Anything you log about a recipient is a transfer to them, and that belongs in your own records of processing rather than being discovered later.
The same is true of breadcrumbs and request captures, which are on by default in several popular SDKs and capture request bodies without being asked.