Skip to content

docs: DNS, email hardening, configuration, and API examples - #95

Open
c41ms0n wants to merge 1 commit into
postalserver:mainfrom
c41ms0n:docs-v2
Open

c41ms0n wants to merge 1 commit into
postalserver:mainfrom
c41ms0n:docs-v2

Conversation

@c41ms0n

@c41ms0n c41ms0n commented Sep 18, 2026

Copy link
Copy Markdown

Add production email delivery security and hardening guidance

Rebased #94

Summary

This PR adds a focused production hardening guide for Postal mail deployments.

The page complements the existing Postal configuration and Sending Domains documentation without duplicating the configuration reference or the source-alignment corrections already being developed in the upstream documentation series.

What is covered

  • Postal hostname, smtp_hostname, helo_hostname, HELO/EHLO identity, PTR/rDNS and FCrDNS
  • IPv4 preference on glibc-based Linux systems when IPv6 is not yet production-ready
  • SPF structure, one-record rule, ~all migration mode and -all production mode
  • Postal DKIM selector construction and the distinction between dkim_identifier and the complete selector
  • Current Postal DKIM characteristics and the domain-specific-key requirement for production
  • From, MAIL FROM and HELO/EHLO identity separation
  • DMARC enforcement, alignment and migration stages
  • Postal custom Return Path and its domain-derived DNS naming
  • SMTP TLS and its relationship to transport-security mechanisms
  • MTA-STS discovery, HTTPS policy, modes and production rollout
  • TLS-RPT policy syntax, URI formats, duplicate-record handling, report formats, result types, reporting periods and retry behaviour
  • DANE/TLSA and DNSSEC operational requirements
  • BIMI as an optional sender-branding layer
  • Hardening for unused domains and subdomains
  • A consolidated production checklist and troubleshooting order

Design goals

The guidance deliberately distinguishes:

  1. Postal application configuration;
  2. Postal infrastructure DNS;
  3. per-sending-domain DNS;
  4. recipient-side transport security policy; and
  5. host-level networking behaviour.

This prevents configuration values such as dkim_identifier, domain_verify_prefix, and custom_return_path_prefix from being mistaken for DNS hostnames or interchangeable prefixes.

The examples use documentation-only IP ranges and example.com names so they cannot be copied as real production addresses by accident.

Relationship to the existing documentation series

Pull Request #90 is already merged and provides the Sending Domains feature page. Pull Requests #91#93 cover the configuration reference and source-alignment corrections for other documentation areas. This PR intentionally avoids reimplementing those pending changes and instead adds the missing security/hardening layer as a standalone feature page.

Validation

  • Markdown front matter follows the existing feature-page format.
  • Existing Postal ::callout syntax is used.
  • Shell/YAML/DNS examples use documentation-only values.
  • No existing screenshots or media assets are removed or renamed.
  • No external source URLs are embedded in the documentation text.

@c41ms0n c41ms0n changed the title docs: add production email delivery hardening guide docs: DNS, email hardening, configuration, and API examples Sep 18, 2026
@c41ms0n
c41ms0n force-pushed the docs-v2 branch 3 times, most recently from b4bd6f5 to 272248e Compare September 18, 2026 20:38
- Separate Postal infrastructure from sending-domain configuration, document
production and migration authentication policies, add email hardening guidance,
expand the postal.yml reference, improve cURL examples, and fix navigation order.
- Document SPF, DKIM, DMARC, SMTP transport security, MTA-STS, TLS-RPT,
DANE, BIMI, FCrDNS, IPv4 preference, and unused-domain hardening.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant