A relay credential belongs to a specific outbound connection
Postfix can authenticate as an SMTP client to an upstream relay. That client-side configuration is different from the SMTP server policy that decides which inbound clients may relay mail. Confusing the smtp and smtpd settings can lead an investigation into the wrong part of the service.
The credential lookup must correspond to the actual relay destination, including the relevant bracket and port form. A correct password stored under the wrong lookup key can still produce authentication failure. This guide diagnoses an outbound relay path and keeps credentials out of logs and public support messages.
Setup: record the next hop and secure the diagnostic view
Identify the queued message's next hop, provider submission requirements and exact rejection stage. Distinguish connection failure, TLS negotiation, authentication rejection and recipient delivery failure. Collect the queue identifier and timestamps with approved redaction of addresses and message content.
An illustrative destination relationship is:
relayhost = [smtp.example.test]:587
credential lookup key = [smtp.example.test]:587
These are example values, not a complete Postfix configuration. Use the database map type supported by the installed build and distribution. Review the configured map path and its permissions privately; do not dump its contents merely to show that a password exists.
Illustrative incident: a port change leaves the old lookup key behind
In this illustrative scenario, a team changes the upstream relay endpoint to an explicit submission port. The credential map still uses the earlier destination form. The relay is reachable, but the expected credentials are not selected for the connection.
The operator compares the actual next-hop form with the configured credential key using a secure administrative procedure. The fix is reviewed together with provider requirements and map generation for the installed backend. Repeated password resets would not address a mismatched lookup path.
Troubleshooting: identify the rejected boundary
| Observation | Evidence | Investigation |
|---|---|---|
| Connection never reaches SMTP | DNS, port and route evidence | Reachability before credentials |
| TLS fails before authentication | Certificate and session error | Required encrypted transport and trust |
| Authentication fails despite an expected secret | Destination form, map type and key | Was the intended credential selected? |
| Authentication succeeds but delivery is deferred | Relay response and recipient policy | Sender or recipient handling after login |
Bracketed relayhost syntax affects MX lookup behavior. Use the provider's intended next-hop design rather than changing the hostname form experimentally without understanding the result. Also check that the service loaded the intended generated map after a controlled configuration change.
Correct the lookup while preserving transport and relay policy
Update only the evidenced destination, credential selection or approved provider setting. Protect both the source credential file and generated map according to the deployment's access policy. Use the supported map-build and configuration-check procedure, then perform a controlled activation.
Do not disable TLS requirements to make a plaintext credential exchange work. Do not broaden inbound relay authorization as a remedy for outbound authentication. Those controls protect different boundaries. If a credential itself is invalid, rotate it through the provider-approved secure process rather than pasting it into an incident ticket.
Verification, monitoring and SOP
Send an approved diagnostic message to a controlled mailbox and trace it by queue identifier through the relay acceptance. Confirm eventual receipt through the mailbox's normal evidence. An upstream acceptance response alone does not prove inbox placement or eliminate downstream filtering.
Monitor repeated authentication rejections, queue age and deferral reasons without logging secrets. An internal SLO can describe timely handoff of eligible messages to the approved relay; inbox-delivery commitments require separate terms and dependencies. The SOP should record destination syntax, map ownership, TLS policy, secure rotation, activation, rollback and the evidence required before retrying queued mail.
See Clouvenix email deliverability for a reviewed implementation and operational handover.
Technical reference
Postfix client and server SASL configuration. Reviewed 19 October 2026; use documentation for the installed product and release.