@antelopejs/interface-dms-mailing 0.5.0 → 0.7.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +49 -19
- package/dist/index.d.ts +1 -1
- package/docs/1.index.md +131 -0
- package/docs/tsconfig.json +10 -0
- package/package.json +17 -5
package/README.md
CHANGED
|
@@ -1,23 +1,36 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
1
3
|
# @antelopejs/interface-dms-mailing
|
|
2
4
|
|
|
3
|
-
<
|
|
4
|
-
<a href="./LICENSE"><img alt="License" src="https://img.shields.io/
|
|
5
|
-
<a href="https://discord.gg/sjK28QHrA7"><img src="https://img.shields.io/badge/Discord-18181B?logo=discord&style=for-the-badge&color=000000"
|
|
6
|
-
<a href="https://antelopejs.com"><img src="https://img.shields.io/badge/Docs-18181B?style=for-the-badge&color=000000"
|
|
5
|
+
<a href="https://www.npmjs.com/package/@antelopejs/interface-dms-mailing"><img alt="npm" src="https://img.shields.io/npm/v/@antelopejs/interface-dms-mailing?style=for-the-badge&labelColor=000000&color=000000"></a>
|
|
6
|
+
<a href="./LICENSE"><img alt="License" src="https://img.shields.io/npm/l/@antelopejs/interface-dms-mailing?style=for-the-badge&labelColor=000000&color=000000"></a>
|
|
7
|
+
<a href="https://discord.gg/sjK28QHrA7"><img alt="Discord" src="https://img.shields.io/badge/Discord-18181B?logo=discord&style=for-the-badge&color=000000"></a>
|
|
8
|
+
<a href="https://dms.antelopejs.com/docs/modules/mailing/extending"><img alt="Documentation" src="https://img.shields.io/badge/Docs-18181B?style=for-the-badge&color=000000"></a>
|
|
9
|
+
|
|
10
|
+
The AntelopeJS interface to send DMS mailing templates and report e-mail events from any module.
|
|
11
|
+
|
|
7
12
|
</div>
|
|
8
13
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
14
|
+
## What it does
|
|
15
|
+
|
|
16
|
+
- Sends a published template by its slug, to one recipient or many, in a given locale and with its variables (`SendTemplate`).
|
|
17
|
+
- Reports a provider event (delivered, opened, clicked, bounced…) against the send it belongs to (`RecordEmailEvent`).
|
|
18
|
+
- Exports the template and send types (`Block`, `TemplateContent`, `VariableDefinition`, `SendStatus`, `EmailEvent`…) for code that builds or inspects templates.
|
|
19
|
+
- Keeps your module independent of the implementation, [`@antelopejs/dms-mailing`](https://www.npmjs.com/package/@antelopejs/dms-mailing).
|
|
20
|
+
|
|
21
|
+
## Install
|
|
22
|
+
|
|
23
|
+
Add the interface to the module that sends e-mails:
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
pnpm add @antelopejs/interface-dms-mailing
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
## Quick start
|
|
13
30
|
|
|
14
31
|
```ts
|
|
15
|
-
import {
|
|
16
|
-
RecordEmailEvent,
|
|
17
|
-
SendTemplate,
|
|
18
|
-
} from "@antelopejs/interface-dms-mailing";
|
|
32
|
+
import { RecordEmailEvent, SendTemplate } from "@antelopejs/interface-dms-mailing";
|
|
19
33
|
|
|
20
|
-
// Render a live template and send it.
|
|
21
34
|
const result = await SendTemplate("order-confirmation", {
|
|
22
35
|
tenantId,
|
|
23
36
|
to: [{ email: "sofie@example.com", name: "Sofie" }],
|
|
@@ -26,7 +39,6 @@ const result = await SendTemplate("order-confirmation", {
|
|
|
26
39
|
source: "checkout",
|
|
27
40
|
});
|
|
28
41
|
|
|
29
|
-
// Report a provider event against the send it belongs to.
|
|
30
42
|
await RecordEmailEvent(tenantId, {
|
|
31
43
|
provider: "brevo",
|
|
32
44
|
messageId,
|
|
@@ -35,11 +47,29 @@ await RecordEmailEvent(tenantId, {
|
|
|
35
47
|
});
|
|
36
48
|
```
|
|
37
49
|
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
50
|
+
A recipient on the workspace's suppression list gets no e-mail: its result has the status `suppressed`. A template whose footer links to an unsubscribe or a preferences page expects `unsubscribeUrl` / `preferencesUrl` in `variables`.
|
|
51
|
+
|
|
52
|
+
## Compatibility
|
|
53
|
+
|
|
54
|
+
The implementation is `@antelopejs/dms-mailing >=0.5.0`. The interface declares these dependencies:
|
|
55
|
+
|
|
56
|
+
<!-- docs-compat: ./package.json#dependencies -->
|
|
57
|
+
|
|
58
|
+
| Package | Range |
|
|
59
|
+
| --- | --- |
|
|
60
|
+
| `@antelopejs/interface-core` | `>=0.2.4 <1.0.0` |
|
|
61
|
+
| `@antelopejs/interface-email` | `>=0.0.6 <1.0.0` |
|
|
62
|
+
|
|
63
|
+
## Documentation
|
|
64
|
+
|
|
65
|
+
- [Consumer reference](./docs/1.index.md): signatures, results, failures, tenant boundaries and template types
|
|
66
|
+
- [Extending the mailing module](https://dms.antelopejs.com/docs/modules/mailing/extending): sending from code, what a recipient receives, provider webhooks, automations
|
|
67
|
+
- [Mailing module guide](https://dms.antelopejs.com/docs/modules/mailing)
|
|
68
|
+
|
|
69
|
+
## Contributing
|
|
70
|
+
|
|
71
|
+
This package lives in the [`AntelopeJS/dms-mailing`](https://github.com/AntelopeJS/dms-mailing) pnpm workspace, next to the module that implements it. Read [CONTRIBUTING.md](https://github.com/AntelopeJS/dms-mailing/blob/main/CONTRIBUTING.md) and the [repository README](https://github.com/AntelopeJS/dms-mailing#contributing) for the development commands. Release this package before the module that implements it.
|
|
42
72
|
|
|
43
73
|
## License
|
|
44
74
|
|
|
45
|
-
Apache-2.0
|
|
75
|
+
[Apache-2.0](./LICENSE)
|
package/dist/index.d.ts
CHANGED
|
@@ -103,6 +103,6 @@ export interface EmailEvent {
|
|
|
103
103
|
details?: Record<string, unknown>;
|
|
104
104
|
}
|
|
105
105
|
export type SendEventType = "queued" | "sent" | "delivered" | "opened" | "clicked" | "bounced" | "spam" | "failed" | "unsubscribed";
|
|
106
|
-
export type SendStatus =
|
|
106
|
+
export type SendStatus = SendEventType | "suppressed";
|
|
107
107
|
export declare const SendTemplate: (slug: string, params: SendTemplateParams) => Promise<SendTemplateResult>;
|
|
108
108
|
export declare const RecordEmailEvent: (tenantId: string, event: EmailEvent) => Promise<boolean>;
|
package/docs/1.index.md
ADDED
|
@@ -0,0 +1,131 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Mailing interface
|
|
3
|
+
description: Consumer contract for sending templates and recording provider events with the DMS mailing interface.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Mailing interface
|
|
7
|
+
|
|
8
|
+
`@antelopejs/interface-dms-mailing` exposes two backend functions and the template types below. Load `@antelopejs/dms-mailing` and an `@antelopejs/interface-email` provider before calling them. Import from the interface package, not the runtime module's services.
|
|
9
|
+
|
|
10
|
+
Both calls use an explicit `tenantId`. They are trusted backend calls, not permission-checked HTTP endpoints: authenticate and authorize the tenant in the calling module. A missing implementation or a storage failure can reject the promise.
|
|
11
|
+
|
|
12
|
+
## SendTemplate
|
|
13
|
+
|
|
14
|
+
```ts [Contract]
|
|
15
|
+
import type { EmailAddress } from "@antelopejs/interface-email";
|
|
16
|
+
import type { SendStatus, TemplateContent } from "@antelopejs/interface-dms-mailing";
|
|
17
|
+
|
|
18
|
+
interface SendTemplateParams {
|
|
19
|
+
tenantId: string;
|
|
20
|
+
to: EmailAddress | EmailAddress[];
|
|
21
|
+
locale?: string;
|
|
22
|
+
variables?: Record<string, unknown>;
|
|
23
|
+
content?: TemplateContent;
|
|
24
|
+
source?: string;
|
|
25
|
+
isTest?: boolean;
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
interface SendTemplateResult {
|
|
29
|
+
sendId: string;
|
|
30
|
+
status: SendStatus;
|
|
31
|
+
messageId?: string;
|
|
32
|
+
error?: string;
|
|
33
|
+
results?: SendTemplateResult[];
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
declare function SendTemplate(
|
|
37
|
+
slug: string,
|
|
38
|
+
params: SendTemplateParams,
|
|
39
|
+
): Promise<SendTemplateResult>;
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
`to` accepts an address string or `{ email: string, name?: string }`, or an array of either. The slug resolves within the specified tenant. The template must exist even when `content` overrides its body; a non-test send requires a live template. `content` does not publish or save the override. The locale falls back through the workspace's fallback locale and available content. `source` labels the send log.
|
|
43
|
+
|
|
44
|
+
The module renders HTML and plain text, uses batch delivery when the provider supports it, and attempts to log one row per recipient. `isTest` marks the send as a test, prefixes its subject, permits a non-live template, and excludes it from production metrics. It does not bypass the suppression list.
|
|
45
|
+
|
|
46
|
+
### Results and failures
|
|
47
|
+
|
|
48
|
+
For multiple recipients, **the top-level result describes the whole call**, not just the first recipient:
|
|
49
|
+
|
|
50
|
+
- `sendId` and `messageId` belong to the first recipient.
|
|
51
|
+
- `status` is the worst outcome: from best to worst, `clicked`, `opened`, `delivered`, `sent`, `queued`, `unsubscribed`, `suppressed`, `spam`, `bounced`, `failed`.
|
|
52
|
+
- `error` is the first nonempty error in recipient order, not necessarily the error of the recipient with the worst status.
|
|
53
|
+
- `results` contains one result per recipient in input order. Those entries do not contain nested `results`. The type makes this field optional; the current implementation includes it even for a single recipient.
|
|
54
|
+
|
|
55
|
+
A suppressed address receives no email. Its result has `status: "suppressed"` and an error key beginning with `$dms_mailing.errors.suppressed.`, followed by `hard_bounce`, `complaint`, `unsubscribe`, or `manual`. Do not retry suppressed recipients.
|
|
56
|
+
|
|
57
|
+
Provider failures become failed recipient results. If recording a send fails, that result has `sendId: ""`, `status: "failed"`, and an error, but may still carry a provider `messageId`: delivery may already have happened. Do not blindly retry the whole call or infer that a failed result means no email left the provider.
|
|
58
|
+
|
|
59
|
+
Validation failures reject instead of returning recipient results. The runtime's errors carry codes `no_recipient`, `template_not_found`, `template_not_live`, `invalid_content`, or `missing_variables`; the error class is not an interface export. Missing-variable refusal follows the workspace setting. Marketing footer URLs are required system variables when the template uses them; test sends do not require those system URLs. Storage or downstream notification failures can also reject after side effects have started, so this call is not transactional or idempotent.
|
|
60
|
+
|
|
61
|
+
### Consume per-recipient results
|
|
62
|
+
|
|
63
|
+
This example returns the outcomes for an authorized tenant; the caller decides
|
|
64
|
+
whether a failed recipient can be retried without duplicating delivery.
|
|
65
|
+
|
|
66
|
+
```ts docs-check
|
|
67
|
+
import { SendTemplate } from "@antelopejs/interface-dms-mailing";
|
|
68
|
+
|
|
69
|
+
export async function sendOrderConfirmation(tenantId: string, recipients: string[]) {
|
|
70
|
+
const result = await SendTemplate("order-confirmation", {
|
|
71
|
+
tenantId,
|
|
72
|
+
to: recipients,
|
|
73
|
+
variables: { order: { total: "48.00" } },
|
|
74
|
+
source: "checkout",
|
|
75
|
+
});
|
|
76
|
+
return result.results ?? [result];
|
|
77
|
+
}
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
## RecordEmailEvent
|
|
81
|
+
|
|
82
|
+
```ts [Contract]
|
|
83
|
+
type SendEventType =
|
|
84
|
+
| "queued" | "sent" | "delivered" | "opened" | "clicked"
|
|
85
|
+
| "bounced" | "spam" | "failed" | "unsubscribed";
|
|
86
|
+
type SendStatus = SendEventType | "suppressed";
|
|
87
|
+
|
|
88
|
+
interface EmailEvent {
|
|
89
|
+
provider: string;
|
|
90
|
+
messageId: string;
|
|
91
|
+
type: SendEventType;
|
|
92
|
+
at?: Date;
|
|
93
|
+
details?: Record<string, unknown>;
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
declare function RecordEmailEvent(
|
|
97
|
+
tenantId: string,
|
|
98
|
+
event: EmailEvent,
|
|
99
|
+
): Promise<boolean>;
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
`messageId` is the provider's message ID, not the mailing `sendId`. Matching uses the tenant and message ID; `provider` is not an authorization boundary or an additional matching key. `at` defaults to now and is a `Date` in this backend interface, unlike the ISO string in the HTTP webhook.
|
|
103
|
+
|
|
104
|
+
The call returns `true` when it records the event. It returns `false` for an unmatched message, a duplicate event, or a send that is retiring or no longer accepts events. Supply a stable `details.eventId` for provider retries. Without it, deduplication requires the same explicit `at`, event type, and serialized details; omitting both event ID and timestamp does not deduplicate retries.
|
|
105
|
+
|
|
106
|
+
Accepted events update the send timeline, status and engagement counters, publish realtime and automation events, and can notify tenant owners of template problems. A hard bounce, spam complaint, or unsubscribe suppresses the recipient; soft bounces and test sends do not. Suppression-write failures are logged without rejecting the recorded event. Repeated activity conflicts, storage failures, or downstream publication failures can reject; a rejection does not guarantee that no event was stored.
|
|
107
|
+
|
|
108
|
+
`details.reason` supplies provider error text. `details.bounceType` distinguishes `soft`/`transient`/`temporary` from `hard`/`permanent`; otherwise the SMTP class in the reason decides. `details.url` and `details.userAgent` annotate engagement events. Authenticate a provider's webhook before translating it to this trusted call. The [runtime webhook guide](/docs/modules/mailing/extending#webhook-contract) defines HTTP authentication and response bodies.
|
|
109
|
+
|
|
110
|
+
## Template types
|
|
111
|
+
|
|
112
|
+
`TemplateContent` is `{ locales: Record<string, LocaleContent> }`; each `LocaleContent` has `subject: string`, `preheader: string`, and `blocks: Block[]`.
|
|
113
|
+
|
|
114
|
+
All blocks share `BlockBase`: `id: string`, the discriminant `type: BlockType`, and `visibleIf: Condition | null`. `Block` is the union of the following exported interfaces. All listed fields are required; `TextAlign` is `"left" | "center" | "right"`.
|
|
115
|
+
|
|
116
|
+
| Interface / `type` | Additional fields |
|
|
117
|
+
| --- | --- |
|
|
118
|
+
| `HeroBlock` / `hero` | `imageUrl: string`, `alt: string` |
|
|
119
|
+
| `HeadingBlock` / `heading` | `text: string`, `align: TextAlign`, `size: number` |
|
|
120
|
+
| `ParagraphBlock` / `paragraph` | `text: string`, `align: TextAlign` |
|
|
121
|
+
| `CodeBlock` / `code` | `text: string` |
|
|
122
|
+
| `ListBlock` / `list` | `source: string`, `labelPath: string`, `valuePath: string` |
|
|
123
|
+
| `TotalBlock` / `total` | `label: string`, `value: string` |
|
|
124
|
+
| `ButtonBlock` / `button` | `text: string`, `href: string`, `align: TextAlign` |
|
|
125
|
+
| `IfBlock` / `if` | `condition: Condition`, `children: Block[]`, `elseChildren: Block[] \| null` |
|
|
126
|
+
| `DividerBlock` / `divider` | None |
|
|
127
|
+
| `FooterBlock` / `footer` | `text: string`, `unsubscribeLabel: string`, `preferencesLabel: string` |
|
|
128
|
+
|
|
129
|
+
`Condition` has `path: string`, `operator: ConditionOperator`, and `value: string`. Operators are `truthy`, `falsy`, `eq`, `ne`, `gt`, and `lt`. `VariableDefinition` has `path: string`, `type: VariableType`, and `required: boolean`. Variable types are `string`, `text`, `number`, `money`, `date`, `url`, `boolean`, and `array`.
|
|
130
|
+
|
|
131
|
+
For template setup, footer variables and automation integration, use the [extending guide](/docs/modules/mailing/extending). Installation, configuration and HTTP routes remain in the runtime guide.
|
package/package.json
CHANGED
|
@@ -1,7 +1,18 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@antelopejs/interface-dms-mailing",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"description": "AntelopeJS interface for DMS mailing",
|
|
3
|
+
"version": "0.7.1",
|
|
4
|
+
"description": "AntelopeJS interface for the DMS mailing module: send templates and report e-mail events from any module.",
|
|
5
|
+
"keywords": [
|
|
6
|
+
"antelopejs",
|
|
7
|
+
"dms",
|
|
8
|
+
"email",
|
|
9
|
+
"interface",
|
|
10
|
+
"mailing"
|
|
11
|
+
],
|
|
12
|
+
"homepage": "https://dms.antelopejs.com/docs/modules/mailing/extending",
|
|
13
|
+
"bugs": {
|
|
14
|
+
"url": "https://github.com/AntelopeJS/dms-mailing/issues"
|
|
15
|
+
},
|
|
5
16
|
"license": "Apache-2.0",
|
|
6
17
|
"repository": {
|
|
7
18
|
"type": "git",
|
|
@@ -11,6 +22,7 @@
|
|
|
11
22
|
"files": [
|
|
12
23
|
"dist",
|
|
13
24
|
"!dist/.tsbuildinfo",
|
|
25
|
+
"docs",
|
|
14
26
|
"LICENSE",
|
|
15
27
|
"README.md"
|
|
16
28
|
],
|
|
@@ -41,11 +53,11 @@
|
|
|
41
53
|
"typecheck": "tsc --noEmit"
|
|
42
54
|
},
|
|
43
55
|
"dependencies": {
|
|
44
|
-
"@antelopejs/interface-core": ">=0.
|
|
45
|
-
"@antelopejs/interface-email": ">=0.0.
|
|
56
|
+
"@antelopejs/interface-core": ">=0.2.4 <1.0.0",
|
|
57
|
+
"@antelopejs/interface-email": ">=0.0.6 <1.0.0"
|
|
46
58
|
},
|
|
47
59
|
"devDependencies": {
|
|
48
|
-
"@antelopejs/tooling-configs": ">=0.0.
|
|
60
|
+
"@antelopejs/tooling-configs": ">=0.0.9 <1.0.0",
|
|
49
61
|
"@types/node": "^24.0.0",
|
|
50
62
|
"oxfmt": "^0.66.0",
|
|
51
63
|
"oxlint": "1.81.0",
|