Your app sends mail for sign-in links, password resets, invitations, invoices and “your export is ready” messages. Strutvane gives you one way to write a mail and several mailers (ways to deliver it): a local inbox while you develop, and SMTP or a provider such as Resend, Postmark or Amazon SES in production. Your code doesn’t change when you switch.
The smallest example
Section titled “The smallest example”Without touching any setting, sign-in mails already work in development. Ask for a password reset:
curl -X POST http://localhost:3000/forgot-password \ -H "Content-Type: application/json" \ -H "Origin: http://localhost:3000" \ -d '{"email":"admin@my-app.test"}'What you’ll see depends on how you installed the app:
-
With Docker: open
http://localhost:8025. The Mailpit inbox shows “Reset your password”, with the link inside. Nothing left your computer. -
Without Docker: the mail is written to your log, link included:
[2026-11-15 10:22:01.123] local.INFO: Mail (log mailer) {"to":"admin@my-app.test","subject":"Reset your password","mailer":"log"}(Something like this; the exact line isn’t final. The full mail body follows it.)
Mailpit is a small mail server with a web inbox that catches every mail your app sends, so you can click links and check layouts without emailing real people.
Where mail goes
Section titled “Where mail goes”The MAIL_MAILER key in .env picks the mailer:
MAIL_MAILER |
Where mail goes | Used for |
|---|---|---|
log |
written to your log, never sent | development without Docker (the default there) |
smtp |
an SMTP server | development with Docker (Mailpit), and production with any SMTP provider |
array |
kept in memory | tests (and Mail.fake()) |
resend, postmark, ses |
the provider’s HTTP API | production (coming in 0.3) |
failover, roundrobin |
several mailers | production resilience (coming in 0.3) |
The .env a new app gets:
With Docker:
MAIL_MAILER=smtpMAIL_HOST=mailpitMAIL_PORT=1025FORWARD_MAILPIT_PORT=8025MAIL_FROM_ADDRESS="hello@my-app.test"MAIL_FROM_NAME="My App"Without Docker:
MAIL_MAILER=logMAIL_FROM_ADDRESS="hello@my-app.test"MAIL_FROM_NAME="My App"MAIL_FROM_ADDRESS and MAIL_FROM_NAME are Laravel’s names for the sender; their exact keys in Strutvane aren’t final.
Production: choosing a mailer
Section titled “Production: choosing a mailer”The installer asks which mailer to use in production (question 20): decide later (the default), SMTP, Resend, Postmark or SES. You can change it any time in .env.
SMTP (works with almost any provider)
Section titled “SMTP (works with almost any provider)”MAIL_MAILER=smtpMAIL_HOST=smtp.example-provider.comMAIL_PORT=587MAIL_USERNAME=apikeyMAIL_PASSWORD=your-smtp-passwordMAIL_FROM_ADDRESS="hello@app.example.com"MAIL_FROM_NAME="Acme Portal"Port 587 uses STARTTLS, 465 uses TLS from the start. Never use plain port 25 from a cloud server: most hosts block it.
A provider’s API (coming in 0.3)
Section titled “A provider’s API (coming in 0.3)”MAIL_MAILER=resendRESEND_API_KEY=re_live_…API mailers are usually faster than SMTP and report bounces. Each driver documents its own key names when it’s released.
Before your first real mail
Section titled “Before your first real mail”Mail providers only deliver reliably when your domain proves the mail is yours:
- Verify your sending domain in the provider’s dashboard.
- Add the SPF and DKIM DNS records they give you (they prove your server may send for your domain).
- Add a DMARC record (it tells receivers what to do with mail that fails those checks).
- Send a test mail to yourself and check it isn’t in spam.
Writing your own mail: mailables
Section titled “Writing your own mail: mailables”A mailable is a class that describes one kind of mail: who it’s for, the subject, and what’s in it. Make one:
node strut make:mail PostPublishedimport { Mailable } from '@strutvane/framework'import type { Post } from '../models/post.ts'import { PostPublishedEmail } from '../../resources/mail/post-published.tsx'
/** Tells the author their post is live. */export class PostPublished extends Mailable { constructor(readonly post: Post) { super() }
subject(): string { return `"${this.post.title}" is live` }
render() { return <PostPublishedEmail title={this.post.title} slug={this.post.slug} /> }}The template is a React component:
import { Button, Layout, Text } from '@strutvane/framework/mail'
export function PostPublishedEmail({ title, slug }: { title: string; slug: string }) { return ( <Layout preview={`${title} is live`}> <Text>Good news: your post "{title}" is now published.</Text> <Button href={`https://app.example.com/posts/${slug}`}>View your post</Button> </Layout> )}Send it:
import { Mail } from '@strutvane/framework'import { PostPublished } from '../../mail/post-published.mail.tsx'
await Mail.to(author).send(new PostPublished(post))What you’ll see: in Mailpit, a mail titled "Hello world" is live with a button. The mail goes to author.email. React escapes {title}, so a post titled <script> can’t inject anything into the mail.
Recipients, copies and attachments
Section titled “Recipients, copies and attachments”await Mail.to(author) .cc('editor@acme.test') .bcc(['audit@acme.test']) .send(new PostPublished(post).attach('storage/app/exports/posts-2026-11.csv', { name: 'posts.csv' }))Attach files from a storage disk rather than from paths users control.
Sending later: queued mail
Section titled “Sending later: queued mail”Sending takes time (a network round trip to the mail server). Don’t make the user wait:
await Mail.to(author).queue(new PostPublished(post))The request answers at once; a queue worker sends the mail. If the mail server is down, the worker retries with back-off, and after the last try the job is recorded as failed (node strut queue:retry sends it again).
Sending only after the database commits
Section titled “Sending only after the database commits”Imagine you create a post in a transaction and queue a mail about it. If the worker is fast, it may look for the post before the transaction commits, and not find it. Or the transaction rolls back and the mail announces a post that doesn’t exist.
afterCommit holds the mail until the transaction has committed, and drops it if it rolls back:
await Mail.to(author).queue(new PostPublished(post), { afterCommit: true })The same afterCommit: true option exists on events and jobs (parity checklist). See Transactions.
Previewing mail in the browser
Section titled “Previewing mail in the browser”http://localhost:3000/_strutvane/mail/preview/post-publishedFailover and round robin
Section titled “Failover and round robin”import { defineConfig, env } from '@strutvane/framework'
export default defineConfig({ default: env.string('MAIL_MAILER', 'log'), mailers: { smtp: { transport: 'smtp', host: env.string('MAIL_HOST'), port: env.number('MAIL_PORT', 587) }, postmark: { transport: 'postmark' }, // Try Postmark first; if it fails, send through SMTP instead. failover: { transport: 'failover', mailers: ['postmark', 'smtp'] }, // Spread mail evenly over two providers. roundrobin: { transport: 'roundrobin', mailers: ['postmark', 'smtp'] }, },})With MAIL_MAILER=failover, a Postmark outage means mail goes through SMTP and one warning is logged per failed attempt.
When the mail server is down
Section titled “When the mail server is down”What happens depends on how the mail was sent:
| How it was sent | The user sees | You see |
|---|---|---|
| A sign-in mail (reset, verification, link, invitation) | the normal answer ({"status":"sent"}) |
one log line with the mail kind and user id; the link is never logged |
Mail.to().send() in a request |
an error page (500), unless you catch it | the exception in the log with the mailer’s message |
Mail.to().queue() |
the normal answer | retries in the worker log, then a failed job |
failover mailer |
the normal answer | a warning, and the mail sent by the next mailer |
Why sign-in mails never fail the request: a different answer when delivery fails would tell an attacker that the account exists. The sign-in mails are also sent in the background, so the response time doesn’t depend on the mail server either.
A typical connection failure in the log looks something like this:
[2026-11-15 10:22:01.456] production.ERROR: Mail could not be sent {"mailer":"smtp","kind":"password-reset","error":"connect ETIMEDOUT 203.0.113.25:587"}Testing mail
Section titled “Testing mail”In tests, Mail.fake() keeps mails in memory and lets you check them:
import { Mail } from '@strutvane/framework'import { client } from '@strutvane/framework/testing'import { expect, it } from 'vitest'import { PostPublished } from '../../app/mail/post-published.mail.tsx'
it('mails the author when a post is published', async () => { Mail.fake() await client(app).withToken(aliceToken).postJson('/api/posts/hello-world/publish', {}) Mail.assertSent(PostPublished, (sent) => sent.post.slug === 'hello-world') Mail.assertSentCount(1)})With Docker or without Docker
Section titled “With Docker or without Docker”| With Docker | Without Docker | |
|---|---|---|
| Default mailer | smtp to Mailpit |
log |
| Where to read mail | http://localhost:8025 |
storage/logs/ |
| Port taken? | change FORWARD_MAILPIT_PORT in .env, then node strut services:up |
— |
On Windows, open the log with any editor, or follow it live with node strut log:tail. On macOS and Linux, tail -f storage/logs/*.log works too.
Common mistakes
Section titled “Common mistakes”No mail arrives in development
Section titled “No mail arrives in development”Why: without Docker, the log mailer writes mail to the log and sends nothing. With Docker, the Mailpit container may be stopped.
Fix: look in storage/logs/, or start the services and open Mailpit:
node strut services:up“connect ECONNREFUSED 127.0.0.1:1025”
Section titled ““connect ECONNREFUSED 127.0.0.1:1025””Error: connect ECONNREFUSED 127.0.0.1:1025Why: MAIL_HOST=mailpit only works inside Docker. Something running on your computer (outside the container) tried localhost:1025, where nothing listens.
Fix: run the command through node strut (which forwards into the container), or use the log mailer when you run without Docker.
Mail works locally but not in production
Section titled “Mail works locally but not in production”Why: usually MAIL_* keys are missing on the server (it falls back to log), the SMTP password is wrong, or the provider hasn’t verified your domain yet.
Fix: check the server’s environment, then send a test mail and read the log line. A wrong password looks something like this:
production.ERROR: Mail could not be sent {"mailer":"smtp","error":"535 Authentication failed"}Links in mails point at localhost
Section titled “Links in mails point at localhost”Why: links are built from APP_URL, which still has its development value on the server.
Fix:
APP_URL=https://app.example.comMy mail lands in spam
Section titled “My mail lands in spam”Why: the sending domain has no SPF, DKIM or DMARC records, or MAIL_FROM_ADDRESS uses a domain you haven’t verified with the provider.
Fix: follow Before your first real mail.
The queued mail says the post doesn’t exist
Section titled “The queued mail says the post doesn’t exist”Why: the mail was queued inside a transaction, and the worker ran before it committed.
Fix: { afterCommit: true }.
Next steps
Section titled “Next steps”- Notifications: one message over mail, the in-app bell and more.
- Queues: sending mail in the background.
- Password Reset and Email Verification: the built-in mails.
- Docker: Mailpit and the local services.