# Email delivery: status and test-send

URL: https://kywi-docs-production.up.railway.app/operating/email-delivery-status-and-test-send
Type: docPage

Email status echoes the non-secret provider fields and a test send is the only way to tell real SMTP from the console provider Kywi silently falls back to.

Two siteAdmin routes: one reads back what the deploy thinks it is configured with, one sends a single message through it. Email is configured once per deployment, so neither takes a site. Both can report success while nothing is delivered, so read them together with an inbox.

Echoes the non-secret fields of the `email` config block. `auth` is a boolean — whether SMTP credentials are set, never what they are — and the SMTP password and any API key are never returned. With no `email` block at all the whole body is `{ "configured": false }`.

Sends one message to `to` with the fixed subject `Kywi CMS — test email`. The body is strict: `to` and nothing else.

curl -s -H "Authorization: Bearer $KYWI_ADMIN_TOKEN" \ "https://example.com/api/v1/email/status" curl -s -X POST -H "Authorization: Bearer $KYWI_ADMIN_TOKEN" \ -H 'Content-Type: application/json' -d '{"to":"you@example.com"}' \ "https://example.com/api/v1/email/test"

## A success response that means nothing arrived

The config type accepts `provider: 'sendgrid'` and a `sendgrid.apiKey` alongside it. Nothing implements it. Kywi builds a real transport for exactly one shape — `provider: 'smtp'` *with* a `smtp` block — and every other combination falls through to a console provider that writes the message to stdout and resolves. A missing `smtp` block under `provider: 'smtp'` falls through the same way.

## Both routes will tell you it is fine

`status` reports `"provider": "sendgrid"` because it reads the config, not the object that was constructed from it. `test` returns `{ "sent": true }` because the console provider's send succeeded. Neither is lying and neither is checkable from the response. The only proof of delivery is arrival — and the tell on the server is a log line where a message should have been:

[KywiEmail] { to: 'you@example.com', subject: 'Kywi CMS — test email', htmlLength: 105 }

## stdout — the console fallback, not a delivery

That is the html *length*, not the html: the message body is not recoverable from the log. If a test send returns `sent: true` and this line appears, the deploy is not sending mail — fix the config rather than chasing the recipient's spam folder.

## The other failure shapes

Omitting the `email` block entirely is the loud version, and much safer than a half-configured one: `status` answers `{ "configured": false }`, `test` answers `501 NOT_CONFIGURED` — *Email provider is not configured* — and the password-reset routes are not registered at all, so that flow 404s instead of appearing to work.

A malformed address is a validation error and a malformed body is `400 BAD_REQUEST`, *Invalid JSON*. The one worth reading closely is `502 EMAIL_SEND_FAILED`: its message is the transport's own, so an authentication failure, a refused connection or a TLS mismatch surfaces there verbatim. A 502 means the SMTP path is real and rejected you, which is better news than a 200 from the console provider. A test send, password reset, form email or comment notification that throws is not retried or queued; it is lost.

## What stops working when this is wrong

Four request-time flows are wired to the provider, so a silent fallback breaks all four at once: password reset (an admin locked out with no way back in), form notifications (submissions land in the database but nobody is told), form confirmations (the visitor gets no receipt), and comment notifications. A fifth template exists in code for approval requests, but nothing calls it — reviewers are not notified by email today regardless of whether email is configured correctly. See [reviewing and approving submissions](/governing/reviewing-and-approving-submissions/) for how the review flow itself works in the absence of that notification.

## Expiration notices wait for a real provider

The page expiration notice (Expiration Notify on a page’s Publishing tab) is the one flow that does not fall back quietly. The sweep that sends it is handed no provider at all when the configured one is the console logger, so nothing is logged and nothing is marked sent: the notices stay pending and go out on the first sweep after SMTP, or a provider your host app supplies, is in place — including for pages that expired in the meantime. It is also the one flow that retries: a notice whose send fails is tried again with backoff on later sweeps, up to five attempts per recipient, and a sweep that has sent nothing leaves the rest for the next one after three failures in a row. The `test` route above reports success either way, so it cannot tell you whether notices will go out. See [Publishing, scheduling and expiry](/authoring/publishing-scheduling-and-expiry/).

## The SMTP block

SMTP is nodemailer with four fields and no extras: `host`, `port`, `secure` (false unless set) and `auth` with `user` and `pass`. There is no pooling, timeout or TLS option to pass through. Keep `nodemailer` in `serverExternalPackages` in `next.config.mjs` — the scaffold puts it there, and dropping it bundles a server-only package into the client build.

email: { provider: 'smtp', from: 'noreply@example.com', smtp: { host: process.env.SMTP_HOST!, port: Number(process.env.SMTP_PORT ?? 587), secure: false, auth: { user: process.env.SMTP_USER!, pass: process.env.SMTP_PASS! }, }, },

## kywi.config.ts
