Skip to content

The Open Source DocuSign Alternative.

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

Jordan Labrossedcc2ac8a71c8
diff --git a/.env.example b/.env.example
index b2dfb0805..559684160 100644
--- a/.env.example
+++ b/.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="[email protected]"
+# 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.
diff --git a/docker/production/compose.yml b/docker/production/compose.yml
index bd2b9597e..4801edb26 100644
--- a/docker/production/compose.yml
+++ b/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}
diff --git a/packages/email/mailer.ts b/packages/email/mailer.ts
index 21aecfa19..3b5afa524 100644
--- a/packages/email/mailer.ts
+++ b/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='[email protected]';
+ * 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 }
+ : {}),
});
};
diff --git a/turbo.json b/turbo.json
index 753c11911..3a04158c9 100644
--- a/turbo.json
+++ b/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",