Project setup

1. Clone or copy the source/ directory into your project root.

2. Install server dependencies:

   cd source/server && npm install
   cd source/zone-mta && npm install
   cd source/client && npm install && npm run build
   

3. Configure environment / config files. Mailtrain reads from server/config/ using the config npm package. Create server/config/local.yaml (or local.json) with your overrides:

   {
     "www": {
       "trustedPort": 3000,
       "sandboxPort": 3003,
       "publicPort": 3004,
       "host": "localhost",
       "trustedUrlBase": "http://localhost:3000",
       "sandboxUrlBase": "http://localhost:3003",
       "publicUrlBase": "http://localhost:3004"
     },
     "mysql": {
       "host": "localhost",
       "user": "mailtrain",
       "password": "yourpassword",
       "database": "mailtrain"
     }
   }
   

4. Run database migrations (handled automatically on first start via knex).

5. Start the server:

   cd source/server && node index.js
   

6. (Optional) Wire mvis analytics: ensure mvis/ivis-core submodule is initialized before running node mvis/server/index.js.

Public API

startHTTPServer (server/index.js)

async function startHTTPServer(
  appType: AppType,
  appName: string,
  port: number
): Promise<void>

Builds an Express app for the given AppType (TRUSTED, SANDBOX, or PUBLIC), binds it to the specified port, and handles listen errors with descriptive log messages. Call this once per endpoint type during server bootstrap.

getRouter (server/routes/index.js)

async function getRouter(appType: AppType): Promise<Router>

Returns an async Express router configured for the given app type. For AppType.TRUSTED, it serves the React shell with CSRF token and Mailtrain client config injected as JSON. Use this when mounting the trusted UI endpoint in a custom Express app.

em.on / em.set (mvis/server/index.js via extension-manager)

em.set(key: string, value: any): void
em.on(event: string, handler: (...args: any[]) => Promise<void>): void

Extension manager hooks used by mvis. em.set('app.clientDist', path) overrides the static file serving path. em.on('knex.migrate', ...) registers a migration hook. em.on('app.installAPIRoutes', app => ...) mounts additional route handlers. Use these hooks when extending mvis with custom panels or API routes.

Working examples

Scenario - Starting all three HTTP endpoints

Start trusted, sandbox, and public endpoints in a single process, mirroring server/index.js.

import { AppType } from './source/shared/app';

const config = require('./source/server/lib/config');

async function main() {
  const { startHTTPServer } = require('./source/server/index');
  // Mailtrain's index.js calls these internally; replicate for custom hosting:
  await startHTTPServer(AppType.TRUSTED,  'Trusted',  config.www.trustedPort);
  await startHTTPServer(AppType.SANDBOX,  'Sandbox',  config.www.sandboxPort);
  await startHTTPServer(AppType.PUBLIC,   'Public',   config.www.publicPort);
}

main().catch(err => { console.error(err); process.exit(1); });

Scenario - Mounting the trusted UI router in an existing Express app

import express from 'express';
import { getRouter } from './source/server/routes/index';
import { AppType } from './source/shared/app';

async function attachMailtrainUI(app: express.Application) {
  const router = await getRouter(AppType.TRUSTED);
  // Mount under a sub-path or at root
  app.use('/mailtrain', router);
}

const app = express();
attachMailtrainUI(app).then(() => {
  app.listen(3000, () => console.log('Listening on 3000'));
});

Scenario - Registering custom mvis API routes via extension hooks

// custom-mvis-extension.js
'use strict';

const em = require('./source/mvis/ivis-core/server/lib/extension-manager');
const express = require('express');

em.set(
  'app.clientDist',
  require('path').join(__dirname, 'my-client', 'dist')
);

em.on('app.installAPIRoutes', async (app: any) => {
  const router = express.Router();
  router.get('/custom-health', (_req: any, res: any) => {
    res.json({ status: 'ok' });
  });
  app.use('/api', router);
});

// Must load ivis-core last to trigger all registered hooks
require('./source/mvis/ivis-core/server/index');

File walkthrough

