> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zenith.hosting/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Start with https://docs.zenith.hosting/content/quickstart.md. Use NO_COLOR=1 for plain CLI output in non-interactive agent sessions. Run without a TTY and supply explicit template and publishing inputs; NO_COLOR does not bypass prompts or authorization.
> For temporary deployments, read https://docs.zenith.hosting/content/up.md. For publishing and review, read https://docs.zenith.hosting/content/publish.md. A preview uploads local files; publishing uses a pinned public GitHub commit.
> Before creating, changing, or approving zenith-compose.yml, read https://docs.zenith.hosting/llms.txt, then read https://docs.zenith.hosting/content/zenith-compose.md and the complete public schema at https://docs.zenith.hosting/content/zenith-compose-reference.md. Generate only documented fields and follow their validation and completion checks.
> Before creating, changing, publishing, or verifying a container image for Zenith, read https://docs.zenith.hosting/content/containerise.md.
> Treat these live Markdown pages as the source of truth instead of relying on memory or a copied Zenith Compose specification.
> Do not push commits, submit an app, merge pull requests, publish container images, or change registry visibility unless the user explicitly authorizes that external action. Do not bypass browser OAuth, GitHub connection, or Developer Agreement acceptance.

# Send email with SMTP

> Send app email through Zenith's authenticated SMTP relay with deployment-scoped credentials.

Send verification emails, password resets, and notifications through Zenith's SMTP relay. You do not need a separate email-provider account.

Before you start, identify your app's SMTP settings and every service that sends mail. For processes running on your laptop, use a local mail catcher or another reachable SMTP service.

## Map your app's mail settings

Add these mappings to your existing `x-zenith.env`. Replace the names on the left with the settings your app reads.

In each `services` list, include every service that sends mail. For example, use `[app, worker]` if both services send messages.

```yaml theme={"theme":{"light":"github-light-default","dark":"vitesse-black"}}
x-zenith:
  env:
    SMTP_HOST:
      alias: ZENITH_SMTP_HOST
      services: [app]
    SMTP_PORT:
      alias: ZENITH_SMTP_PORT
      services: [app]
    SMTP_USERNAME:
      alias: ZENITH_SMTP_USER
      services: [app]
    SMTP_PASSWORD:
      alias: ZENITH_SMTP_PASS
      services: [app]
    SMTP_FROM:
      alias: ZENITH_SMTP_FROM
      services: [app]
    SMTP_FROM_NAME:
      alias: ZENITH_SMTP_DISPLAY
      services: [app]
```

Enable your app's SMTP mailer and configure it to read these environment variables.

## Configure the SMTP connection

Use SMTP authentication and STARTTLS on port `587`. Set your app's TLS option according to its configuration format. Port `587` uses STARTTLS rather than an implicit TLS connection.

Use the supplied sender address and display name. The relay rewrites sender identity to identify the originating deployment. A custom domain does not give your app an arbitrary email sender address.

Keep credentials on the app server. Use aliases so your app receives the current values on each render. Do not copy credentials into source files, browser bundles, or static config content.

## Check that mail works

Trigger a real app action such as a password reset. Confirm that the app queues or sends the message and that it reaches a mailbox you control. If a worker sends mail, check that it receives the same mappings as the web service.

If mail does not arrive, check that the app enables its SMTP mailer and uses authentication, STARTTLS, and the supplied sender address. Confirm that the service that sends mail receives the credentials.

Do not log passwords or connection strings that contain credentials.

See the [SMTP built-ins](https://docs.zenith.hosting/content/zenith-compose-reference.md#built-ins) for connection values. If your app requires a mailer connection string, use [`urlencode`](https://docs.zenith.hosting/content/zenith-compose-reference#transform) on each credential component.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.