# nestjs/mail architecture

> Architecture diagram of the GitHub repository nestjs/mail, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nestjs/mail
- Repository: https://github.com/nestjs/mail

## Overview

This is a NestJS mail module: applications submit inline messages or injectable mail classes, which the mailer validates and renders into immutable messages, then delivers through SMTP or an HTTP provider with retries and events. Templates, MIME construction, and provider-specific adapters are distinct capabilities. The README documents the overall feature set; detailed edges are limited to relationships visible in excerpts or the SOURCE INDEX, so unsampled wiring is not inferred.

Main entry points: [`lib/mailer.service.ts`](https://github.com/nestjs/mail/blob/master/lib/mailer.service.ts) (Mailer service), [`lib/transports/http-provider.transport.ts`](https://github.com/nestjs/mail/blob/master/lib/transports/http-provider.transport.ts) (HTTP provider base), [`lib/message/mail-message.ts`](https://github.com/nestjs/mail/blob/master/lib/message/mail-message.ts) (Validated mail message), [`lib/message/normalize.util.ts`](https://github.com/nestjs/mail/blob/master/lib/message/normalize.util.ts) (Message normalization)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_send["Mail workflow"]
  node_mailer["Mailer service<br/>[mailer.service.ts]"]
  node_mailclass["Injectable mail classes"]
  node_module["Mail module setup"]
end

subgraph group_content["Message and templates"]
  node_message["Validated mail message<br/>[mail-message.ts]"]
  node_normalizer["Message normalization<br/>[normalize.util.ts]"]
  node_address["Address parsing<br/>[address.util.ts]"]
  node_headers["Header validation<br/>[headers.util.ts]"]
  node_mime["MIME builder<br/>[mime.util.ts]"]
  node_templateengine["Template engine"]
  node_filetemplate["File template engine"]
  node_compiler["Template compiler"]
end

subgraph group_delivery["Delivery transports"]
  node_transporttoken["Transport contract<br/>[mail.transport.ts]"]
  node_smtp["SMTP transport<br/>[smtp.transport.ts]"]
  node_smtpconnection["SMTP connection<br/>[smtp-connection.ts]"]
  node_httpbase["HTTP provider base"]
  node_resend["Resend transport"]
  node_postmark["Postmark transport"]
  node_sendgrid["SendGrid transport"]
  node_ses["Amazon SES transport<br/>[ses.transport.ts]"]
  node_localtransports["Local transports"]
end

subgraph group_support["Retry and events"]
  node_retry["Retry policy<br/>[retry.util.ts]"]
  node_events["Mail events"]
end

node_application(("Nest application"))
node_provider(("Mail provider APIs"))
node_smtpserver(("SMTP server"))

node_application -->|"configures"| node_module
node_application -->|"sends mail"| node_mailer
node_mailer -->|"resolves and renders"| node_mailclass
node_mailer -->|"normalizes"| node_normalizer
node_normalizer -->|"parses addresses"| node_address
node_normalizer -->|"validates headers"| node_headers
node_mailer -->|"builds"| node_message
node_message -->|"checks internationalization"| node_address
node_message -->|"builds MIME"| node_mime
node_mailer -->|"renders templates"| node_templateengine
node_filetemplate -->|"compiles templates"| node_compiler
node_mailer -->|"dispatches message"| node_transporttoken
node_mailer -->|"applies retries"| node_retry
node_mailer -->|"publishes events"| node_events
node_smtp -->|"uses connection"| node_smtpconnection
node_smtpconnection -.->|"speaks SMTP"| node_smtpserver
node_resend -->|"uses HTTP requests"| node_httpbase
node_postmark -.->|"uses HTTP requests"| node_httpbase
node_sendgrid -.->|"uses HTTP requests"| node_httpbase
node_ses -->|"uses HTTP requests"| node_httpbase
node_httpbase -.->|"sends API request"| node_provider
node_localtransports -.->|"implements alternatives"| node_transporttoken

click node_mailer "https://github.com/nestjs/mail/blob/master/lib/mailer.service.ts"
click node_mailclass "https://github.com/nestjs/mail/blob/master/lib/interfaces/mailable.interface.ts"
click node_module "https://github.com/nestjs/mail/blob/master/lib/mail.module-definition.ts"
click node_message "https://github.com/nestjs/mail/blob/master/lib/message/mail-message.ts"
click node_normalizer "https://github.com/nestjs/mail/blob/master/lib/message/normalize.util.ts"
click node_address "https://github.com/nestjs/mail/blob/master/lib/message/address.util.ts"
click node_headers "https://github.com/nestjs/mail/blob/master/lib/message/headers.util.ts"
click node_mime "https://github.com/nestjs/mail/blob/master/lib/message/mime.util.ts"
click node_templateengine "https://github.com/nestjs/mail/blob/master/lib/templates/mail-template.engine.ts"
click node_filetemplate "https://github.com/nestjs/mail/blob/master/lib/templates/file-template.engine.ts"
click node_compiler "https://github.com/nestjs/mail/blob/master/lib/templates/template-compiler.util.ts"
click node_transporttoken "https://github.com/nestjs/mail/blob/master/lib/transports/mail.transport.ts"
click node_smtp "https://github.com/nestjs/mail/blob/master/lib/smtp/smtp.transport.ts"
click node_smtpconnection "https://github.com/nestjs/mail/blob/master/lib/smtp/smtp-connection.ts"
click node_httpbase "https://github.com/nestjs/mail/blob/master/lib/transports/http-provider.transport.ts"
click node_resend "https://github.com/nestjs/mail/blob/master/lib/transports/resend.transport.ts"
click node_postmark "https://github.com/nestjs/mail/blob/master/lib/transports/postmark.transport.ts"
click node_sendgrid "https://github.com/nestjs/mail/blob/master/lib/transports/sendgrid.transport.ts"
click node_ses "https://github.com/nestjs/mail/blob/master/lib/transports/ses.transport.ts"
click node_localtransports "https://github.com/nestjs/mail/tree/master/lib/transports"
click node_retry "https://github.com/nestjs/mail/blob/master/lib/utils/retry.util.ts"
click node_events "https://github.com/nestjs/mail/blob/master/lib/events/mail-events.service.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_mailer,node_mailclass,node_module toneBlue
class node_message,node_normalizer,node_address,node_headers,node_mime,node_templateengine,node_filetemplate,node_compiler toneAmber
class node_transporttoken,node_smtp,node_smtpconnection,node_httpbase,node_resend,node_postmark,node_sendgrid,node_ses,node_localtransports,node_provider,node_smtpserver toneMint
class node_retry,node_events toneRose
class node_application toneIndigo
```

## Components

### Mail workflow

- [Mailer service](https://github.com/nestjs/mail/blob/master/lib/mailer.service.ts): `lib/mailer.service.ts`
- [Injectable mail classes](https://github.com/nestjs/mail/blob/master/lib/interfaces/mailable.interface.ts): `lib/interfaces/mailable.interface.ts`
- [Mail module setup](https://github.com/nestjs/mail/blob/master/lib/mail.module-definition.ts): `lib/mail.module-definition.ts`

### Message and templates

- [Validated mail message](https://github.com/nestjs/mail/blob/master/lib/message/mail-message.ts): `lib/message/mail-message.ts`
- [Message normalization](https://github.com/nestjs/mail/blob/master/lib/message/normalize.util.ts): `lib/message/normalize.util.ts`
- [Address parsing](https://github.com/nestjs/mail/blob/master/lib/message/address.util.ts): `lib/message/address.util.ts`
- [Header validation](https://github.com/nestjs/mail/blob/master/lib/message/headers.util.ts): `lib/message/headers.util.ts`
- [MIME builder](https://github.com/nestjs/mail/blob/master/lib/message/mime.util.ts): `lib/message/mime.util.ts`
- [Template engine](https://github.com/nestjs/mail/blob/master/lib/templates/mail-template.engine.ts): `lib/templates/mail-template.engine.ts`
- [File template engine](https://github.com/nestjs/mail/blob/master/lib/templates/file-template.engine.ts): `lib/templates/file-template.engine.ts`
- [Template compiler](https://github.com/nestjs/mail/blob/master/lib/templates/template-compiler.util.ts): `lib/templates/template-compiler.util.ts`

### Delivery transports

- [Transport contract](https://github.com/nestjs/mail/blob/master/lib/transports/mail.transport.ts): `lib/transports/mail.transport.ts`
- [SMTP transport](https://github.com/nestjs/mail/blob/master/lib/smtp/smtp.transport.ts): `lib/smtp/smtp.transport.ts`
- [SMTP connection](https://github.com/nestjs/mail/blob/master/lib/smtp/smtp-connection.ts): `lib/smtp/smtp-connection.ts`
- [HTTP provider base](https://github.com/nestjs/mail/blob/master/lib/transports/http-provider.transport.ts): `lib/transports/http-provider.transport.ts`
- [Resend transport](https://github.com/nestjs/mail/blob/master/lib/transports/resend.transport.ts): `lib/transports/resend.transport.ts`
- [Postmark transport](https://github.com/nestjs/mail/blob/master/lib/transports/postmark.transport.ts): `lib/transports/postmark.transport.ts`
- [SendGrid transport](https://github.com/nestjs/mail/blob/master/lib/transports/sendgrid.transport.ts): `lib/transports/sendgrid.transport.ts`
- [Amazon SES transport](https://github.com/nestjs/mail/blob/master/lib/transports/ses.transport.ts): `lib/transports/ses.transport.ts`
- [Local transports](https://github.com/nestjs/mail/tree/master/lib/transports): `lib/transports`

### Retry and events

- [Retry policy](https://github.com/nestjs/mail/blob/master/lib/utils/retry.util.ts): `lib/utils/retry.util.ts`
- [Mail events](https://github.com/nestjs/mail/blob/master/lib/events/mail-events.service.ts): `lib/events/mail-events.service.ts`

### Other components

- **Nest application**
- **Mail provider APIs**
- **SMTP server**

## Connections

- Nest application → Mail module setup: configures (evidence: `README.md`)
- Nest application → Mailer service: sends mail (evidence: `README.md`)
- Mailer service → Injectable mail classes: resolves and renders (evidence: `lib/mailer.service.ts`)
- Mailer service → Message normalization: normalizes (evidence: `lib/mailer.service.ts`)
- Message normalization → Address parsing: parses addresses (evidence: `lib/message/normalize.util.ts`)
- Message normalization → Header validation: validates headers (evidence: `lib/message/normalize.util.ts`)
- Mailer service → Validated mail message: builds (evidence: `lib/mailer.service.ts`)
- Validated mail message → Address parsing: checks internationalization (evidence: `lib/message/mail-message.ts`)
- Validated mail message → MIME builder: builds MIME (evidence: `lib/message/mail-message.ts`)
- Mailer service → Template engine: renders templates (evidence: `lib/mailer.service.ts`)
- File template engine → Template compiler: compiles templates (evidence: `lib/templates/file-template.engine.ts`)
- Mailer service → Transport contract: dispatches message (evidence: `lib/mailer.service.ts`)
- Mailer service → Retry policy: applies retries (evidence: `lib/mailer.service.ts`)
- Mailer service → Mail events: publishes events (evidence: `lib/mailer.service.ts`)
- SMTP transport → SMTP connection: uses connection (evidence: `lib/smtp/smtp.transport.ts`)
- SMTP connection → SMTP server: speaks SMTP (evidence: `README.md`)
- Resend transport → HTTP provider base: uses HTTP requests (evidence: `lib/transports/resend.transport.ts`)
- Postmark transport → HTTP provider base: uses HTTP requests (evidence: `README.md`)
- SendGrid transport → HTTP provider base: uses HTTP requests (evidence: `README.md`)
- Amazon SES transport → HTTP provider base: uses HTTP requests (evidence: `lib/transports/ses.transport.ts`)
- HTTP provider base → Mail provider APIs: sends API request (evidence: `README.md`)
- Local transports → Transport contract: implements alternatives (evidence: `README.md`)
