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: To use SMTP, set the NEXT_PUBLIC_EMAIL_PROVIDER environment variable to "smtp". This can be done via the configuration UI (/configure) or directly in the .env file.

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).
   • The configuration UI (/configure) displays inputs for these when "SMTP" is selected.
   • The configuration schema (src/app/configure/schema.ts) enforces that HOST and PORT are provided and recommends USER and PASS if NEXT_PUBLIC_EMAIL_PROVIDER is set to "SMTP".

3. Environment Setup:

   • src/env.ts: Defines the NEXT_PUBLIC_EMAIL_PROVIDER enum option "smtp" and the SMTP_* schema (smtpSchema).
   • .env.example: Includes placeholders for these SMTP variables.

How it Works

When NEXT_PUBLIC_EMAIL_PROVIDER is set to "smtp", the core email router calls the SMTP sending logic (src/server/email/send-email-smtp.ts), which uses the SMTP transport defined in src/server/email/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.