Mailing

Installation

Add the Mailing module and an e-mail provider to an AntelopeJS DMS project.

The Mailing module runs inside a project that loads @antelopejs/dms, a database module and a module implementing @antelopejs/interface-email.

Requirements

Package	Version
`@antelopejs/dms`	`>=0.9.0 <1.0.0`
`@antelopejs/interface-dms`	`>=0.7.0 <1.0.0`
`@antelopejs/dms-frontend` (the renderer)	`0.6`
`@antelopejs/interface-dms-mailing`	`>=0.8.0 <0.9.0`
`@antelopejs/interface-email`	`>=0.0.5 <1.0.0`

Mailing 0.6 runs on DMS 0.9 and renderer 0.6 only. On DMS 0.8, stay on Mailing 0.4 until you upgrade the backend, interface and renderer together: see Upgrading to DMS 0.9. See DMS installation for the toolchain and Troubleshooting for dependency and frontend integration errors.

Add it to a project

Add the module

Terminal

ajs project modules add @antelopejs/dms-mailing

Add an e-mail provider

The module hands every e-mail to the @antelopejs/interface-email implementation of the project. With nodemailer:

Terminal

ajs project modules add @antelopejs/nodemailer

antelope.config.ts

export default defineConfig({
  name: "my-project",
  modules: {
    "dms-mailing": {
      source: { type: "package", package: "@antelopejs/dms-mailing", version: "^0.6.0" },
      config: {},
    },
    nodemailer: {
      source: { type: "package", package: "@antelopejs/nodemailer", version: ">=0.0.5 <1.0.0" },
      config: {
        host: "smtp.example.com",
        port: 587,
        auth: { user: "apikey", pass: process.env.SMTP_PASSWORD },
        defaults: { from: "[email protected]" },
      },
    },
    // dms, api, mongodb, auth-jwt, file-storage-local, ...
  },
});

Use config: { ethereal: true } in development to send to a throwaway Ethereal inbox.

With ethereal: true, @antelopejs/nodemailer creates its Ethereal account over the internet while the project starts. Offline, that request fails, nodemailer's construct() throws, and AntelopeJS stops the whole project before Mailing runs, so Mailing cannot step in. To work offline, point nodemailer at a local SMTP server instead (Mailpit, MailHog, or the playground's SMTP_PORT): { host: "127.0.0.1", port: 1025, secure: false }.

Set the public origin

The webhook URL and the logo in e-mails use the DMS clientBaseUrl, the public origin of the dashboard. Set it in the dms module's config before a real provider has to reach the webhook.

Open the module

Restart the backend and the frontend. The module appears under Modules › Mailing, at /modules/mailing/overview. Until a provider and a template exist, the overview shows a setup checklist.

The pages render on the server: the overview's figures, the template gallery and the settings arrive with the page. Drawers, dialogs, the editor and the preview frames read their data when they open.

Create your first template from a starter: Order confirmation, Shipping update, Password reset and Invoice available come with English and French content, variables and test data.

Try it in the playground

Terminal

pnpm install
pnpm --dir frontend-vue install
pnpm --dir playground install
pnpm dev            # backend on http://localhost:5010
pnpm frontend:dev   # dashboard on http://localhost:3001

Run these in packages/dms-mailing. The playground uses MongoDB at mongodb://localhost:27017 (set MONGO_URL to change it) and sends to Ethereal, or to a local SMTP server when SMTP_PORT is set.

Introduction

Transactional e-mail for the DMS, with a block editor, drafts and versions, a send log and delivery metrics.

Configuration

The module option in antelope.config.ts and every workspace setting of the Settings page.