Transactional Email

You are a backend engineer building transactional email systems. The user wants to implement a production-ready transactional email service using Resend or SendGrid.

What to check first

• Run npm list resend or npm list @sendgrid/mail to confirm the SDK is installed
• Verify your API key is set in .env as RESEND_API_KEY or SENDGRID_API_KEY
• Check that your email templates directory exists and contains .html or .mjml files

Steps

1. Install the Resend or SendGrid SDK: npm install resend or npm install @sendgrid/mail
2. Create a .env file with your API key from the provider dashboard
3. Set up an email service class that initializes the client with your API key
4. Define email template types (welcome, password-reset, order-confirmation, etc.)
5. Create a function to read and compile HTML templates, supporting variable substitution with {{variable}} syntax
6. Implement the send function with retry logic and error handling for failed deliveries
7. Add request validation to ensure recipient email, subject, and required template variables are present
8. Create a queue or background job handler (Bull, node-cron, or simple in-memory) to retry failed emails after 5 minutes

Code

import Resend from 'resend';
import fs from 'fs/promises';
import path from 'path';

const resend = new Resend(process.env.RESEND_API_KEY);

class TransactionalEmailService {
  constructor() {
    this.templatesDir = path.join(process.cwd(), 'templates/emails');
    this.retryQueue = [];
  }

  async loadTemplate(templateName) {
    try {
      const templatePath = path.join(this.templatesDir, `${templateName}.html`);
      const content = await fs.readFile(templatePath, 'utf-8');
      return content;
    } catch (error) {
      throw new Error(`Template not found: ${templateName}`);
    }
  }

  compileTemplate(template, variables) {
    let compiled = template;
    Object.entries(variables).forEach(([key, value]) => {
      compiled = compiled.replace(new RegExp(`{{${key}}}`, 'g'), String(value));
    });
    return compiled;
  }

  async send(options) {
    const { to, subject, templateName, variables = {}, from = 'noreply@example.com' } = options;

    if (!to || !subject || !templateName) {
      throw new Error('Missing required fields: to, subject, templateName');
    }

    try {
      const template = await this.loadTemplate(templateName);
      const html = this.compileTemplate(template, variables);

      const response = await resend.emails.send({
        from,
        to,

Note: this example was truncated in the source. See the GitHub repo for the latest full version.

Common Pitfalls

• Treating this skill as a one-shot solution — most workflows need iteration and verification
• Skipping the verification steps — you don't know it worked until you measure
• Applying this skill without understanding the underlying problem — read the related docs first

When NOT to Use This Skill

• When a simpler manual approach would take less than 10 minutes
• On critical production systems without testing in staging first
• When you don't have permission or authorization to make these changes

How to Verify It Worked

• Run the verification steps documented above
• Compare the output against your expected baseline
• Check logs for any warnings or errors — silent failures are the worst kind

Production Considerations

• Test in staging before deploying to production
• Have a rollback plan — every change should be reversible
• Monitor the affected systems for at least 24 hours after the change