Email Settings

Chinaski emails people when something happens: password resets, review decisions, new form submissions, scheduled publishing, security alerts, and build outcomes. Every message goes out through one SMTP relay you configure under Settings → Email. This page explains the configuration, the transport’s security rules, and everything that sends mail.

Configuring the relay

On the Email tab:

Field	Default	What to know
SMTP host	n/a	Your mail relay’s hostname (e.g. smtp.example.com)
SMTP port	587	Common ports: 587, 465, 25, 2525
Encryption	STARTTLS	Or SSL/TLS, or None (plain text): prefer STARTTLS or SSL
From address	n/a	The address your messages send from (e.g. noreply@example.com)
SMTP username	blank	Blank if the relay requires no authentication
SMTP password	blank	Stored encrypted; forms show “leave blank to keep current.” The hint suggests an app password
Build notification email	blank	Build success/failure notes go here; blank disables those notes

Two test buttons live right on the tab:

• Send test email: type any address and the CMS sends a message through the exact configured relay. On failure, the response tells you which stage failed (connect, TLS, authentication, sender acceptance, recipient validation, or sending) plus “check host, port, and credentials.”
• Send test build notification: exercises the build-notification address specifically, so both halves can be verified independently.

Transport security (built in)

• STARTTLS upgrades the connection after connecting; SSL/TLS connects encrypted from the start. Both verify certificates (against the relay’s hostname) by default, so credentials can’t be captured by a forged certificate. None connects in plain text; useful only for relays on a private network.
• If your relay uses a self-signed certificate, CHINASKI_SMTP_INSECURE_NOVERIFY=1 in the instance env is the single documented opt-out from certificate verification.
• Authentication is attempted only when both username and password are set; relays without auth are fine blank.
• Every notification is plain text UTF-8; header values are sanitized against injection.

Air-gap mode

In air-gap mode no email is sent, ever; the transport returns immediately with no network attempt. Form emails, notifications, and scheduled summaries are all skipped, and the Integrations tab says so. Nothing needs configuring to make this happen; it’s global.

Who gets mail, and when

• You (site admin), typically via either the build-notification address or the review-notification address:
  • A build succeeded or failed (if Build notification email is set, sent by the builder after each build; delivery failures never disturb the build outcome).
  • Sustained repeated sign-in failures (first alert per hour, to the same build-notification address).
  • Content was auto-published by the scheduler (summary with per-item titles and languages, address set on the Integrations tab).
  • Review submissions: “A page has been submitted for review by …” with a direct edit link (address set under Settings → Workflow).
• Content creators, when they have an email on file:
  • Page approval (or rejection with a reason): the Approval Workflow notifications.
• Submitters and recipients (Forms):
  • A confirmation email to the visitor when the form has a reply-to field configured (subject/From-name are per-form settings; the body is a thank-you plus a copy of their answers); sent asynchronously.
  • The notification email to your recipients, one per submission, listing every field’s value, the submitted IP (unless disabled or privacy-requested), and the timestamp.
• Users: password-reset links, and admin-sent invitations/resets with their documented time limits.

The two types of failure

• Relay-side failures: the send returns a flash or log entry naming the stage that failed (connect, STARTTLS, AUTH, MAIL FROM, RCPT TO, or DATA) plus the server’s code. The SMTP test button is the fastest diagnostic.
• Silent non-configurations: most commonly “the setting exists but the send was skipped”: air-gap mode active, no From address, the form’s notify/confirmation fields blank, or a reset/other action whose recipient had no valid email. Each path deliberately treats a missing configuration as “no send” rather than an error.
• Build notification failures are special: they’re logged (a build_notify_email_failed event) but never turn a good build into a failure, or vice versa.

Practical guidance

• Use an app password rather than your personal account password (the field hint says so); relay credentials are sensitive, even encrypted.
• Set the From address before any sending workflow: several paths require it even with a working relay.
• After changing any field, use the test button that corresponds to what you changed; the flash gives you a precise reason rather than “email didn’t arrive.”
• Form-specific notifications are configured per form (Forms → edit): reply-to field, subject line, notify addresses, IP inclusion, and the thank-you URL; the Email tab is the relay, not the behavior.
• If an important message never arrived, the audit log entries (approvals) and the flash results at the triggering action tell you whether the send was attempted and what the relay said.