docs: clarify DNS, email hardening, configuration, and API examples

[c41ms0n]

Clarify Postal DNS, sending domains, configuration, DMARC, and API usage

Summary

This PR reorganizes and clarifies the current Postal documentation without changing Postal application behavior. The goal is to make a new production installation easier to configure correctly and to remove ambiguity between the Postal installation hostname, Postal infrastructure DNS, sending domains, authentication policy, configuration parameters, and the HTTP API.

The documentation keeps postal.example.com as the canonical hostname, matching the default Postal configuration. It explicitly notes that a deployment may choose another stable hostname such as mail.example.com, but that hostname choice is independent from dkim_identifier, domain_verify_prefix, custom_return_path_prefix, and sending-domain-derived DNS records.

Changes

Installation and configuration reference

• Clarify the role of the Postal installation hostname and keep postal.example.com as the canonical example.
• Explain that mail.example.com is an alternative hostname, not a replacement for unrelated DNS prefixes in postal.yml.
• Add a section-by-section reference for every top-level section and parameter currently present in doc/config/yaml.yml, including defaults, expected value types, security considerations, and operational notes. Explicitly state that current Postal 3.x configuration is YAML-based and that this reference must track the source configuration file.
• Point readers to the matching environment-variable reference.
• Preserve the existing installation screenshot/media reference; no existing media files are removed or renamed.

DNS configuration

• Define the page as Postal infrastructure DNS and link to the separate sending-domain guide.
• Document both single-MX and multi-MX deployments. A single Postal MX hostname is valid; mx1/mx2 are examples, not requirements.
• Explain that domain_verify_prefix is part of the verification TXT value, not a DNS hostname.
• Avoid hard-coding a DKIM selector that depends on dns.dkim_identifier; use postal default-dkim-record and publish its exact output.
• Document hardened SPF with -all and retain ~all as a migration/soft-fail option.
• Explain when the sending domain's MX should remain with an existing mail provider.
• Keep route and tracking infrastructure separate from per-sending-domain DNS.

Sending domain configuration

• Add a dedicated page describing Organization → Mail Server → Domain ownership.
• Describe the exact records used for domain verification, SPF, DKIM, Return Path, DMARC, and optional inbound MX.
• Add DMARC as an explicit production DNS layer even though it is not a postal.yml setting.
• Add optional inbound/domain hardening guidance for MTA-STS (including DNS discovery, policy modes, caching and staging), TLS-RPT (record syntax, transports, report schema, failure categories, compression and retries), DANE/TLSA, BIMI, and unused domains, while explicitly distinguishing these domain-level controls from Postal application configuration.
• Document migration policies (p=none, p=quarantine) and hardened policy (p=reject, sp=reject, pct=100).
• Explain strict/relaxed DMARC alignment in the context of Postal's derived Return Path (aspf=r) and sending-domain DKIM (adkim=s).
• Explicitly warn against moving records to a parent DNS level merely because the shorter name looks cleaner.
• Add DKIM key-rotation and strict-selector guidance, an SMTP HELO/EHLO identity note, and a note about DMARC external-reporting authorization when a report address is outside the protected domain.

API documentation

• Clarify the API overview status semantics, including success, parameter-error, and error, and keep action-specific validation errors in the individual action documentation.
• Keep X-Server-API-Key authentication.
• Use readable cURL examples with single-quoted static URLs and JSON where practical.
• Use a variable-expanded here-document only where required for the generated base64 raw message.
• Include every documented top-level parameter for the structured send action and label required, optional, and conditional parameters.
• Document the attachment object fields used by Postal and include a complete attachment example.
• Document the raw send parameters and provide a readable RFC 2822 example.
• Correct GET /api/v1/messages/message to use query parameters rather than a JSON request body.
• Use RFC 2822 consistently in the documentation instead of the typo currently visible in the generated reference title.
• Avoid inventing an attachment-item schema where the public action reference does not define one.

Navigation

The Getting Started section currently contains a duplicate 2.3 position. With the new sending-domain page, the intended order becomes:

2.1 Installation
2.2 Configuration
2.3 DNS configuration
2.4 Sending domain configuration
2.5 Upgrading to v3
2.6 Upgrading to v2

The DNS page remains 2.3; only the duplicated upgrade positions are shifted.

Compatibility / scope

• Documentation-only change; no Postal application code is modified.
• No existing screenshots or image assets are removed or renamed.
• No new DNS or API behavior is introduced.
• The guide distinguishes global Postal infrastructure names from records that Postal derives from an individual sending domain.
• DMARC is documented as DNS policy, not as a Postal application configuration key.
• The configuration reference is explanatory documentation around the current doc/config/yaml.yml; the source configuration file remains authoritative for defaults and future changes.

[willpower232]

I'll have a look at this once the other PRs are sorted, thanks for your attention!

[c41ms0n]

#95