Email delivery: status and test-send
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.
/api/v1/email/statusSite adminEchoes 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 }.
{
"data": {
"configured": true,
"provider": "smtp",
"from": "noreply@example.com",
"smtp": { "host": "smtp.example.com", "port": 587, "secure": false, "auth": true }
}
}/api/v1/email/testSite adminSends one message to to with the fixed subject
Kywi CMS — test email. The body is strict: to and nothing
else.
{ "data": { "sent": true, "to": "you@example.com" } }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.
[KywiEmail] { to: 'you@example.com', subject: 'Kywi CMS — test email', htmlLength: 105 }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 for how the review flow itself works in the absence of that notification.
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! },
},
},