Configure outbound email and verify delivery

Access needed: Site email-settings permission; server access for global relay settings.

Get the provider's relay hostname, port, authentication method, TLS requirements, and permitted sender address before changing settings.

1. Decide whether the relay is global or specific to this site. Inspect existing overrides first.
2. Configure the provider's host, port, credentials, and TLS mode at that scope. Global keys include smtp_relay, smtp_host, smtp_port, smtp_username, smtp_password, and smtp_ssl; site relay settings use different smtp_relay_* keys.
3. Apply the documented reload or restart and check the effective settings without exposing credentials.
4. Arrange the provider's required domain verification and DNS records with the domain owner.
5. Send one representative message to an address you control, such as a password-recovery message or form receipt.
6. Check Zotonic's mail status, the provider's delivery status, and the recipient inbox. Confirm the sender and reply address are correct.

Server acceptance and inbox delivery are different outcomes. Follow the mail-diagnosis task if delivery fails. Never disable certificate checks to work around a TLS mismatch; verify the provider's hostname and connection mode.

Direct test mail to a controlled recipient

Access needed: Site email-settings permission or server configuration access.

Set up test-mail routing before running copied production data or testing scheduled mail.

1. Choose a mailbox that the testing team controls.
2. Configure the appropriate email_override: the global setting affects the installation; the site's site.email_override affects that site. Check any configured exceptions.
3. Apply the change using the owning configuration mechanism.
4. Send a test whose requested recipient is another address you control. Verify the actual delivery destination and inspect the mail status.
5. Test the real workflow, then record that the override is intentional for this environment.
6. Before production cutover, check the effective override and exceptions explicitly. A leftover catch-all can divert real users' messages.

This setting governs Zotonic's email handling. Custom integrations that send through another provider API need their own test configuration. Do not assume a database copy also copied safe delivery settings.

Diagnose missing or failed email

Access needed: Mail-log access; provider access may be needed.

1. Identify one message by time, intended recipient, and originating workflow.
2. Check whether Zotonic created and queued it. If not, verify the workflow settings and logs.
3. Check whether a catch-all override or exception changed the destination.
4. Read the sending status and failure reason. Check relay authentication, TLS, connectivity, sender acceptance, and retry state as applicable.
5. If accepted by the provider, inspect its delivery or bounce record, then check the recipient's spam handling.
6. After correcting the cause, send one controlled test and confirm receipt before retrying a larger batch.

Do not resend an entire newsletter because one inbox is empty. Pending retries and provider acceptance can otherwise create duplicates. Record enough identifiers for diagnosis without copying private message content into a public ticket.