Email notifications: User behavior and content

Defines user-visible transactional and optional email behavior, including preference precedence, safe links, threading, accessibility, localization, privacy, and a truthful in-product delivery history.

Package status: reference context ready for human review. The contract and test scenarios are complete, but no claim is made that an adopting implementation has passed them.

Decision

Classify every email by purpose before applying preferences. Essential service messages use the narrowest necessary content; optional messages require the applicable opt-in policy. In-product state remains authoritative when email delivery is delayed or fails.

Scope

• Purpose classes, recipients, preference rules, content anatomy, localization, links, threading, delivery status, unsubscribe, and support behavior.
• User-facing email triggered by product events.
• Coordination between product state and communication history.

Outside this block

• Provider retry mechanics, template rendering internals, or legal classification for every jurisdiction.
• Using email as the sole durable record of an action.

Contract

• Each notification declares purpose, audience, urgency, preference category, data classification, and source event.
• Recipient resolution occurs at send time from an authorized account channel; arbitrary event payload addresses are not trusted.
• Subject and preheader identify the service and action without exposing unnecessary sensitive data.
• The message explains what happened, who or what initiated it when appropriate, when it occurred, and the safe next action.
• Links use an approved origin, minimize bearer credentials, and route through a confirmation page for consequential actions.
• The product exposes delivery state separately from the underlying business action and does not promise inbox arrival.

Implementation guidance

• Use multipart text and HTML with semantic headings, meaningful link text, sufficient contrast, and useful alt text.
• Localize from recipient preference captured at event time or send time according to documented product semantics.
• Set stable message and correlation identifiers for threading and support.
• Provide a preference route for optional categories and a security-report route for unexpected messages.

Failure handling and safeguards

• If recipient resolution is ambiguous or channel status is unverified, suppress sensitive delivery and surface an internal failure.
• If delivery fails, preserve the product action and offer an in-product recovery path where needed.
• If account ownership changes, do not send queued content to a newly assigned address without reauthorization.

Verification and operations

• Measure requested, suppressed by preference, rendered, accepted, bounced, complained, delayed, and action-completed outcomes by purpose.
• Audit content for sensitive fields and expired links using fixtures.
• Review high-volume or high-complaint messages with product and privacy owners.

The executable-looking examples in this package are fixtures and acceptance contracts. Run python tools/validate.py from the collection root to check package structure and metadata; then implement and execute the scenarios in the target repository.

Adoption assumptions

• Names and numeric values in example.yaml are an adoption profile, not universal defaults.
• The adopting team must map actors, data classes, error vocabulary, and ownership to its system.

References

• No external normative source is required; this package defines a project decision.