MDN

RFC 3798 / RFC 8098 Message Disposition Notification builder + parser. An MDN is the "I read your message" return-receipt — a multipart/report MIME body with a message/disposition-notification segment that names what the user-agent did with the original message (displayed / deleted / dispatched / processed / failed).

Auto-generation discipline: the framework refuses to auto-build an MDN unless the operator explicitly opts in via requireUserConfirmation: false. RFC 3798 §2.1 plus RFC 8098 require user opt-in for MDN delivery — accidental automatic generation leaks behavioural metadata and is a known privacy regression in mail clients. The framework defaults to refusal so the operator codepath has to actively choose to send.

Parser tolerates both bare RFC 3798 reports and the RFC 8098 updated shape (action / sending / disposition modes), surfaces the original-message-id binding, the reporting user-agent string, and the optional original-message attachment.

b.mailMdn.build(opts) #

{
  originalMessageId:        string,         // required — Message-Id of the message being acknowledged
  originalRecipient:        string,         // optional — RFC 5322 address of the original recipient
  finalRecipient:           string,         // required — RFC 5322 address of the final-recipient (may differ after forwarding)
  disposition:              "displayed" | "deleted" | "dispatched" | "processed" | "failed" | "denied",
  actionMode:               "manual-action" | "automatic-action",   // default: manual-action
  sendingMode:              "MDN-sent-manually" | "MDN-sent-automatically", // default: MDN-sent-manually
  reportingUserAgent:       string,         // optional — RFC 3798 §3.2.1 reporting agent name/version
  originalMessage:          string,         // optional — raw RFC 5322 message body to attach as message/rfc822
  from:                     string,         // optional — From: header for the MDN envelope
  to:                       string,         // optional — To: header for the MDN envelope (typically the original sender)
  subject:                  string,         // optional — Subject: header
  dispositionNotificationOptions: string,   // RFC 3798 Disposition-Notification-Options value from the inbound message
  requireUserConfirmation:  boolean,        // default: true — refuse to auto-build unless the operator explicitly opts out
}

Build an RFC 3798 / RFC 8098 multipart/report message body carrying a message/disposition-notification segment. The result is a raw RFC 5322 message body ready for SMTP relay back to the sender.

The framework refuses to auto-generate an MDN (emits the audit row mailmdn.suppressed instead) when:

- The original message's Disposition-Notification-Options header asserted important=required AND - opts.requireUserConfirmation is not explicitly false

RFC 3798 §2.1 requires user opt-in for MDN delivery; the default is refusal so accidental automatic generation by an unattended mail processor cannot leak behavioural metadata. Operators with an explicit "the user clicked send-receipt" code path pass requireUserConfirmation: false to skip the gate.

var b = require("@blamejs/core");
var mdn = b.mailMdn.build({
  originalMessageId:       "",
  finalRecipient:          "user@example.com",
  disposition:             "displayed",
  reportingUserAgent:      "blamejs/0.8.53",
  requireUserConfirmation: false,
});
typeof mdn;                                            // -> "string"
/multipart\/report/.test(mdn);                         // -> true
/message\/disposition-notification/.test(mdn);         // -> true

b.mailMdn.parse(rawMessage) #

Parse a raw RFC 3798 / RFC 8098 multipart/report message into a normalized event shape:

{ messageId: string | null, // outer Message-ID of the MDN itself originalMessageId: string, // Original-Message-ID field originalRecipient: string | null, // Original-Recipient field finalRecipient: string, // Final-Recipient field (required) disposition: { actionMode: "manual-action" | "automatic-action", sendingMode: "mdn-sent-manually" | "mdn-sent-automatically" | null, type: "displayed" | "deleted" | "dispatched" | "processed" | "failed" | "denied", }, reportingUserAgent: string | null, originalMessage: string | null, // attached message/rfc822 body, when present }

Throws MailMdnError on missing top-level Content-Type, non- multipart/report content type, missing message/disposition- notification segment, missing Final-Recipient, or oversized payload.

var b = require("@blamejs/core");
var mdn = b.mailMdn.build({
  originalMessageId:       "",
  finalRecipient:          "user@example.com",
  disposition:             "displayed",
  reportingUserAgent:      "blamejs/0.8.53",
  requireUserConfirmation: false,
});
var parsed = b.mailMdn.parse(mdn);
parsed.disposition.type;       // -> "displayed"
parsed.finalRecipient;         // -> "user@example.com"
parsed.originalMessageId;      // -> ""

Last updated 2026-08-08T16:39:49.652Z by seeder.