{"result":{"depiction_url":null,"edges":{"hasreference":{"objects":[{"created":"2026-10-07T11:13:47Z","object_id":{"id":3067,"is_a":["text","documentation","adminguide"],"name":"admin_outbound_email","title":{"_type":"trans","tr":{"en":"Configure outbound email and verify delivery"}},"uri":"https:\/\/zotonic.com\/id\/3067"},"seq":1},{"created":"2026-10-07T11:13:47Z","object_id":{"id":3068,"is_a":["text","documentation","adminguide"],"name":"admin_test_email","title":{"_type":"trans","tr":{"en":"Direct test mail to a controlled recipient"}},"uri":"https:\/\/zotonic.com\/id\/3068"},"seq":2},{"created":"2026-10-07T11:13:47Z","object_id":{"id":3081,"is_a":["text","documentation","adminguide"],"name":"admin_mail_failures","title":{"_type":"trans","tr":{"en":"Diagnose missing or failed email"}},"uri":"https:\/\/zotonic.com\/id\/3081"},"seq":3}],"predicate":{"id":2774,"is_a":["meta","predicate"],"name":"hasreference","title":{"_type":"trans","tr":{"en":"Documentation reference"}},"uri":"https:\/\/zotonic.com\/id\/hasreference"}},"references":{"objects":[{"created":"2020-05-30T05:48:18Z","object_id":{"id":1352,"is_a":["text","documentation","developerguide"],"name":"doc_developerguide_templates","title":{"_type":"trans","tr":{"en":"Create a page layout"}},"uri":"https:\/\/zotonic.com\/id\/1352"},"seq":1000000},{"created":"2020-05-30T05:48:18Z","object_id":{"id":1341,"is_a":["text","documentation","reference","template_tag"],"name":"doc_template_tag_tag_image","title":"image","uri":"https:\/\/zotonic.com\/id\/1341"},"seq":1000000},{"created":"2020-05-30T05:48:18Z","object_id":{"id":1280,"is_a":["text","documentation","developerguide"],"name":"doc_developerguide_media","title":{"_type":"trans","tr":{"en":"Render and manage media"}},"uri":"https:\/\/zotonic.com\/id\/1280"},"seq":1000000},{"created":"2020-05-30T05:48:18Z","object_id":{"id":1465,"is_a":["text","documentation","reference","module"],"name":"doc_module_mod_mailinglist","title":"mod_mailinglist","uri":"https:\/\/zotonic.com\/id\/1465"},"seq":1000000},{"created":"2020-05-30T05:48:18Z","object_id":{"id":1279,"is_a":["text","documentation"],"name":"doc_glossary","title":"Glossary","uri":"https:\/\/zotonic.com\/id\/1279"},"seq":1000000},{"created":"2020-05-30T05:48:18Z","object_id":{"id":1858,"is_a":["text","documentation","reference","module"],"name":"doc_module_mod_logging","title":"mod_logging","uri":"https:\/\/zotonic.com\/id\/1858"},"seq":1000000}],"predicate":{"id":332,"is_a":["meta","predicate"],"name":"references","title":{"_type":"trans","tr":{"en":"References"}},"uri":"https:\/\/zotonic.com\/id\/references"}},"subject":{"objects":[{"created":"2026-10-07T11:13:47Z","object_id":{"id":2554,"is_a":["categorization","keyword","keyword_information_type"],"name":"zotonic_topic_how_to_guide","title":"How-to guide","uri":"https:\/\/zotonic.com\/id\/2554"},"seq":1},{"created":"2026-10-07T11:13:47Z","object_id":{"id":2566,"is_a":["categorization","keyword","keyword_audience"],"name":"zotonic_topic_operator","title":"Operator","uri":"https:\/\/zotonic.com\/id\/2566"},"seq":2},{"created":"2026-10-07T11:13:47Z","object_id":{"id":2594,"is_a":["categorization","keyword","keyword_domain"],"name":"zotonic_topic_email","title":"Email","uri":"https:\/\/zotonic.com\/id\/2594"},"seq":3},{"created":"2026-10-07T11:13:47Z","object_id":{"id":2595,"is_a":["categorization","keyword","keyword_domain"],"name":"zotonic_topic_email_delivery","title":"Email delivery","uri":"https:\/\/zotonic.com\/id\/2595"},"seq":4},{"created":"2026-10-07T11:13:47Z","object_id":{"id":2603,"is_a":["categorization","keyword","keyword_domain"],"name":"zotonic_topic_configuration","title":"Configuration","uri":"https:\/\/zotonic.com\/id\/2603"},"seq":5}],"predicate":{"id":308,"is_a":["meta","predicate"],"name":"subject","title":{"_type":"trans","tr":{"en":"Keyword"}},"uri":"http:\/\/purl.org\/dc\/elements\/1.1\/subject"}}},"id":1552,"is_a":["text","documentation","developerguide"],"links":[{"rel":"self","target":"https:\/\/zotonic.com\/.zotonic\/websub\/topic\/1552"},{"rel":"hub","target":"https:\/\/zotonic.com\/.zotonic\/websub"}],"medium":null,"medium_url":null,"name":"doc_developerguide_email","page_url":{"en":"https:\/\/zotonic.com\/docs\/1552\/configure-outbound-email-and-verify-delivery","x-default":"https:\/\/zotonic.com\/docs\/1552\/configure-outbound-email-and-verify-delivery"},"preview_url":null,"resource":{"version":39,"pivot_location_lat":null,"title":{"_type":"trans","tr":{"en":"Configure outbound email and verify delivery"}},"is_authoritative":true,"body":{"_type":"trans","tr":{"en":"

Access needed:<\/strong> Site email-settings permission; server access for global relay settings.<\/p>\n

Get the provider's relay hostname, port, authentication method, TLS requirements, and permitted sender address before changing settings.<\/p>\n

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

    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.<\/p>\n

    Direct test mail to a controlled recipient<\/h2>\n

    Access needed:<\/strong> Site email-settings permission or server configuration access.<\/p>\n

    Set up test-mail routing before running copied production data or testing scheduled mail.<\/p>\n

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

      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.<\/p>\n

      Diagnose missing or failed email<\/h2>\n

      Access needed:<\/strong> Mail-log access; provider access may be needed.<\/p>\n

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

        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.<\/p>"}},"is_mailing_opt_out":false,"slug":"configure-outbound-email-and-verify-delivery","is_protected":false,"visible_for":0,"tz":"UTC","language":["en"],"is_featured":false,"content_group_id":{"id":339,"is_a":["meta","content_group"],"name":"default_content_group","title":{"_type":"trans","tr":{"en":"Default Content Group"}},"uri":"https:\/\/zotonic.com\/id\/default_content_group"},"category_id":{"id":317,"is_a":["meta","category"],"name":"developerguide","title":"Developer guide","uri":"https:\/\/zotonic.com\/id\/developerguide"},"publication_start":"2022-02-15T10:01:00Z","is_website_redirect":false,"github_url":"https:\/\/github.com\/zotonic\/zotonic\/tree\/master\/doc\/developer-guide\/email.rst","pivot_location_lng":null,"name":"doc_developerguide_email","is_unfindable":false,"is_published":true,"doc_editorial_edges":{"hasreference":[3067,3068,3081],"subject":[2554,2566,2594,2595,2603]},"summary":{"_type":"trans","tr":{"en":"Set a relay at the correct scope and test a real site message."}},"pivot_geocode":null,"custom_slug":false,"created":"2020-05-30T05:47:25Z","uri":null,"date_is_all_day":false,"is_dependent":false,"is_page_path_multiple":false,"publication_end":"9999-08-17T12:00:00Z","modifier_id":{"id":1,"is_a":["person"],"name":"administrator","title":"Site Administrator","uri":"https:\/\/zotonic.com\/id\/1"},"privacy":0,"doc_editorial_bundle":true,"creator_id":{"id":336,"is_a":["person","robot"],"name":"gitbot","title":"Git","uri":"https:\/\/zotonic.com\/id\/336"},"seo_noindex":false,"modified":"2026-10-07T11:13:59Z","title_slug":{"_type":"trans","tr":{"en":"configure-outbound-email-and-verify-delivery"}}},"uri":"https:\/\/zotonic.com\/id\/1552","uri_template":"https:\/\/zotonic.com\/id\/:id","websub":{"hub":"https:\/\/zotonic.com\/.zotonic\/websub","topic":"https:\/\/zotonic.com\/.zotonic\/websub\/topic\/1552"}},"status":"ok"}