• server/index.js - Main server entrypoint; starts HTTP servers for all three app types, runs services (triggers, importer, VERP, zone-mta), and ensures DB migrations complete.
• server/routes/index.js - Factory returning per-app-type routers; the TRUSTED router injects CSRF tokens and serialized client config into the Handlebars root template.
• mvis/server/index.js - Launches the embedded ivis-core analytics server with Mailtrain-specific migrations and API route extensions wired through the extension manager.
• mvis/test-embed/index.js - Standalone test harness for mvis panel embedding; fetches panel tokens from the mvis API and renders them via Handlebars for manual browser testing.
• zone-mta/index.js - Thin shim that requires the zone-mta npm package, which self-starts using its own config directory (zone-mta/config/).
• client/ - Webpack-built React SPA. Entry point is client/src/root.js; each feature area (campaigns, lists, templates, etc.) is a sub-directory with its own route root.
• shared/ - Isomorphic constants and helpers; shared/app.js exports AppType used across server and client.
• setup/ - Bash automation scripts for CentOS 7 and Ubuntu 18.04 that install Node.js, MySQL, Nginx, and Let's Encrypt certificates.
• locales/ - JSON translation files consumed by i18next on both client and server.
• docs/ - Architecture notes and API documentation.

Common pitfalls and fixes

• MySQL 8 authentication: Node's mysql2 may fail with ER_NOT_SUPPORTED_AUTH_MODE against MySQL 8 default auth plugin. Fix: ALTER USER 'mailtrain'@'localhost' IDENTIFIED WITH mysql_native_password BY 'password';
• Three ports must all be reachable: CSRF and session cookies are scoped per endpoint. Running only the trusted port will cause sandbox iframe editors to fail silently. Fix: always start all three endpoints even in dev.
• Client must be built before server starts: server/lib/client-helpers.js reads the Webpack manifest at startup. Fix: run cd client && npm run build before node server/index.js.
• Zone-MTA config directory: Zone-MTA reads from zone-mta/config/; missing plugins/ or pools/ entries cause silent mail delivery failure. Fix: copy zone-mta/config/example/ to zone-mta/config/ and adjust SMTP credentials.
• mvis ivis-core submodule not initialized: mvis/server/index.js requires ../ivis-core/server/lib/extension-manager which will throw MODULE_NOT_FOUND if the Git submodule was not pulled. Fix: git submodule update --init --recursive.
• klaw-sync on read-only filesystems: server/index.js calls klaw-sync on uploadedFilesDir at startup; if that directory doesn't exist the process exits. Fix: pre-create data/files/, data/uploads/, and data/reports/ directories.

Vibe-coding prompt template

I have purchased the Mailtrain v2 source block. The source is in `./source/` and
the integration guide is in `./source/USAGE.md`.

Upstream platform: Mailtrain v2 (self-hosted newsletter, Node.js + MySQL).

My project is: [describe your project, e.g. "an Express API server on Node 18
with a PostgreSQL primary database that needs newsletter campaign delivery"].

Please integrate Mailtrain v2 into my project step-by-step:
1. Read USAGE.md fully before writing any code.
2. Install all required npm dependencies listed in USAGE.md into my project.
3. Create the necessary config files (`server/config/local.yaml`) for my environment.
4. Mount the Mailtrain trusted-UI router from `source/server/routes/index.js` on
   the path `/newsletters` in my existing Express app.
5. Start the sandbox and public endpoints as child processes or parallel async calls.
6. Ensure Zone-MTA is configured for my SMTP relay (host: [my smtp host]).
7. Show me how to verify the integration by hitting the trusted UI and confirming
   the React shell loads with a valid CSRF token.
Do not invent any imports or APIs; use only what is documented in USAGE.md and
visible in the source files.

License and credit

Mailtrain v2 is released under the GPL-3.0 License (see source/LICENSE). The upstream project is maintained at https://github.com/Mailtrain-org/mailtrain (v2 branch). The embedded ivis-core analytics component carries its own license found at source/mvis/ivis-core/LICENSE.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.