SMTP Integration

This document explains how to configure the application to send emails using a standard SMTP (Simple Mail Transfer Protocol) server. This could be your own mail server or a third-party provider like Gmail, SendGrid (using SMTP relay), AWS SES (via SMTP), etc.

Configuration

1. Provider Selection: Set NEXT_PUBLIC_EMAIL_PROVIDER to "smtp" in root .env.

2. SMTP Credentials: You must provide the connection details for your SMTP server:

   • SMTP_HOST: The hostname of your SMTP server (e.g., smtp.gmail.com).
   • SMTP_PORT: The port number (e.g., 587 for TLS, 465 for SSL).
   • SMTP_USER: The username for authentication.
   • SMTP_PASS: The password or App Password for authentication.
   • SMTP_SECURE: Whether to use a secure connection (TLS/SSL). Defaults to true. Set to false only if connecting to a non-secure server (uncommon).
   • SMTP fields are validated in packages/env/src/schemas/email.ts when NEXT_PUBLIC_EMAIL_PROVIDER is "smtp".

3. Environment Setup:

   • packages/env/src/schemas/email.ts: Defines "smtp" and SMTP_* variables.
   • .env.example: Includes placeholders for these SMTP variables.

How it Works

When NEXT_PUBLIC_EMAIL_PROVIDER is set to "smtp", the router calls packages/email/src/send-email-smtp.ts, which uses packages/email/src/transports/nodemailer-smtp-transport.ts.

This transport:

• Uses the nodemailer library.
• Checks if all required SMTP_* variables are set (isSmtpConfigured).
• If configured, creates a Nodemailer transport (smtpTransport) using these credentials.
• Verifies the SMTP connection on application startup and logs the status.

The sending logic (send-email-smtp.ts):

• Uses the configured smtpTransport.
• Renders React email components to HTML.
• Calls smtpTransport.sendMail() to send the email via the configured SMTP server.
• Handles multiple recipients by sending individual emails in a loop.

Usage Examples

When SMTP is configured as the provider, it's used by the core sendEmail function for actions like:

• Sending email verification links.
• Sending password reset links.
• Sending email change confirmations (if enabled).

Considerations

• Deliverability: Email deliverability with generic SMTP can be complex. Ensure your sending domain has proper SPF, DKIM, and DMARC records configured. Using a dedicated email service provider often simplifies this. See the General Email Configuration for more details.
• Rate Limits: Be mindful of any sending limits imposed by your SMTP provider (e.g., Gmail limits). See the General Email Configuration for general discussion.
• Security: Use secure connections (SMTP_SECURE=true) whenever possible. If using Gmail, you'll likely need an App Password instead of your regular account password.