Built with Chinaski

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 — 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 — 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.