feat(email): support configurable SMTP service (#1447)

.env.example

@@ -93,6 +93,8 @@ NEXT_PRIVATE_SMTP_UNSAFE_IGNORE_TLS=
 NEXT_PRIVATE_SMTP_FROM_NAME="Documenso"
 # REQUIRED: Defines the email address to use as the from address.
 NEXT_PRIVATE_SMTP_FROM_ADDRESS="noreply@documenso.com"
+# OPTIONAL: Defines the service for nodemailer
+NEXT_PRIVATE_SMTP_SERVICE=
 # OPTIONAL: The API key to use for Resend.com
 NEXT_PRIVATE_RESEND_API_KEY=
 # OPTIONAL: The API key to use for MailChannels.

docker/production/compose.yml

@@ -50,6 +50,7 @@ services:
       - NEXT_PRIVATE_SMTP_SECURE=${NEXT_PRIVATE_SMTP_SECURE}
       - NEXT_PRIVATE_SMTP_FROM_NAME=${NEXT_PRIVATE_SMTP_FROM_NAME:?err}
       - NEXT_PRIVATE_SMTP_FROM_ADDRESS=${NEXT_PRIVATE_SMTP_FROM_ADDRESS:?err}
+      - NEXT_PRIVATE_SMTP_SERVICE=${NEXT_PRIVATE_SMTP_SERVICE}
       - NEXT_PRIVATE_RESEND_API_KEY=${NEXT_PRIVATE_RESEND_API_KEY}
       - NEXT_PRIVATE_MAILCHANNELS_API_KEY=${NEXT_PRIVATE_MAILCHANNELS_API_KEY}
       - NEXT_PRIVATE_MAILCHANNELS_ENDPOINT=${NEXT_PRIVATE_MAILCHANNELS_ENDPOINT}

packages/email/mailer.ts

@@ -1,10 +1,56 @@
+import type { Transporter } from 'nodemailer';
 import { createTransport } from 'nodemailer';
 
 import { ResendTransport } from '@documenso/nodemailer-resend';
 
 import { MailChannelsTransport } from './transports/mailchannels';
 
-const getTransport = () => {
+/**
+ * Creates a Nodemailer transport object for sending emails.
+ *
+ * This function uses various environment variables to configure the appropriate
+ * email transport mechanism. It supports multiple types of email transports,
+ * including MailChannels, Resend, and different SMTP configurations.
+ *
+ * @returns {Transporter} A configured Nodemailer transporter instance.
+ *
+ * Supported Transports:
+ * - **mailchannels**: Uses MailChannelsTransport, requiring:
+ *   - `NEXT_PRIVATE_MAILCHANNELS_API_KEY`: API key for MailChannels
+ *   - `NEXT_PRIVATE_MAILCHANNELS_ENDPOINT`: Endpoint for MailChannels (optional)
+ * - **resend**: Uses ResendTransport, requiring:
+ *   - `NEXT_PRIVATE_RESEND_API_KEY`: API key for Resend
+ * - **smtp-api**: Uses a custom SMTP API configuration, requiring:
+ *   - `NEXT_PRIVATE_SMTP_HOST`: The SMTP server host
+ *   - `NEXT_PRIVATE_SMTP_APIKEY`: The API key for SMTP authentication
+ *   - `NEXT_PRIVATE_SMTP_APIKEY_USER`: The username for SMTP authentication (default: 'apikey')
+ * - **smtp-auth** (default): Uses a standard SMTP configuration, requiring:
+ *   - `NEXT_PRIVATE_SMTP_HOST`: The SMTP server host (default: 'localhost:2500')
+ *   - `NEXT_PRIVATE_SMTP_PORT`: The port to connect to (default: 587)
+ *   - `NEXT_PRIVATE_SMTP_SECURE`: Whether to use SSL/TLS (default: false)
+ *   - `NEXT_PRIVATE_SMTP_UNSAFE_IGNORE_TLS`: Whether to ignore TLS (default: false)
+ *   - `NEXT_PRIVATE_SMTP_USERNAME`: The username for SMTP authentication
+ *   - `NEXT_PRIVATE_SMTP_PASSWORD`: The password for SMTP authentication
+ *   - `NEXT_PRIVATE_SMTP_SERVICE`: The SMTP service provider (e.g., "gmail"). This option is used
+ *     when integrating with well-known services (like Gmail), enabling simplified configuration.
+ *
+ * Example Usage:
+ * ```env
+ * NEXT_PRIVATE_SMTP_TRANSPORT='smtp-auth';
+ * NEXT_PRIVATE_SMTP_HOST='smtp.example.com';
+ * NEXT_PRIVATE_SMTP_PORT=587;
+ * NEXT_PRIVATE_SMTP_SERVICE='gmail';
+ * NEXT_PRIVATE_SMTP_SECURE='true';
+ * NEXT_PRIVATE_SMTP_USERNAME='your-email@gmail.com';
+ * NEXT_PRIVATE_SMTP_PASSWORD='your-password';
+ * ```
+ *
+ * Notes:
+ * - Ensure that the required environment variables for each transport type are set.
+ * - If `NEXT_PRIVATE_SMTP_TRANSPORT` is not specified, the default is `smtp-auth`.
+ * - `NEXT_PRIVATE_SMTP_SERVICE` is optional and used specifically for well-known services like Gmail.
+ */
+const getTransport = (): Transporter => {
   const transport = process.env.NEXT_PRIVATE_SMTP_TRANSPORT ?? 'smtp-auth';
 
   if (transport === 'mailchannels') {
@@ -53,6 +99,9 @@ const getTransport = () => {
           pass: process.env.NEXT_PRIVATE_SMTP_PASSWORD ?? '',
         }
       : undefined,
+    ...(process.env.NEXT_PRIVATE_SMTP_SERVICE
+      ? { service: process.env.NEXT_PRIVATE_SMTP_SERVICE }
+      : {}),
   });
 };
 

turbo.json

@@ -105,6 +105,7 @@
     "NEXT_PRIVATE_SMTP_UNSAFE_IGNORE_TLS",
     "NEXT_PRIVATE_SMTP_FROM_NAME",
     "NEXT_PRIVATE_SMTP_FROM_ADDRESS",
+    "NEXT_PRIVATE_SMTP_SERVICE",
     "NEXT_PRIVATE_STRIPE_API_KEY",
     "NEXT_PRIVATE_STRIPE_WEBHOOK_SECRET",
     "NEXT_PRIVATE_GITHUB_TOKEN",