Email Configuration

Configure email sending in MakerKit using @kit/mailers with either Nodemailer (SMTP) or Resend (HTTP API). Set MAILER_PROVIDER=nodemailer for universal SMTP compatibility or MAILER_PROVIDER=resend for edge runtime support. Configure SMTP credentials (EMAIL_HOST, EMAIL_PORT, EMAIL_USER, EMAIL_PASSWORD) or a Resend API key, then use getMailer() to send emails.

The MakerKit mailer system is an abstraction layer over email providers that normalizes the sending API, handles provider switching via environment variables, and supports both Node.js and edge runtimes.

• Use Nodemailer when: you need maximum provider flexibility or already have SMTP credentials.
• Use Resend when: deploying to edge runtimes (Cloudflare Workers, Vercel Edge) or want simpler setup.

If unsure: start with Nodemailer for development (works with Mailpit), then consider Resend for production.

Configuring the mailer provider

MakerKit offers the @kit/mailers package to configure and send emails, providing a straightforward API for email operations.

There are two mailer implementations provided by Makerkit:

1. nodemailer: This is the default mailer that leverages the nodemailer library. It's ideal for Node.js environments as it's compatible with any SMTP server, ensuring you're not tied to a specific provider.
2. resend: This mailer uses the Resend API via HTTP. It's a suitable choice if you opt for Resend or are using a runtime that doesn't support Node.js.

The following sections will guide you on configuring the mailer provider to start sending emails from your application.

Nodemailer

To specify the mailer provider, set the MAILER_PROVIDER environment variable in the apps/web/.env file.

For instance, to use the nodemailer mailer, set MAILER_PROVIDER to nodemailer:

MAILER_PROVIDER=nodemailer

By default, nodemailer is used, so you don't need to set the MAILER_PROVIDER environment variable by yourself.

SMTP Configuration

If you're using the nodemailer mailer, you'll need to set the SMTP configuration in your environment variables. Here's an example of the SMTP configuration:

EMAIL_USER=User # refer to your email provider's documentation
EMAIL_PASSWORD=your-password # refer to your email provider's documentation
EMAIL_HOST=smtp.your-email-provider.com # refer to your email provider's documentation
EMAIL_PORT=587 # or 465 for SSL
EMAIL_TLS=true # or false for SSL (see provider documentation)
EMAIL_SENDER=Makerkit <your-email@app.com> # refer to your email provider's documentation

The variables are:

1. EMAIL_USER: The email address username. This is provider-specific, so refer to your email provider's documentation.
2. EMAIL_PASSWORD: The email address password. This is provider-specific, so refer to your email provider's documentation.
3. EMAIL_HOST: The SMTP server host. This is provider-specific, so refer to your email provider's documentation.
4. EMAIL_PORT: The SMTP server port. This is provider-specific, so refer to your email provider's documentation.
5. EMAIL_TLS: The TLS configuration. This is provider-specific, so refer to your email provider's documentation. Generally, you can set it to true.
6. EMAIL_SENDER: The sender of the emails. This is usually the email address of your application. It's usually in the format Sender Name <email@app.com>.

EMAIL_SENDER format

Sometimes, EMAIL_SENDER should be written in the format Sender Name <email@app.com> so that the email provider can identify the sender of the email. This setting can be different for different email providers, so please refer to your email provider's documentation.

Resend

As an alternative, you can use Resend, a modern email service that provides a simple API for sending emails.

Set the MAILER_PROVIDER environment variable to resend in the apps/web/.env file:

MAILER_PROVIDER=resend

And provide the Resend API key:

RESEND_API_KEY=your-api-key
EMAIL_SENDER=your-email

In production, we've found Resend's HTTP API to be more reliable than SMTP when deploying to Vercel - SMTP connections can timeout during cold starts, while Resend's API completes within the function timeout.

Common Pitfalls

• EMAIL_SENDER format varies by provider: Some providers require Name <email@domain.com>, others just email@domain.com. Check your provider's docs - wrong format causes silent failures.
• Nodemailer fails on edge runtime: Nodemailer uses Node.js net module, unavailable in edge. Switch to MAILER_PROVIDER=resend for edge deployments.
• TLS vs SSL confusion: Port 587 uses STARTTLS (EMAIL_TLS=true), port 465 uses implicit SSL. Mismatched settings cause connection refused errors.
• Missing EMAIL_SENDER: The from field defaults to EMAIL_SENDER. If not set, emails may be rejected or marked as spam.
• Development emails going to real addresses: Always use Mailpit locally. Real SMTP credentials in development can accidentally send emails to actual users.
• Resend API key in wrong env file: Set RESEND_API_KEY in apps/web/.env.local, not .env. The .env file is committed to git.

Next: Sending Emails →