Nestled includes a built-in email service that supports multiple providers. In development, use a local mail catcher to preview emails without sending them. In production, plug in your SMTP provider of choice.

Development setup

Option A: Mailhog (recommended)

Mailhog is already included in the Docker Compose stack. When you run pnpm dev, it starts automatically.

# If running standalone:
brew install mailhog
mailhog

Then in your .env file:

SMTP_HOST=localhost
SMTP_PORT=1025
SMTP_USER=test
SMTP_PASS=test

Access the Mailhog UI at http://localhost:8025 to view captured emails.

Option B: Mailtrap

Mailtrap is a cloud-based email testing service. Sign up for a free account, copy your SMTP credentials from the inbox settings, and update your .env file.

Option C: Disable email

The application still works without email, but users will not receive verification or password reset emails.

Production setup

Configure your .env file with real SMTP credentials:

# SendGrid
SMTP_HOST=smtp.sendgrid.net
SMTP_PORT=587
SMTP_USER=apikey
SMTP_PASS=your_sendgrid_api_key

# AWS SES
SMTP_HOST=email-smtp.us-east-1.amazonaws.com
SMTP_PORT=587
SMTP_USER=your_ses_smtp_username
SMTP_PASS=your_ses_smtp_password

Restart required

After changing .env variables, restart the API server for the changes to take effect.

Email templates

Templates are located in libs/api/integrations/src/lib/email/templates/. Each template is a TypeScript file that exports a TemplateDefinition object containing template metadata, subject line (with Handlebars variables), HTML template, plain text fallback, and required/optional variables.

The built-in templates:

Template	Purpose
`email-verification.template.ts`	Verify email addresses
`password-reset.template.ts`	Password reset requests
`password-changed.template.ts`	Password change notification
`welcome.template.ts`	Welcome email for new users

Creating a new template

Create a new file in libs/api/integrations/src/lib/email/templates/
Import the TemplateDefinition interface
Export your template following the existing pattern
Import and add it to the EMAIL_TEMPLATES map in index.ts

Templates are compiled into the JavaScript bundle -- no file copying or runtime file reading needed.

Troubleshooting

Check API logs -- the API logs template loading and any errors
Test SMTP connection -- the email service has a testConnection() method
Use Mailhog for development -- captures all emails locally without sending them
Rebuild after template changes -- templates are part of the compiled code, so run npx nx build api after modifying them