Email via SMTP (mail-smtp)
Delivers the emails your app sends through any SMTP server (Amazon SES, Postmark, Mailgun, your own) with Nodemailer.
npx calm add mail-smtp| Adds | |
|---|---|
| Files | app/blocks/mail-smtp/index.js |
| Dependency | nodemailer |
| Environment | SMTP_URL=smtps://user:password@smtp.example.com:465, MAIL_FROM=My App <no-reply@example.com> |
Set SMTP_URL to your server (smtp:// or smtps://, credentials URL-encoded) and MAIL_FROM to the sender. MAIL_FROM takes precedence over mail.from in calm.config.js.
SMTP_URL=smtps://AKIA...:secret@email-smtp.eu-west-1.amazonaws.com:465
MAIL_FROM=My App <no-reply@example.com>While SMTP_URL is empty or still the smtp.example.com placeholder, the block stays inactive: emails go to the devtools Mail panel in development, and calm doctor reports an error in production. The connection is closed on shutdown.
Send email with app.mailer.send({ to, subject, text, html }), exactly as with mail-resend.
Official documentation#
Read these before changing the block; they are also in app/blocks/mail-smtp/AGENTS.md and in the devtools Blocks panel.
- Nodemailer
- Nodemailer: SMTP transport
- Nodemailer: Message configuration
- Amazon SES: Using the SMTP interface
- RFC 5321: Simple Mail Transfer Protocol
For AI agents#
Coding agents read these notes in app/blocks/mail-smtp/AGENTS.md:
- Read first:
app/blocks/mail-smtp/index.js(one Nodemailer transport registered withcalm.mailer.use). - Configuration: env
SMTP_URL(secret;smtp://with STARTTLS, usually port 587, orsmtps://for implicit TLS on 465) andMAIL_FROM. Nocalm.config.jsoptions. Unset, or still thesmtp.example.complaceholder, means no transport: development mail stays in devtools andcalm doctorerrors in production. - Invariant:
SMTP_URLcontains credentials. Never log it, include it in errors or commit it; URL-encode special characters in the user name and password. - Send through
app.mailer.send({ to, subject, text, html }); do not create other Nodemailer transports in features, so tests and devtools keep capturing mail. - Only
from,to,subject,textandhtmlreachtransport.sendMail. Addcc,bcc,replyTo,attachmentsorheadersthere using Nodemailer message fields.metais stripped by the core. - Transport options beyond the URL (
pool, timeouts,tls): pass an options object tonodemailer.createTransportinstead of the URL string. Keeptransport.close()incalm.onShutdown. - Only one mail transport is active:
calm.mailer.usereplaces the previous one, so do not install mail-resend next to it. - Pitfall: most providers (SES, Postmark, Gmail) only accept a verified sender in
MAIL_FROM; SES SMTP credentials are not your IAM access keys. - Pitfall:
sendMailerrors propagate to the caller; send from a job (jobs block) when you need retries. When delivery fails,await transport.verify()in a script checks the connection and credentials.