NestJS Enterprise Email Microservice with a Durable Postgres Job Queue

import { Injectable, Logger, OnModuleDestroy, OnModuleInit } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import PgBoss from 'pg-boss';

export interface EmailJobData {
  to: string;
  subject: string;
  html?: string;
  text: string;
  idempotencyKey: string;
}

export const EMAIL_QUEUE = 'transactional-email';

@Injectable()
export class EmailProcessor implements OnModuleInit, OnModuleDestroy {
  private readonly logger = new Logger(EmailProcessor.name);
  private readonly boss: PgBoss;
  private readonly apiKey: string;

  constructor(private readonly config: ConfigService) {
    this.boss = new PgBoss(this.config.getOrThrow<string>('DATABASE_URL'));
    this.apiKey = this.config.getOrThrow<string>('SADASEND_API_KEY');
  }

  async onModuleInit(): Promise<void> {
    await this.boss.start();
    await this.boss.createQueue(`${EMAIL_QUEUE}-dlq`);
    await this.boss.createQueue(EMAIL_QUEUE, {
      retryLimit: 5,
      retryDelay: 2,
      retryBackoff: true, // 2s, 4s, 8s, 16s, 32s
      deadLetter: `${EMAIL_QUEUE}-dlq`,
    });
    await this.boss.work<EmailJobData>(EMAIL_QUEUE, { batchSize: 25 }, async (jobs) => {
      for (const job of jobs) await this.process(job.id, job.data);
    });
  }

  async onModuleDestroy(): Promise<void> {
    await this.boss.stop();
  }

  private async process(jobId: string, data: EmailJobData): Promise<void> {
    const res = await fetch('https://api.sadasend.com/emails', {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json',
        'Idempotency-Key': data.idempotencyKey,
      },
      body: JSON.stringify({ to: data.to, subject: data.subject, html: data.html, text: data.text }),
    });

    if (res.status === 403 || res.status === 422) {
      // A guardrail refused it (allowlist, suppression, undeliverable). Retrying cannot help,
      // so log it and return: the job completes instead of burning five attempts.
      const err = await res.json();
      this.logger.error(`Job ${jobId} refused by SadaSend (${err.error}): ${err.message}`);
      return;
    }

    if (!res.ok) {
      // Transient: throwing hands the job back for an exponential-backoff retry.
      throw new Error(`Upstream delivery failure: ${res.status}`);
    }
  }
}

// In your Auth or Order Service. Pass your transaction's connection as `db` to
// enqueue atomically with the row you are writing: commit and the job exists,
// roll back and it never did.
await this.boss.send(
  EMAIL_QUEUE,
  {
    to: user.email,
    subject: 'Confirm your work email',
    text: `Verify your account: ${verificationUrl}`,
    idempotencyKey: `verify-${user.id}`,
  },
  { singletonKey: `verify-${user.id}` }, // a second enqueue of the same email is a no-op
);