Docs / Running it yourself
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:
- modules registered in code with
registerExtensions([...]), for bundled builds that cannot look for packages at run time (a Worker, a desktop bundle); - otherwise installed
@onesend/*packages whosepackage.jsonnames a server module:"onesend": { "order": 10, "server": "./node" }(a subpath of the package'sexports; the default export is the extension).ONESEND_EXTENSIONS=offloads 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.