Correct developer and feature pages against the Postal 3.3.7 source - #92
Open
benrfairless wants to merge 6 commits into
Open
benrfairless wants to merge 6 commits into
benrfairless wants to merge 6 commits into
Conversation
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)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Reviews the Developer and Features sections against the Postal source at tag
3.3.7and corrects the places where the documentation had drifted from the code, filling in behaviour that was undocumented along the way.Corrections
{event, timestamp, uuid, payload}; the docs showed the innerpayloadas the top level. Adds the signature headers (X-Postal-Signature-256, legacyX-Postal-Signature,X-Postal-Signature-KID) and the/.well-known/jwks.jsonendpoint for verifying them, the 5 s timeout, the retry schedule (6 attempts: 2/3/6/10/15 min), theSendLimitApproaching/SendLimitExceededevents, and corrects history retention from 7 to 10 days.5xx, timeouts and connection errors are soft failures that are retried, other3xx/4xxare hard failures, and429hard-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_fromon the raw payload), form-data attachment flattening, the back-off formula, and the 3.3.7 SSRF block list withallowed_request_destinations./api/v1endpoints. Documents the thirdparameter-errorstatus, every error code, all parameters (incl. theheaderskey, comma-separated recipients, the 50-per-list limit,rcpt_tomust be an array forsend/raw), and the full_expansionsresponse shape.discovery: false.>spam threshold,>=failure threshold), documents theX-Postal-Spam*/X-Postal-Threatheaders, 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.org/serverfor CRAM-MD5), From-then-Sender validation order, SMTP-IP longest-prefix matching, credential hold, a table of SMTP responses, CRLF-only end-of-DATA.OK; paths served; 307 redirect; excluded domains are exact-match./endpoint.logging.*options, SMTP connection logging, per-server Log SMTP data.Also fixes a typo ("owned by that domain" → server) and adds
descriptionfrontmatter to pages that had it empty.Stacked on #90 and #91 (cross-links to the new pages).
pnpm generatepasses on this branch (177 routes prerendered, no 404s from the link crawler).