Set up SMTP and email
Raytha sends email for welcome messages, password resets, one-time sign-in codes and anything your own Functions send. This page shows how to connect it to an SMTP server, how the sender is chosen, and how to use the email log to confirm that mail is leaving.
What you need
- The Manage System Settings permission.
- An SMTP account: host name, port, and usually a user name and password, from your email provider.
Two places to configure SMTP
Raytha can read its SMTP account from the server's environment variables, or from the admin. The environment variables are SMTP_HOST, SMTP_PORT, SMTP_USERNAME, SMTP_PASSWORD, SMTP_FROM_ADDRESS and SMTP_FROM_NAME. Whoever deploys Raytha sets them; see Sending emails.
If the server has no SMTP_HOST, the admin tells you so: the Configuration screen shows "Server SMTP environment variables are missing. Override is required." and the Override system SMTP box is ticked and locked. If the server does have SMTP set, you can still replace it from the admin by ticking that box.
Connect Raytha to an SMTP server
- Open Settings > Configuration.
- Set Default from address and Default from name. Both are required.
- Tick Override system SMTP if you are not using the server's environment variables.
- Fill in Host and Port. Both are required when you override. Enter Username and Password if your provider needs them. A saved password is never shown again, and the form says to leave the box blank to keep it, but in this release a blank box saves an empty password. Retype the password every time you click Save with the override on.
- Click Save.
- Send a real message to yourself (see Check that mail leaves).
Raytha turns on encryption when the port is 587 or 465. On other ports, such as 25, the connection is not encrypted by Raytha.
How the sender is chosen
| Part of the message | Taken from |
|---|---|
| From address and name | The server's SMTP_FROM_ADDRESS and SMTP_FROM_NAME if they are set. Otherwise Default from address and Default from name. |
| Reply-To | The message's own sender if the sender set one, otherwise Default from address and Default from name. |
So if you change Default from address and mail still arrives from the old address, the server's environment variables are winning. Ask whoever runs the server to remove them. Many SMTP providers also reject a From address they do not host, so use an address on a domain your provider has verified.
Check that mail leaves
The Send test button sits next to Save on the Configuration screen. In this release it calls an address the server does not provide, so expect an error message instead of a message in your inbox. Test with a real message instead:
- Open People > Users and click New user.
- Create a test user with your own email address and tick Send welcome email. Alternatively use Reset password on an existing test account with Email the new password ticked.
- Open Observability > Email log.
You should see a new row with your address and a Sent badge, and the message in your inbox shortly after. Delete the test user afterwards.
The email log
Observability > Email log lists every message Raytha tried to send, newest first.
| Part | Meaning |
|---|---|
| When, To, Subject | Sortable columns. |
| Status | Sent means the SMTP server accepted the message. Failed means it did not. |
| The arrow at the start of a row | Opens the message body. For a failed message it also shows the error the SMTP server returned. |
| Filters | Recipient (a complete email address), From and To dates, and a search box that matches part of a subject or recipient. |
The log hides secrets: password reset links, sign-in codes and labelled passwords are replaced with a placeholder, and very long bodies are cut off. Entries are kept 180 days by default; change that under Settings > Maintenance. See Update configuration and system-wide settings.
The email log needs Manage System Settings. Manage Audit Logs does not include it.
Change what the emails say
The wording of each message is a template under Design > Email templates. See Modifying the built-in email templates.
Gotchas
- "Sent" does not always mean delivered. It means your SMTP server took the message. Spam filters and bounces happen after that. Check your provider's own logs for delivery.
- No SMTP host means no mail, with no error. If neither the server nor the admin override provides a host, Raytha skips sending without failing, and the log can still show Sent. Open Settings > Configuration and make sure Host is filled in.
- Port and encryption must match. Providers expect port 587 (or 465) with encryption. A timeout or "connection refused" error in the log usually means the wrong host or port, or a firewall that blocks outgoing SMTP.
- Authentication errors usually mean the wrong user name or password, or that your provider requires an app password. Re-enter the Password and save. This also happens after you change an unrelated field such as Organization name and click Save without retyping the password: the stored password is replaced by an empty one.
- Magic-link sign-in and password reset depend on email. If they fail, check email first. See Troubleshooting.