Skip to content

Correct developer and feature pages against the Postal 3.3.7 source - #92

Open
benrfairless wants to merge 6 commits into
postalserver:mainfrom
benrfairless:docs/corrections-developer-features
Open

benrfairless wants to merge 6 commits into
postalserver:mainfrom
benrfairless:docs/corrections-developer-features

Conversation

@benrfairless

Copy link
Copy Markdown
Contributor

Reviews the Developer and Features sections against the Postal source at tag 3.3.7 and corrects the places where the documentation had drifted from the code, filling in behaviour that was undocumented along the way.

Corrections

Page Key changes
Webhooks Every webhook body is an envelope {event, timestamp, uuid, payload}; the docs showed the inner payload as the top level. Adds the signature headers (X-Postal-Signature-256, legacy X-Postal-Signature, X-Postal-Signature-KID) and the /.well-known/jwks.json endpoint for verifying them, the 5 s timeout, the retry schedule (6 attempts: 2/3/6/10/15 min), the SendLimitApproaching/SendLimitExceeded events, and corrects history retention from 7 to 10 days.
Receiving e-mail by HTTP The status-code handling was inverted: 5xx, timeouts and connection errors are soft failures that are retried, other 3xx/4xx are hard failures, and 429 hard-fails without a bounce. Timeout is 5–60 s per endpoint rather than a fixed 5 s. Adds missing payload keys (reply_to, replies_from_plain_body, rcpt_to/mail_from on the raw payload), form-data attachment flattening, the back-off formula, and the 3.3.7 SSRF block list with allowed_request_destinations.
Using the API Expanded into a reference for all four /api/v1 endpoints. Documents the third parameter-error status, every error code, all parameters (incl. the headers key, comma-separated recipients, the 50-per-list limit, rcpt_to must be an array for send/raw), and the full _expansions response shape.
OpenID Connect User matching order was reversed: Postal matches on OIDC UID + issuer first, then falls back to e-mail address (only for users not yet linked). Notes that linking clears the local password, adds the manual-endpoint config for discovery: false.
Spam & Virus Checking Adds rspamd (which takes precedence over spamd when both are enabled) and ClamAV configuration. Corrects threshold semantics (> spam threshold, >= failure threshold), documents the X-Postal-Spam*/X-Postal-Threat headers, and that a virus detection only sets a flag – it never holds or fails a message. Outbound scanning only happens when an outbound threshold is set.
SMTP Authentication Username handling per mechanism (ignored for PLAIN/LOGIN, org/server for CRAM-MD5), From-then-Sender validation order, SMTP-IP longest-prefix matching, credential hold, a table of SMTP responses, CRLF-only end-of-DATA.
SMTP TLS STARTTLS only (no implicit TLS/465), certificate file may contain the chain, container paths.
Click & Open Tracking Rewriting only happens once the tracking domain's CNAME check is OK; paths served; 307 redirect; excluded domains are exact-match.
Health & Metrics Full list of exported Prometheus metrics with labels; / endpoint.
IP Pools IP address fields (hostname is used for HELO; priority weighting), rule matching (exact address/domain, server rules before organization rules), meaning of the default pool, and that messages allocated to an IP no running worker holds are never processed.
Logging All logging.* options, SMTP connection logging, per-server Log SMTP data.

Also fixes a typo ("owned by that domain" → server) and adds description frontmatter to pages that had it empty.

Stacked on #90 and #91 (cross-links to the new pages). pnpm generate passes on this branch (177 routes prerendered, no 404s from the link crawler).

New feature pages written from the 3.3.7 source:
- Routing incoming e-mail: MX vs forwarding address, route name rules,
  the five route modes and their SMTP-time behaviour, additional
  endpoints, processing order, HTTP/SMTP/address endpoint options
  (including the STARTTLS/STARTLS mismatch), retries and bounces
- Mail server settings: Live/Development, retention behaviour and
  defaults, send limits (rolling hour, 90% warning, hourly notices),
  every reason a message can be held and whether release bypasses it,
  suppression list rules, advanced/admin-only settings, suspension,
  deletion
- Sending domains: org vs server domains, DNS and e-mail verification,
  the four DNS checks with exact expected records and statuses, DKIM
  signing and fallback, custom return path for DMARC alignment,
  use_for_any
Documents the install-repo helper script: run/setup/tool commands,
flags, override files and hooks.
Generated from doc/config/yaml.yml at the 3.3.7 tag (111 options across
17 sections) with environment variable names derived using the GROUP_KEY
convention, plus cross-references to the relevant feature pages.
- Webhooks: document the {event,timestamp,uuid,payload} envelope, request
  signing headers and JWKS verification, retry schedule, 10-day history,
  SendLimit* events
- HTTP payloads: correct status-code handling (5xx retries, 429/4xx hard
  fail), per-endpoint timeout, missing payload keys, SSRF blocked ranges
  and allowed_request_destinations
- API: expand into a full reference for all four legacy endpoints,
  including parameter-error status, error codes and response shapes
- OIDC: correct user matching order (UID first, then e-mail), note that
  linking removes the local password, document manual endpoints
- Spam & virus: add rspamd and ClamAV sections, correct threshold
  semantics, document X-Postal-* headers and outbound inspection
- SMTP auth/TLS: username handling per mechanism, SMTP-IP matching,
  response table, STARTTLS-only, certificate chains
- Click tracking, health metrics, IP pools, logging: fill in behaviour
  from source (DNS OK requirement, metric list, priority weighting,
  rule matching, log options)
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