Sending emails

Raytha sends mail for account events: a new account, password recovery, password changes and one-time sign-in codes. It talks to any SMTP server. This page covers the two ways to configure it, the built-in templates, the email log and a way to test it without a real mail provider.

Configure SMTP

There are two places to put SMTP settings. Use one.

With environment variables

SMTP_HOST=smtp.example.com
SMTP_PORT=587
[email protected]
SMTP_PASSWORD=...
[email protected]
SMTP_FROM_NAME=Example CMS

This is the system SMTP. If SMTP_FROM_ADDRESS or SMTP_FROM_NAME are set, they decide the From header. Otherwise Raytha uses the default from address and name saved in the admin under Settings, Configuration.

In the admin

Open Settings, Configuration, tick Override system SMTP, and fill in host, port, username and password. When the override is on, Raytha uses these values and ignores SMTP_HOST, SMTP_PORT, SMTP_USERNAME and SMTP_PASSWORD.

If SMTP_HOST is empty, the page shows "Server SMTP environment variables are missing. Override is required." and the override is forced on. The first-run setup turns the override on for you in that case.

Ports and encryption

Port	What Raytha does
587	Enables TLS. Use this with providers that offer STARTTLS submission, which is most of them.
465	Also enables TLS, but Raytha uses .NET's SmtpClient, which negotiates STARTTLS and does not support implicit TLS. If your provider only offers implicit TLS on 465, use its 587 endpoint.
anything else (25, 2525, 1025)	No TLS. Credentials are sent in clear text, so use these only for a local mail catcher or a trusted internal relay.

What gets sent, and when

Nine templates ship with Raytha. They are created during setup and live in the database, so you can edit them under Email templates.

Developer name	Sent when
raytha_email_admin_welcome	An administrator account is created.
raytha_email_admin_passwordchanged	An administrator's password is changed.
raytha_email_admin_passwordreset	An administrator's password is reset by another administrator.
raytha_email_user_welcome	A public-site user account is created.
raytha_email_user_passwordreset	A user's password is reset by an administrator.
raytha_email_login_beginforgotpassword	Someone starts "forgot password". It contains a reset link that expires after 15 minutes.
raytha_email_login_completedforgotpassword	A forgotten password has been recovered.
raytha_email_login_beginloginwithmagiclink	Someone asks to sign in by email. In 2.0 this sends a one-time code (Target.Code) rather than a link.
raytha_email_user_passwordchanged	Never. The template exists but nothing sends it in 2.0.

Subjects and bodies are Liquid templates. For example, the subject of the recovery email is [{{ CurrentOrganization.OrganizationName }}] Password recovery. Every edit is kept as a revision you can revert to. Links in the emails are built from the Website URL in Settings, Configuration, never from the request, so a wrong Website URL means broken links in every email.

For a walk-through of editing a template, see Modifying the built-in email templates.

The email log

Every message Raytha tries to send is recorded under Observability, Email log. Each row has the recipient, subject, whether it succeeded, the error if not, and how long the SMTP call took. Filter by recipient, date range or free text.

• The stored body is the rendered HTML or text, truncated at 200,000 characters.
• Password-reset links, sign-in codes and temporary passwords are replaced with [redacted] in the stored copy, so the log is safe to show to support staff.
• Rows are deleted after the retention period, 180 days by default. Change it, or keep rows forever with 0, under Settings, Maintenance, Data retention.
• The From value is the message's reply-to identity, which is blank for several built-in emails. It is not the SMTP envelope sender.
• "Success" means the SMTP server accepted the message. It does not tell you whether the recipient received it.

The same data is available from the admin API at GET /raytha/api/admin/email-log, using a signed-in session cookie.

Test your setup

Run a local mail catcher so nothing leaves your machine. MailHog shows every message in a web page:

docker run -d --name mailhog -p 1025:1025 -p 8025:8025 mailhog/mailhog

Start Raytha with SMTP_HOST=localhost and SMTP_PORT=1025. If Raytha runs in a container, use the host's address or put both on one Docker network and use the container name. Then trigger a real email:

1. Sign out and choose the forgot-password link on the sign-in page, or create a new administrator under Admins.
2. Open http://localhost:8025 to read the message.
3. Open the Email log and check that the row shows success.

The repository's tools/dev.sh starts MailHog and points Raytha at it for you. See Local development.

With a real provider the steps are the same: send yourself a password recovery email and check the log. A failure shows the SMTP error message in the log row, such as a rejected sender or an authentication failure.

Gotchas

• The Send test button on the Configuration page calls an endpoint that does not exist in 2.0.0 and reports an error. Test by triggering a real email as above.
• If no SMTP host is configured at all, Raytha logs a warning, skips the send and still records the message in the email log as successful. An empty email log row is not proof that mail works.
• The SMTP password you save in the admin is stored in plain text in the database. Treat database dumps accordingly. See Backups and restores.
• The SMTP From address must be one your provider lets you send as. Most providers reject others even when the credentials are valid.
• Emails are sent from the request that triggers them, so a slow SMTP server slows that request.

Next steps

• Email templates: the variables each template can use.
• Set up SMTP and email in the user guide.
• Configuration for all SMTP_* variables.