@breadstone/archipel-platform-mailing

Multi-strategy email delivery for NestJS with support for SMTP, Postmark, Resend, SendGrid, and Mailgun.

Features

• Multi-provider — Switch between SMTP, Postmark, Resend, SendGrid, or Mailgun via config
• Subpath imports — Each provider lives in its own subpath — install only the SDK you need
• Template engines — File-based or blob-based template fetching with variable substitution
• Health checks — MailHealthIndicator for readiness probes (separate /health subpath)
• SMTP connection verification — SmtpConnectionVerifier for verifying SMTP server reachability and sending test emails
• Attachment support — Send file attachments with MIME-type validation and size limits (25 MB max)
• Header injection prevention — Subject lines are automatically sanitized against SMTP header injection

Deprecation notice: MailVerificationService is deprecated. Use SmtpConnectionVerifier instead — it provides verifyConnection() and sendTestEmail() methods.

⚠️ Environment Variables

Core mailing configuration

| Variable | Required | Default | Description | | ----------------------------- | -------- | ------- | ------------------------------------------------ | | MAIL_TEMPLATE_STRATEGY | yes | - | Template fetch strategy (file or blob) | | MAIL_DELIVERY_STRATEGY | yes | - | Delivery strategy (log, smtp, or postmark) | | MAIL_SENDER_EMAIL | yes | - | Sender address for the From header | | MAIL_TEMPLATE_ENGINE_FORMAT | yes | - | Template engine format identifier |

Postmark provider

| Variable | Required | Default | Description | | ----------------------- | ------------------------------------------ | ------- | ---------------- | | MAIL_POSTMARK_API_KEY | yes when MAIL_DELIVERY_STRATEGY=postmark | - | Postmark API key |

SMTP provider

| Variable | Required | Default | Description | | -------------------- | -------- | ----------- | --------------------- | | MAIL_SMTP_HOST | no | localhost | SMTP host | | MAIL_SMTP_PORT | no | 587 | SMTP port | | MAIL_SMTP_SECURE | no | false | Use secure SMTP (TLS) | | MAIL_SMTP_USER | no | '' | SMTP username | | MAIL_SMTP_PASSWORD | no | '' | SMTP password |

Health indicator

| Variable | Required | Default | Description | | ----------- | -------- | ------- | ---------------------- | | MAIL_HOST | no | '' | Health-check mail host | | MAIL_USER | no | '' | Health-check mail user | | MAIL_PORT | no | 0 | Health-check mail port |

Quick Start

import { Module } from '@nestjs/common';
import { MailModule } from '@breadstone/archipel-platform-mailing';

@Module({
  imports: [MailModule],
})
export class AppModule {}

Set MAIL_DELIVERY_STRATEGY to one of: smtp, postmark, resend, sendgrid, mailgun, log.

Supported Providers

| Subpath | Class | SDK | | ------------------------------------------------ | -------------------------- | ---------------- | | @breadstone/archipel-platform-mailing/postmark | PostmarkDeliveryStrategy | postmark | | @breadstone/archipel-platform-mailing/resend | ResendDeliveryStrategy | resend | | @breadstone/archipel-platform-mailing/sendgrid | SendGridDeliveryStrategy | @sendgrid/mail | | @breadstone/archipel-platform-mailing/mailgun | MailgunDeliveryStrategy | mailgun.js |

SMTP and Log strategies are built-in (no external SDK required).

Import Options

// Main import (module, service)
import { MailModule, MailService } from '@breadstone/archipel-platform-mailing';

// Built-in strategies
import { SmtpDeliveryStrategy } from '@breadstone/archipel-platform-mailing/smtp';
import { LogDeliveryStrategy } from '@breadstone/archipel-platform-mailing/log';

// Provider-specific (tree-shakable sub-exports)
import { PostmarkDeliveryStrategy, POSTMARK_CONFIG_ENTRIES } from '@breadstone/archipel-platform-mailing/postmark';
import { ResendDeliveryStrategy } from '@breadstone/archipel-platform-mailing/resend';
import { SendGridDeliveryStrategy } from '@breadstone/archipel-platform-mailing/sendgrid';
import { MailgunDeliveryStrategy } from '@breadstone/archipel-platform-mailing/mailgun';

// Health indicator (optional)
import { MailHealthIndicator } from '@breadstone/archipel-platform-mailing/health';

Error Handling

| Error Class | Code | When Thrown | | ------------------- | --------------- | ----------------------------------- | | MailDeliveryError | MAIL_DELIVERY | Provider SDK failure during sending |

Lifecycle

• Startup (OnModuleInit): MailTemplateEngine preloads and compiles templates.
• Shutdown (OnModuleDestroy): MailEventSubscriber unsubscribes from event streams.

Peer Dependencies

| Package | Required | Notes | | --------------------------------------------- | -------- | ------------------------------ | | @breadstone/archipel-platform-configuration | Yes | Typed config key support | | @nestjs/common | Yes | NestJS core | | nodemailer | No | Required for SMTP strategy | | postmark | No | Required for Postmark provider | | resend | No | Required for Resend provider | | @sendgrid/mail | No | Required for SendGrid provider | | mailgun.js | No | Required for Mailgun provider | | @breadstone/archipel-platform-health | No | Required for health indicator | | @nestjs/terminus | No | Required for health indicator |

Documentation

📖 Package Docs: .docs/packages/platform-mailing/index.md

Development

# Build
yarn nx build platform-mailing

# Test
yarn nx test platform-mailing

# Lint
yarn nx lint platform-mailing