@antelopejs/interface-dms-mailing

The AntelopeJS interface to send DMS mailing templates and report e-mail events from any module.

What it does

• Sends a published template by its slug, to one recipient or many, in a given locale and with its variables (SendTemplate).
• Reports a provider event (delivered, opened, clicked, bounced…) against the send it belongs to (RecordEmailEvent).
• Ships templates and template categories as code when a workspace is provisioned (DeclareTemplate, DeclareTemplateCategory). A declaration writes once: a template is created already published, and a slug or category id the workspace already has is left as it is.
• Writes the workspace sender when a workspace is provisioned (DeclareSender).
• Sets the workspace webhook secret from code, keeping one the workspace owner set or rotated (DeclareWebhookSecret).
• Imports past sends and their events with their own dates, for a demo data set or a move from another provider (ImportSends).
• Exports the template and send types (Block, TemplateContent, VariableDefinition, SendStatus, EmailEvent…) for code that builds or inspects templates.
• Keeps your module independent of the implementation, @antelopejs/dms-mailing.

Install

Add the interface to the module that sends e-mails:

pnpm add @antelopejs/interface-dms-mailing

Quick start

import { RecordEmailEvent, SendTemplate } from "@antelopejs/interface-dms-mailing";

const result = await SendTemplate("order-confirmed", {
  tenantId,
  to: [{ email: "[email protected]", name: "Sofie" }],
  locale: "fr",
  variables: {
    customer: { firstName: "Sofie" },
    order: {
      number: "#10482",
      total: { value: 4800, currency: "EUR" },
      lines: [{ name: "Linen shirt", total: { value: 4800, currency: "EUR" } }],
      url: "https://example.com/orders/10482",
    },
  },
  source: "checkout",
});

await RecordEmailEvent(tenantId, {
  provider: "brevo",
  messageId,
  type: "bounced",
  details: { reason: "mailbox full" },
});

A recipient on the workspace's suppression list gets no e-mail, and its result has the status suppressed. A template whose footer links to an unsubscribe page or a preferences page reads their URLs from unsubscribeUrl and preferencesUrl in variables.

Compatibility

A @antelopejs/dms-mailing release implements one minor line of this interface. The @antelopejs/interface-dms-mailing row of the compatibility block in the module README gives that range. Use a module release whose range covers the interface release your code imports. DeclareTemplate, DeclareTemplateCategory, DeclareSender, DeclareWebhookSecret and ImportSends each take an explicit tenantId. The interface declares these dependencies:

| Package | Supported | Tested with | | ----------------------------- | ---------------- | ----------- | | @antelopejs/interface-core | >=0.4.0 <1.0.0 | 0.4.0 | | @antelopejs/interface-email | >=0.0.6 <1.0.0 | 0.0.6 |

Documentation

• Consumer reference: signatures, results, failures, tenant boundaries and template types
• Extending the mailing module: sending from code, what a recipient receives, provider webhooks, automations
• Mailing module guide

Contributing

This package lives in the AntelopeJS/dms-mailing pnpm workspace, next to the module that implements it. Read CONTRIBUTING.md and the repository README for the development commands. Release this package before the module that implements it.

License

Apache-2.0