---
title: "Extensions"
description: "OneSend can load optional modules that add features to the server, the dashboard and the MCP server."
url: https://onesend.email/docs/architecture/extensions/
---
# Extensions

OneSend can load optional modules that add features to the server, the dashboard and the MCP server. This
edition runs without any: a feature whose module is not installed is off, and `GET /v1/auth/me` says so in
`capabilities` (for example `inbox: false` and `connectedAccounts: false`). Core code never imports a module;
it calls extension points that do nothing when no module implements them.

## Server

`apps/server/src/extensions.ts` defines `ServerExtension` and loads the modules:

1. modules registered in code with `registerExtensions([...])`, for bundled builds that cannot look for
   packages at run time (a Worker, a desktop bundle);
2. otherwise installed `@onesend/*` packages whose `package.json` names a server module:
   `"onesend": { "order": 10, "server": "./node" }` (a subpath of the package's `exports`; the default
   export is the extension). `ONESEND_EXTENSIONS=off` loads none; `ONESEND_EXTENSIONS=<pkg>,<pkg>` only those.

`boot()` (`src/node/boot.ts`) loads them after the migrations and keeps them in `deps.extensions`.

| Extension point | Called from | What it does |
|---|---|---|
| `middleware(app, deps)` | `app.ts` | Guards mounted before every route |
| `routes(app, deps)` | `app.ts` | Routes, mounted after the core routes |
| `publicCors`, `openapiTags` | `app.ts` | CORS for public endpoints; OpenAPI tags, placed after a named tag |
| `jobs(deps)` | `worker.ts` | Job handlers, merged into `jobHandlers` (a core kind stays the core's) |
| `startup`, `maintenance`, `onDeadJob` | `worker.ts` | Periodic jobs at worker start, hourly housekeeping, a job that gave up |
| `boot(deps)` | `node/boot.ts` | Startup work after migrations, on every runtime |
| `secrets(deps, { rotating })` | `node/boot.ts` | Encrypted columns re-encrypted on key rotation |
| `listen(deps)` → `{ close() }` | `index.ts` (Node only) | Listeners, started after the HTTP server, closed on shutdown |
| `shutdown()` | `index.ts` | Cleanup on SIGINT/SIGTERM |
| `capabilities(deps, auth)` | `routes/auth.ts` | Turns features on in `GET /v1/auth/me` |
| `providers` | `node/boot.ts` | Sending adapters registered into the provider registry (`registerAdapter`, optionally before another one) |
| `gallery.host(deps)`, `gallery.link(deps, workspaceId)` | `services/gallery` | Host the template gallery from this server's database (its routes become the public gallery API); the cloud account a workspace submits templates through |
| `connectionAllowed(...)` | `routes/connections.ts` | Refuse creating or resuming a sending connection (plan limits, gating) |
| `send.validate`, `send.remoteTemplate` | `services/send.ts` | Checks before a send is created; templates rendered by another service (`<prefix><id>`) |
| `send.validateBatch`, `send.canSendLive` | `extensions.ts` (`validateBatchSend`, `liveSendProblem`) | Checks of a whole batch before any item is queued (the cloud's monthly emails); whether a workspace can send live email now (campaigns, automations, the worker) |
| `send.created` | `services/send.ts` | A new email was created (not an idempotent replay; sandboxed ones too); errors are logged and never fail the send. The cloud counts live emails toward the monthly limit here |
| `gdpr.deletionRequested`, `gdpr.deletionCanceled` | `services/gdpr/purge.ts` | Work when a workspace deletion is requested or canceled. Export and purge of rows cover every table of the shared schema already |
| `ai.visibleRows`, `ai.withBodies`, `ai.hiddenAccountIds` | `ai/context.ts` | What the AI assistant may read of received mail |
| `mcp(deps)`, `mcpWatcher(...)` | `routes/mcp-remote.ts` | MCP tools, resources and prompts for `/mcp`, and subscriptions |
| `smtpLogin` | `node/smtp.ts` | Other sign-ins to the SMTP submission server |
| `admin`, `doctor` | `node/admin.ts`, `cli/doctor.ts` | `onesend-admin` commands and `npm run doctor` checks |
| `cloudflareEmail(...)` | `apps/worker-cf/src/email.ts` | The Worker's `email()` handler (without one, mail is refused) |

The database schema, the migrations and the `Store` (`packages/core`) are shared by every build, so tables used
only by a module exist here too and stay empty.

## Dashboard

`apps/web/src/extensions.ts` defines `WebExtension`. The packages the build includes are listed in
`src/extensions.installed.ts` (none here); Vite and TypeScript resolve each package or an empty stub
(`vite.extensions.ts`, `tsconfig.extensions.json`). A package's default export has its id, its translation
catalogs and `load()`, which brings in the rest before the app renders (`main.tsx`).

| Extension point | Used by |
|---|---|
| `routes`, `pages` | `app/App.tsx`: routes inside the dashboard layout; pages outside it (signed in unless public) |
| `useNav` | `app/nav.tsx`: pages of a navigation area (home, sending, marketing, inbox, developers, settings: an icon in the rail, the pages in the sidebar), each after a named entry |
| `useSettingsSections` | `pages/Settings.tsx`: tabs (a hidden tab still opens with `?tab=`) |
| `layout` | `app/App.tsx`: replaces the whole signed-in dashboard while active |
| `homeCards`, `domainCards` | `pages/Dashboard.tsx`, `pages/Domains.tsx` |
| `useCommands` | `app/CommandPalette.tsx`: "Go to" entries |
| `useAiSettingsSections` | `features/ai/AiSettingsPanel.tsx`: inbox-side sections of Settings → AI |
| `accountEmailDialog` | `pages/Account.tsx` |
| `slots` | `Slot` in the Shell (banner, page gate), the providers page and pages of features this server does not offer |
| `fullBleed`, `mock`, `prepare`, `devSetup` | the Shell's padding; demo mode (`VITE_DEMO=1`); development only |

Translations: each package has its own `locales/*.json` (the same 11 languages), merged at run time
(`src/i18n/index.tsx`). `npm run i18n:check -w @onesend/web` checks the dashboard's catalogs and those of every
installed package (`"onesend": { "web": ".", "locales": "./locales" }`); a key belongs to one catalog set.

## MCP server

`apps/mcp/src/server.ts` defines `McpExtension` (tools, instructions, resources and prompts, a watcher for
subscriptions, and `available(capabilities)`). The standalone server loads installed packages with an
`"onesend": { "mcp": "./mcp" }` entry (`src/extensions.ts`) and offers those the OneSend server's
capabilities allow. The server's own `/mcp` endpoint uses `ServerExtension.mcp`.
