Email (SMTP)

Stoa sends transactional email through your own SMTP server. Configure it once and the platform will handle welcome emails and approval notifications for you. This page covers what to set, what gets sent, and how to debug delivery issues.

What Stoa sends

When SMTP is configured, the platform sends email for the following events:

• Welcome emails on user creation. New accounts created by an admin receive a welcome email with their sign-in URL and a short orientation.
• Active Directory auto-provisioning notifications. When a directory user signs in for the first time and Stoa creates their account, they get the same welcome email so they know it happened.
• Approval requests. Workflows that require human approval (for example, before publishing a high-stakes draft) email the approver with a link straight to the request.

If SMTP is not configured, none of these emails are sent and Stoa continues to function normally. The platform never blocks an action because email is unavailable.

What you need

Before you start, gather:

• The SMTP server hostname and port (commonly 587 for STARTTLS, 465 for implicit TLS, 25 if you have an internal relay).
• Whether the server requires TLS (almost always yes; we strongly recommend it).
• The username and password for the account Stoa will use to send mail.
• The From address Stoa should put on outgoing messages. This must be an address your SMTP server is authorized to send from. If you use sender policies (SPF, DKIM, DMARC), make sure the chosen address passes them.
• An optional From display name (for example, "Stoa Notifications").

Configuring it

In the admin UI, open the user menu, choose System, then Integrations, and select SMTP Server. Enter the values from the previous section and save.

Once saved, the configuration is held centrally and used by every part of the platform that sends mail. You don't need to restart anything.

TIP

The SMTP password is stored encrypted at rest. If you come back to this screen later, the password field shows a placeholder rather than the real value: you don't need to retype it to send a test or change another field.

Sending a test email

Right beside the SMTP form, the admin UI exposes a Send test email action. Enter a destination address (your own is the right choice) and click send. Stoa will:

1. Connect to your SMTP server using the configuration you just saved.
2. Authenticate.
3. Send a short test message to the address you provided.
4. Report success, or show you the exact error from your SMTP server.

If the test arrives in your inbox, you're done. If not, the error message tells you what to fix next.

When email fails

The most common reasons a test fails:

• Firewall blocks the SMTP port. Confirm the Stoa host can reach your SMTP server on the configured port. Internal relays often live on 25; external services typically require 587 or 465.
• Wrong credentials. Re-enter the username and password. Some providers require an app password rather than the account password.
• From address not authorized. If your SMTP server enforces a sender policy, the From address has to belong to (or be authorized for) the account you're logging in with. Switch to an address you're allowed to send from.
• TLS mismatch. If your server requires STARTTLS on 587 but the configuration is set to plain, the handshake will fail. Toggle TLS and try again.
• DNS or hostname typos. Stoa surfaces the underlying connection error verbatim, so a "no such host" error usually points at a typo.

Email and identity

If you're using Active Directory or LDAP for sign-in, the welcome email is the first thing a brand-new user sees from Stoa. Make sure your branding (product name, logo) is set correctly before you turn AD provisioning on, so the email matches what users see when they sign in. See Branding.

What about inbound email?

Stoa does not currently process inbound email. Mail sent to the From address (replies, bounces, out-of-office) goes to whatever inbox owns that address on your mail server. We recommend using a dedicated alias like stoa-noreply@yourdomain so replies don't sit in a personal mailbox.

Next

• Active Directory so the first email a user receives is their auto-provisioning welcome.
• Branding so outbound mail matches the rest of your deployment.