Skip to content

Email Notification System

Relevant source files - config/nodemailer.js - controllers/workflow.controller.js - utils/email-template.js - utils/send-email.js

The Email Notification System is responsible for dispatching automated renewal reminders to users. It integrates with the Brevo SMTP relay and is triggered by the Upstash Workflow engine to ensure reliable, scheduled delivery of HTML-formatted notifications at specific intervals before a subscription's renewal date.

SMTP Configuration

The system uses nodemailer as the primary transport library, configured to communicate with the Brevo (formerly Sendinblue) SMTP relay. The configuration is centralized in config/nodemailer.js and includes specific timeouts and diagnostic logging to ensure reliability in cloud environments like Render.

Transporter Settings

The transporter object is initialized with the following parameters:

Parameter Value Description
Host smtp-relay.brevo.com Brevo SMTP endpoint config/nodemailer.js14
Port 587 Standard SMTP port for STARTTLS config/nodemailer.js15
Secure false Uses STARTTLS rather than implicit SSL config/nodemailer.js16
Authentication BREVO_LOGIN, BREVO_SMTP_KEY Credentials loaded from environment config/nodemailer.js17-20
Timeouts 5s - 10s Short timeouts to prevent hanging processes config/nodemailer.js23-25

Health Checks

The system provides a verifyTransporter function that wraps transporter.verify(). This is used to validate the connection to the SMTP server during the email dispatch sequence config/nodemailer.js32-44

Sources:

Email Dispatch Pipeline

The dispatch pipeline bridges the gap between the asynchronous workflow engine and the SMTP relay. It handles data formatting, template selection, and error logging.

The sendReminderEmail Utility

Defined in utils/send-email.js, this function is the primary entry point for sending notifications. It performs the following steps:

  1. Validation: Ensures recipient email and template type are provided utils/send-email.js9
  2. Template Lookup: Matches the type parameter against the emailTemplates array utils/send-email.js11
  3. Data Preparation: Formats subscription data (e.g., using dayjs for dates) into a mailInfo object utils/send-email.js15-22
  4. Generation: Calls the template's generator functions to produce the final HTML and Subject line utils/send-email.js24-25
  5. Execution: Performs a pre-send verification before calling transporter.sendMail()utils/send-email.js38-47

Email Workflow Integration

The following diagram illustrates how the sendReminders workflow interacts with the email utility and the SMTP transporter.

Email Pipeline Flow

[Flowchart Diagram]

Sources:

Email Templates

The system supports four specific reminder intervals defined in utils/email-template.js. All templates share a common responsive HTML layout generated by the generateEmailTemplate function.

Reminder Intervals

The emailTemplates array defines the logic for different stages of the renewal cycle:

Label Subject Line Prefix Days Left
7 days before reminder 📅 Reminder: Your... 7
5 days before reminder ⏳ ...Renews in 5 Days 5
2 days before reminder 🚀 2 Days Left! 2
1 days before reminder ⚡ Final Reminder: 1

Data Mapping

The templates expect a mailInfo object containing:

Sources:

Implementation Details

Data Flow: From Model to Inbox

The following diagram maps the transformation of data from the Subscription model through the email generation logic.

Data Mapping: Model to Template

[Flowchart Diagram]

Error Handling and Diagnostics

The system is designed to be "fail-vocal" to assist in troubleshooting:

  • Verification Logs: verifyTransporter logs the status of the SMTP connection config/nodemailer.js35
  • Detailed Error Catching: In sendReminderEmail, the catch block logs the error message, code, and response from the SMTP server before re-throwing the error to the workflow engine for potential retries utils/send-email.js50-58
  • Execution Timing: The system logs the elapsed time for each email sent to monitor performance utils/send-email.js49

Sources: