# postalsys/emailengine architecture

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

- Interactive diagram: https://gitdiagram.com/postalsys/emailengine
- Repository: https://github.com/postalsys/emailengine

## Overview

EmailEngine is a headless email API that normalizes IMAP/SMTP, Gmail, and Microsoft Graph accounts behind REST endpoints. The main workflow is an API or hosted-admin request to connect an account, synchronize it through a provider client, persist state in Redis, and expose mail operations and notifications. Sending, webhooks, export, legacy protocol access, and administration are distinct product branches. Edges are limited to relationships supported by the README or SOURCE INDEX; several runtime wiring details were not sampled.

Main entry points: [`lib/account.js`](https://github.com/postalsys/emailengine/blob/master/lib/account.js) (Account Management), [`lib/db.js`](https://github.com/postalsys/emailengine/blob/master/lib/db.js) (Redis Store and Queues), [`lib/api-routes/account-routes.js`](https://github.com/postalsys/emailengine/blob/master/lib/api-routes/account-routes.js) (API Routes), [`lib/api-listener.js`](https://github.com/postalsys/emailengine/blob/master/lib/api-listener.js) (REST API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Interfaces"]
  node_api["REST API<br/>[api-listener.js]"]
  node_api_routes["API Routes<br/>[account-routes.js]"]
  node_admin_ui["Admin Interface<br/>[routes-ui.js]"]
  node_ui_auth["Admin Authentication<br/>[auth-routes.js]"]
end

subgraph group_accounts["Accounts and Sync"]
  node_account["Account Management<br/>[account.js]"]
  node_oauth_apps["OAuth Provider Apps<br/>[oauth2-apps.js]"]
  node_imap_client["IMAP Client<br/>[imap-client.js]"]
  node_gmail_client["Gmail Client<br/>[gmail-client.js]"]
  node_outlook_client["Microsoft Graph Client<br/>[outlook-client.js]"]
end

subgraph group_delivery["Mail Delivery"]
  node_webhooks["Webhook Management<br/>[webhooks.js]"]
  node_webhook_worker["Webhook Delivery Worker<br/>[webhooks.js]"]
  node_submit["SMTP Submission<br/>[submit.js]"]
  node_outbox["Queued Sending<br/>[outbox.js]"]
  node_export["Mail Export<br/>[export.js]"]
end

subgraph group_operations["Operations"]
  node_imap_proxy["IMAP Proxy<br/>[imap-server.js]"]
  node_mcp["MCP Integration<br/>[index.js]"]
  node_metrics["Metrics and Operations"]
end

subgraph group_foundation["Shared Foundation"]
  node_redis[("Redis Store and Queues<br/>[db.js]")]
  node_settings["Settings<br/>[settings.js]"]
  node_schemas["Validation Schemas<br/>[schemas.js]"]
  node_tokens["API Tokens<br/>[tokens.js]"]
end

node_integrator(("API Integrator"))
node_admin(("Administrator"))

node_integrator -->|"calls"| node_api
node_admin -->|"uses"| node_admin_ui
node_api -.->|"routes requests"| node_api_routes
node_admin_ui -.->|"authenticates through"| node_ui_auth
node_api_routes -->|"manages accounts"| node_account
node_account -->|"resolves provider"| node_oauth_apps
node_account -->|"stores account state"| node_redis
node_account -.->|"supports IMAP sync"| node_imap_client
node_account -.->|"supports Gmail sync"| node_gmail_client
node_account -->|"supports Graph sync"| node_outlook_client
node_webhook_worker -->|"loads handlers"| node_webhooks
node_webhooks -->|"stores routes"| node_redis
node_outbox -.->|"queues delivery"| node_redis
node_submit -.->|"processes queued mail"| node_outbox
node_export -.->|"uses export queue"| node_redis
node_imap_proxy -.->|"accesses mail accounts"| node_account
node_mcp -.->|"uses API tokens"| node_tokens
node_settings -->|"reads and writes"| node_redis
node_tokens -->|"stores tokens"| node_redis
node_api_routes -->|"validates requests"| node_schemas

click node_api "https://github.com/postalsys/emailengine/blob/master/lib/api-listener.js"
click node_api_routes "https://github.com/postalsys/emailengine/blob/master/lib/api-routes/account-routes.js"
click node_admin_ui "https://github.com/postalsys/emailengine/blob/master/lib/routes-ui.js"
click node_ui_auth "https://github.com/postalsys/emailengine/blob/master/lib/ui-routes/auth-routes.js"
click node_account "https://github.com/postalsys/emailengine/blob/master/lib/account.js"
click node_oauth_apps "https://github.com/postalsys/emailengine/blob/master/lib/oauth2-apps.js"
click node_imap_client "https://github.com/postalsys/emailengine/blob/master/lib/email-client/imap-client.js"
click node_gmail_client "https://github.com/postalsys/emailengine/blob/master/lib/email-client/gmail-client.js"
click node_outlook_client "https://github.com/postalsys/emailengine/blob/master/lib/email-client/outlook-client.js"
click node_webhooks "https://github.com/postalsys/emailengine/blob/master/lib/webhooks.js"
click node_webhook_worker "https://github.com/postalsys/emailengine/blob/master/workers/webhooks.js"
click node_submit "https://github.com/postalsys/emailengine/blob/master/workers/submit.js"
click node_outbox "https://github.com/postalsys/emailengine/blob/master/lib/outbox.js"
click node_export "https://github.com/postalsys/emailengine/blob/master/lib/export.js"
click node_imap_proxy "https://github.com/postalsys/emailengine/blob/master/lib/imapproxy/imap-server.js"
click node_mcp "https://github.com/postalsys/emailengine/blob/master/lib/mcp/index.js"
click node_redis "https://github.com/postalsys/emailengine/blob/master/lib/db.js"
click node_settings "https://github.com/postalsys/emailengine/blob/master/lib/settings.js"
click node_schemas "https://github.com/postalsys/emailengine/blob/master/lib/schemas.js"
click node_tokens "https://github.com/postalsys/emailengine/blob/master/lib/tokens.js"
click node_metrics "https://github.com/postalsys/emailengine/blob/master/lib/metrics-collector.js"

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_api,node_api_routes,node_admin_ui,node_ui_auth toneBlue
class node_account,node_oauth_apps,node_imap_client,node_gmail_client,node_outlook_client toneAmber
class node_webhooks,node_webhook_worker,node_submit,node_outbox,node_export,node_integrator toneMint
class node_imap_proxy,node_mcp,node_metrics toneRose
class node_redis,node_settings,node_schemas,node_tokens,node_admin toneIndigo
```

## Components

### Interfaces

- [REST API](https://github.com/postalsys/emailengine/blob/master/lib/api-listener.js): `lib/api-listener.js`
- [API Routes](https://github.com/postalsys/emailengine/blob/master/lib/api-routes/account-routes.js): `lib/api-routes/account-routes.js`
- [Admin Interface](https://github.com/postalsys/emailengine/blob/master/lib/routes-ui.js): `lib/routes-ui.js`
- [Admin Authentication](https://github.com/postalsys/emailengine/blob/master/lib/ui-routes/auth-routes.js): `lib/ui-routes/auth-routes.js`

### Accounts and Sync

- [Account Management](https://github.com/postalsys/emailengine/blob/master/lib/account.js): `lib/account.js`
- [OAuth Provider Apps](https://github.com/postalsys/emailengine/blob/master/lib/oauth2-apps.js): `lib/oauth2-apps.js`
- [IMAP Client](https://github.com/postalsys/emailengine/blob/master/lib/email-client/imap-client.js): `lib/email-client/imap-client.js`
- [Gmail Client](https://github.com/postalsys/emailengine/blob/master/lib/email-client/gmail-client.js): `lib/email-client/gmail-client.js`
- [Microsoft Graph Client](https://github.com/postalsys/emailengine/blob/master/lib/email-client/outlook-client.js): `lib/email-client/outlook-client.js`

### Mail Delivery

- [Webhook Management](https://github.com/postalsys/emailengine/blob/master/lib/webhooks.js): `lib/webhooks.js`
- [Webhook Delivery Worker](https://github.com/postalsys/emailengine/blob/master/workers/webhooks.js): `workers/webhooks.js`
- [SMTP Submission](https://github.com/postalsys/emailengine/blob/master/workers/submit.js): `workers/submit.js`
- [Queued Sending](https://github.com/postalsys/emailengine/blob/master/lib/outbox.js): `lib/outbox.js`
- [Mail Export](https://github.com/postalsys/emailengine/blob/master/lib/export.js): `lib/export.js`

### Operations

- [IMAP Proxy](https://github.com/postalsys/emailengine/blob/master/lib/imapproxy/imap-server.js): `lib/imapproxy/imap-server.js`
- [MCP Integration](https://github.com/postalsys/emailengine/blob/master/lib/mcp/index.js): `lib/mcp/index.js`
- [Metrics and Operations](https://github.com/postalsys/emailengine/blob/master/lib/metrics-collector.js): `lib/metrics-collector.js`

### Shared Foundation

- [Redis Store and Queues](https://github.com/postalsys/emailengine/blob/master/lib/db.js): `lib/db.js`
- [Settings](https://github.com/postalsys/emailengine/blob/master/lib/settings.js): `lib/settings.js`
- [Validation Schemas](https://github.com/postalsys/emailengine/blob/master/lib/schemas.js): `lib/schemas.js`
- [API Tokens](https://github.com/postalsys/emailengine/blob/master/lib/tokens.js): `lib/tokens.js`

### Other components

- **API Integrator**
- **Administrator**

## Connections

- API Integrator → REST API: calls (evidence: `README.md`)
- Administrator → Admin Interface: uses (evidence: `README.md`)
- REST API → API Routes: routes requests
- Admin Interface → Admin Authentication: authenticates through (evidence: `lib/routes-ui.js`)
- API Routes → Account Management: manages accounts (evidence: `lib/api-routes/account-routes.js`)
- Account Management → OAuth Provider Apps: resolves provider (evidence: `lib/account.js`)
- Account Management → Redis Store and Queues: stores account state (evidence: `lib/account.js`)
- Account Management → IMAP Client: supports IMAP sync
- Account Management → Gmail Client: supports Gmail sync
- Account Management → Microsoft Graph Client: supports Graph sync (evidence: `lib/email-client/outlook-client.js`)
- Webhook Delivery Worker → Webhook Management: loads handlers (evidence: `workers/webhooks.js`)
- Webhook Management → Redis Store and Queues: stores routes (evidence: `lib/webhooks.js`)
- Queued Sending → Redis Store and Queues: queues delivery
- SMTP Submission → Queued Sending: processes queued mail
- Mail Export → Redis Store and Queues: uses export queue
- IMAP Proxy → Account Management: accesses mail accounts
- MCP Integration → API Tokens: uses API tokens
- Settings → Redis Store and Queues: reads and writes (evidence: `lib/settings.js`)
- API Tokens → Redis Store and Queues: stores tokens (evidence: `lib/tokens.js`)
- API Routes → Validation Schemas: validates requests (evidence: `lib/api-routes/account-routes.js`)
