Correlate returned reports and auto-replies to the message that caused them

[jbagsik]

Parent

#1

What to build

A return that arrives in a polled mailbox is matched back to the message that caused it, and the outcome is recorded on that message's log row and announced.

Two kinds of return matter, and they share all of their matching machinery while meaning opposite things — which is why they are one ticket rather than two:

• A delivery report says an address could not be reached. Permanent (5.x.x) is a failure worth acting on. Transient (4.x.x) is recorded and nothing more — the sending infrastructure retries on its own for hours, and a permanent report would follow if it ultimately fails. Reacting to transient reports manufactures alarms that resolve themselves, and teaches whoever reads them to stop reading them.
• An auto-reply says a mailbox accepted the message but nobody is reading it. It is recorded and never changes delivery state in either direction — not failed, which is untrue, and not delivered, which cannot be proven from the sending side at all.

Matching uses the identifiers minted at send time: the identifier read back from the provider's sent copy, and the self-assigned correlation header as a second key. Two keys because a report carries the original headers usually rather than always. A return that matches nothing is recorded as unmatched and kept — it is evidence, and silently dropping it hides both bugs and genuine traffic.

A report names a recipient address, not a message: a mail to three addresses that fails for one is a failure for that address. The recorded outcome is per address.

This package interprets and correlates. What a failure means for a business document is announced as an event and decided elsewhere.

Acceptance criteria

• A delivery report matching a sent message by the read-back identifier updates that log row and emits an event
• Matching falls back to the correlation header when the read-back identifier is absent from the report
• Permanent and transient reports are recorded distinctly, and a transient one produces no failure outcome
• An auto-reply is correlated and recorded, and produces no delivery-state change of any kind
• The outcome is recorded against the recipient address, so one failing address among several is representable
• A return matching no sent message is recorded as unmatched rather than discarded
• Correlating the same return twice does not duplicate the outcome
• Emitted events carry enough for a consumer to act without reaching into this package's tables
• Tests construct returns directly; no transport and no live mailbox
• README documents the matching keys and the transient/permanent rule; CHANGELOG updated

Blocked by

• Classify inbound messages by kind and gate attachment processing on it mail-inbox#2 — returns must be classified before they can be interpreted.
• Send a mail through SendMailJob and record it in the send log #2 — the identifiers matched on are minted there, at send time.