Skip to main content

Concern

Sending transactional email (mailing).

Technology

Mailgun via mailgun.js (official JavaScript SDK).

Documentation​

Version

v12 (pin to latest major).

Implementation

The boilerplate implements mailing via MailingModule in backend/src/mailing/. An abstract MailingService exposes sendEmail(options: SendEmailOptions): Promise<void>. Two implementations:

  • MailgunMailingService — Sends email through Mailgun using mailgun.js; configured via MAILGUN_API_KEY, MAILGUN_API_URL, MAILGUN_DOMAIN, and MAILGUN_FROM_EMAIL.
  • LocalMailingService — Writes each email to the monorepo root directory mails/ (gitignored) for local development: per-email subdirectory with email.html, metadata.json, and optional attachments/ subdirectory.

The active implementation is selected by MAILING_TYPE in app config (local or mailgun). In non-development environments (acceptance/production), MAILING_TYPE must not be local (enforced at bootstrap). See backend configuration for env schema and validation.

Integration

configuration​

Env schema and validation define MAILING_TYPE and Mailgun env vars; refinement requires non-local mailing type when ENVIRONMENT is acceptance or production.

service-layer​

Other modules inject MailingService and call sendEmail for transactional mail (e.g. magic links, notifications).

Configuration

Environment variables​

  • MAILING_TYPE — local or mailgun. Default local. Run-time. In acceptance/production, must not be local (validation fails at startup).
  • MAILGUN_API_KEY — Mailgun API key. Required when MAILING_TYPE is mailgun. Run-time.
  • MAILGUN_API_URL — Mailgun API base URL. Default https://api.eu.mailgun.net. Run-time.
  • MAILGUN_DOMAIN — Sending domain. Required when MAILING_TYPE is mailgun. Run-time.
  • MAILGUN_FROM_EMAIL — From address. Defaults to noreply@${MAILGUN_DOMAIN} when unset. Run-time.

Dev uses MAILING_TYPE=local and the mails/ directory at monorepo root; deployed apps set MAILING_TYPE=mailgun and Mailgun env vars (e.g. via GitLab CI/CD variables).