@antelopejs/interface-email 0.0.5 → 0.1.0
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 +74 -13
- package/dist/index.d.ts +20 -4
- package/dist/index.js.map +1 -1
- package/docs/1.introduction.md +48 -29
- package/docs/2.sending-emails.md +81 -57
- package/docs/3.attachments.md +40 -22
- package/docs/assets/message-lifecycle.svg +19 -0
- package/package.json +40 -18
- package/skills/email-interface/SKILL.md +45 -7
- package/skills/email-interface/cases.json +49 -0
package/README.md
CHANGED
|
@@ -1,28 +1,89 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @antelopejs/interface-email
|
|
2
2
|
|
|
3
3
|
<div align="center">
|
|
4
|
-
<a href="https://www.npmjs.com/package/@antelopejs/interface-email"><img src="https://img.shields.io/npm/v/@antelopejs/interface-email?style=for-the-badge&labelColor=000000&color=000000"
|
|
5
|
-
<a href="./LICENSE"><img alt="License" src="https://img.shields.io/
|
|
6
|
-
<a href="https://discord.gg/sjK28QHrA7"><img src="https://img.shields.io/badge/Discord-18181B?logo=discord&style=for-the-badge&color=000000"
|
|
7
|
-
<a href="./docs/1.introduction.md"><img src="https://img.shields.io/badge/Docs-18181B?style=for-the-badge&color=000000"
|
|
4
|
+
<a href="https://www.npmjs.com/package/@antelopejs/interface-email"><img alt="npm" src="https://img.shields.io/npm/v/@antelopejs/interface-email?style=for-the-badge&labelColor=000000&color=000000"></a>
|
|
5
|
+
<a href="./LICENSE"><img alt="License" src="https://img.shields.io/npm/l/@antelopejs/interface-email?style=for-the-badge&labelColor=000000&color=000000"></a>
|
|
6
|
+
<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>
|
|
7
|
+
<a href="./docs/1.introduction.md"><img alt="Docs" src="https://img.shields.io/badge/Docs-18181B?style=for-the-badge&color=000000"></a>
|
|
8
8
|
</div>
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
The AntelopeJS contract for sending email: one API for single, batch and template messages, whatever provider delivers them.
|
|
11
11
|
|
|
12
|
-
##
|
|
12
|
+
## What it offers
|
|
13
|
+
|
|
14
|
+
- `Send` sends one message with text or HTML, recipients, threading headers and attachments.
|
|
15
|
+
- `SendBatch` sends several messages in one call, with shared defaults.
|
|
16
|
+
- `SendTemplate` renders a provider template or an inline template with variables.
|
|
17
|
+
- `GetCapabilities` reports what the provider supports, such as scheduling or tracking.
|
|
18
|
+
- `Send` and `SendTemplate` return a status, an optional provider message ID and optional error details. `SendBatch` returns totals and individual message results; `GetCapabilities` returns provider features and limits, not delivery results.
|
|
19
|
+
|
|
20
|
+
## Implementations
|
|
21
|
+
|
|
22
|
+
| Module | Notes |
|
|
23
|
+
| -------------------------------------------------------------------- | ----------------------- |
|
|
24
|
+
| [`@antelopejs/nodemailer`](https://github.com/AntelopeJS/nodemailer) | SMTP through Nodemailer |
|
|
25
|
+
|
|
26
|
+
## Install
|
|
27
|
+
|
|
28
|
+
Add the interface to the module that sends email:
|
|
13
29
|
|
|
14
30
|
```bash
|
|
15
|
-
|
|
31
|
+
pnpm add @antelopejs/interface-email
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
Then add an implementation to the project:
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
ajs project modules add @antelopejs/nodemailer
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
## Quick start
|
|
41
|
+
|
|
42
|
+
```ts
|
|
43
|
+
import { Send } from "@antelopejs/interface-email";
|
|
44
|
+
|
|
45
|
+
export async function sendWelcome(address: string) {
|
|
46
|
+
const response = await Send({
|
|
47
|
+
to: address,
|
|
48
|
+
subject: "Welcome aboard",
|
|
49
|
+
html: "<p>Thanks for joining.</p>",
|
|
50
|
+
text: "Thanks for joining.",
|
|
51
|
+
});
|
|
52
|
+
|
|
53
|
+
if (!response.success) {
|
|
54
|
+
throw new Error(response.error?.message);
|
|
55
|
+
}
|
|
56
|
+
return response.messageId;
|
|
57
|
+
}
|
|
16
58
|
```
|
|
17
59
|
|
|
18
60
|
## Documentation
|
|
19
61
|
|
|
20
|
-
|
|
62
|
+
- [Introduction](./docs/1.introduction.md)
|
|
63
|
+
- [Sending emails](./docs/2.sending-emails.md)
|
|
64
|
+
- [Attachments](./docs/3.attachments.md)
|
|
65
|
+
|
|
66
|
+
## Compatibility
|
|
67
|
+
|
|
68
|
+
<!-- docs-compat: ./package.json#peerDependencies -->
|
|
69
|
+
|
|
70
|
+
| Package | Range |
|
|
71
|
+
| ---------------------------- | ---------------- |
|
|
72
|
+
| `@antelopejs/interface-core` | `>=0.2.4 <1.0.0` |
|
|
21
73
|
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
74
|
+
This is the peer requirement in `package.json`. The package does not declare an
|
|
75
|
+
`@antelopejs/core` peer range; check the implementing module's requirements too.
|
|
76
|
+
|
|
77
|
+
## Contributing
|
|
78
|
+
|
|
79
|
+
Read [CONTRIBUTING.md](./CONTRIBUTING.md) before you open a pull request. The local checks are:
|
|
80
|
+
|
|
81
|
+
```bash
|
|
82
|
+
pnpm install
|
|
83
|
+
pnpm lint
|
|
84
|
+
pnpm build
|
|
85
|
+
```
|
|
25
86
|
|
|
26
87
|
## License
|
|
27
88
|
|
|
28
|
-
|
|
89
|
+
[Apache-2.0](./LICENSE)
|
package/dist/index.d.ts
CHANGED
|
@@ -1,3 +1,19 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A value JSON can represent: a string, number, boolean, `null`, an array of
|
|
3
|
+
* JSON values, or a {@link JsonObject}. `Date`, `Buffer`, functions and class
|
|
4
|
+
* instances are not JSON values; convert them first (for example
|
|
5
|
+
* `date.toISOString()`).
|
|
6
|
+
*/
|
|
7
|
+
export type JsonValue = string | number | boolean | null | JsonValue[] | JsonObject;
|
|
8
|
+
/**
|
|
9
|
+
* String keys mapped to JSON values. A key whose value is `undefined` is
|
|
10
|
+
* accepted so an optional field can be passed as is; `JSON.stringify` drops
|
|
11
|
+
* it. An object typed as an `interface` is not assignable (it has no index
|
|
12
|
+
* signature); declare it with a `type` alias or spread it into a literal.
|
|
13
|
+
*/
|
|
14
|
+
export type JsonObject = {
|
|
15
|
+
[key: string]: JsonValue | undefined;
|
|
16
|
+
};
|
|
1
17
|
export interface EmailAddressObject {
|
|
2
18
|
email: string;
|
|
3
19
|
name?: string;
|
|
@@ -81,7 +97,7 @@ export interface EmailParams {
|
|
|
81
97
|
/** Schedule for later delivery */
|
|
82
98
|
schedule?: ScheduleOptions;
|
|
83
99
|
/** Provider-specific options (use sparingly) */
|
|
84
|
-
providerOptions?:
|
|
100
|
+
providerOptions?: JsonObject;
|
|
85
101
|
}
|
|
86
102
|
/** Reference to a template hosted by the provider */
|
|
87
103
|
export interface ProviderTemplate {
|
|
@@ -105,9 +121,9 @@ export interface TemplateEmailParams {
|
|
|
105
121
|
/** Template to use */
|
|
106
122
|
template: ProviderTemplate | InlineTemplate;
|
|
107
123
|
/** Variables for template substitution */
|
|
108
|
-
variables?:
|
|
124
|
+
variables?: JsonObject;
|
|
109
125
|
/** Per-recipient variables (keyed by email address) */
|
|
110
|
-
recipientVariables?: Record<string,
|
|
126
|
+
recipientVariables?: Record<string, JsonObject>;
|
|
111
127
|
from?: EmailAddress;
|
|
112
128
|
replyTo?: EmailAddress | EmailAddress[];
|
|
113
129
|
cc?: EmailAddress | EmailAddress[];
|
|
@@ -120,7 +136,7 @@ export interface TemplateEmailParams {
|
|
|
120
136
|
tags?: string[];
|
|
121
137
|
metadata?: Record<string, string>;
|
|
122
138
|
schedule?: ScheduleOptions;
|
|
123
|
-
providerOptions?:
|
|
139
|
+
providerOptions?: JsonObject;
|
|
124
140
|
}
|
|
125
141
|
/** Single message in a batch */
|
|
126
142
|
export interface BatchEmailMessage extends EmailParams {
|
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,+DAA+D;
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,+DAA+D;AAkS/D;;;;;;;;;;GAUG;AACU,QAAA,IAAI,GAAG,IAAA,kCAAiB,GAAgB,CAAC;AAEtD;;;;;;;;;;;;GAYG;AACU,QAAA,SAAS,GAAG,IAAA,kCAAiB,GAAqB,CAAC;AAEhE;;;;;;;;;;GAUG;AACU,QAAA,YAAY,GAAG,IAAA,kCAAiB,GAAwB,CAAC;AAEtE;;;;;;;;;GASG;AACU,QAAA,eAAe,GAAG,IAAA,kCAAiB,GAA2B,CAAC"}
|
package/docs/1.introduction.md
CHANGED
|
@@ -1,19 +1,33 @@
|
|
|
1
1
|
# Introduction
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Send transactional messages, templates, and batches through one provider-neutral contract. `@antelopejs/interface-email` defines the request and response types; an implementing module supplies the email provider and its configuration.
|
|
4
|
+
|
|
5
|
+
## Choose your sending path
|
|
6
|
+
|
|
7
|
+
| Your task | Start here |
|
|
8
|
+
| -------------------------------------------------- | -------------------------------------------------------------- |
|
|
9
|
+
| Send a welcome email or receipt | [Send a message](./2.sending-emails.md#the-emailparams-object) |
|
|
10
|
+
| Personalize provider-hosted or inline content | [Template emails](./2.sending-emails.md#template-emails) |
|
|
11
|
+
| Send several messages and inspect partial failures | [Batch sending](./2.sending-emails.md#batch-sending) |
|
|
12
|
+
| Include a document or inline image | [Attachments](./3.attachments.md) |
|
|
13
|
+
| Keep optional features portable | [Provider capabilities](#provider-capabilities) |
|
|
14
|
+
|
|
15
|
+
{width="480"}
|
|
16
|
+
|
|
17
|
+
**Before sending:** configure an implementation with credentials and an authorized sender. Installing this contract alone does not connect an email service. Examples use placeholder recipients and do not send mail from this documentation.
|
|
4
18
|
|
|
5
19
|
## Core Concepts
|
|
6
20
|
|
|
7
21
|
The interface separates email operations into four functions:
|
|
8
22
|
|
|
9
|
-
| Function
|
|
10
|
-
|
|
|
11
|
-
| `Send`
|
|
12
|
-
| `SendBatch`
|
|
13
|
-
| `SendTemplate`
|
|
14
|
-
| `GetCapabilities` | Query the provider's supported features and limits
|
|
23
|
+
| Function | Purpose |
|
|
24
|
+
| ----------------- | -------------------------------------------------------------- |
|
|
25
|
+
| `Send` | Send a single email with full control over content and options |
|
|
26
|
+
| `SendBatch` | Send multiple emails in a single operation |
|
|
27
|
+
| `SendTemplate` | Send an email rendered from a template |
|
|
28
|
+
| `GetCapabilities` | Query the provider's supported features and limits |
|
|
15
29
|
|
|
16
|
-
|
|
30
|
+
The sending functions return typed delivery responses. `GetCapabilities` returns feature flags and limits instead. A successful send means the provider accepted the request; inspect `status` rather than treating acceptance as confirmed delivery.
|
|
17
31
|
|
|
18
32
|
## Installation
|
|
19
33
|
|
|
@@ -30,6 +44,8 @@ Recipients, senders, and reply-to addresses all accept the `EmailAddress` type.
|
|
|
30
44
|
Pass an email address directly as a string:
|
|
31
45
|
|
|
32
46
|
```ts
|
|
47
|
+
import type { EmailAddress } from "@antelopejs/interface-email";
|
|
48
|
+
|
|
33
49
|
const to: EmailAddress = "user@example.com";
|
|
34
50
|
```
|
|
35
51
|
|
|
@@ -64,10 +80,7 @@ Fields like `to`, `cc`, and `bcc` also accept arrays of `EmailAddress`, so you c
|
|
|
64
80
|
import { Send } from "@antelopejs/interface-email";
|
|
65
81
|
|
|
66
82
|
await Send({
|
|
67
|
-
to: [
|
|
68
|
-
"alice@example.com",
|
|
69
|
-
{ email: "bob@example.com", name: "Bob" },
|
|
70
|
-
],
|
|
83
|
+
to: ["alice@example.com", { email: "bob@example.com", name: "Bob" }],
|
|
71
84
|
subject: "Team Update",
|
|
72
85
|
text: "Here is the latest update.",
|
|
73
86
|
});
|
|
@@ -82,46 +95,52 @@ import { GetCapabilities } from "@antelopejs/interface-email";
|
|
|
82
95
|
|
|
83
96
|
const capabilities = await GetCapabilities();
|
|
84
97
|
|
|
85
|
-
console.log(capabilities.name);
|
|
86
|
-
console.log(capabilities.features.batch);
|
|
98
|
+
console.log(capabilities.name); // e.g., "sendgrid"
|
|
99
|
+
console.log(capabilities.features.batch); // true or false
|
|
87
100
|
console.log(capabilities.features.scheduling); // true or false
|
|
88
|
-
console.log(capabilities.maxRecipients);
|
|
101
|
+
console.log(capabilities.maxRecipients); // e.g., 1000
|
|
89
102
|
```
|
|
90
103
|
|
|
91
104
|
The `ProviderFeatures` object includes the following flags:
|
|
92
105
|
|
|
93
|
-
| Feature
|
|
94
|
-
|
|
|
95
|
-
| `batch`
|
|
96
|
-
| `templates`
|
|
97
|
-
| `scheduling`
|
|
98
|
-
| `openTracking`
|
|
99
|
-
| `clickTracking`
|
|
100
|
-
| `inlineAttachments` | Supports inline/embedded images
|
|
101
|
-
| `tags`
|
|
102
|
-
| `metadata`
|
|
103
|
-
| `priority`
|
|
106
|
+
| Feature | Description |
|
|
107
|
+
| ------------------- | ----------------------------------------------- |
|
|
108
|
+
| `batch` | Supports sending multiple emails in one request |
|
|
109
|
+
| `templates` | Supports provider-hosted templates |
|
|
110
|
+
| `scheduling` | Supports delayed email delivery |
|
|
111
|
+
| `openTracking` | Tracks when recipients open emails |
|
|
112
|
+
| `clickTracking` | Tracks when recipients click links |
|
|
113
|
+
| `inlineAttachments` | Supports inline/embedded images |
|
|
114
|
+
| `tags` | Supports email tagging for analytics |
|
|
115
|
+
| `metadata` | Supports custom metadata on emails |
|
|
116
|
+
| `priority` | Supports email priority levels |
|
|
104
117
|
|
|
105
118
|
Check capabilities before using optional features to ensure your code works across providers:
|
|
106
119
|
|
|
107
120
|
```ts
|
|
108
|
-
import {
|
|
121
|
+
import {
|
|
122
|
+
GetCapabilities,
|
|
123
|
+
Send,
|
|
124
|
+
type EmailParams,
|
|
125
|
+
} from "@antelopejs/interface-email";
|
|
109
126
|
|
|
110
127
|
const caps = await GetCapabilities();
|
|
111
128
|
|
|
112
|
-
const params:
|
|
129
|
+
const params: EmailParams = {
|
|
113
130
|
to: "user@example.com",
|
|
114
131
|
subject: "Hello",
|
|
115
132
|
html: "<p>Welcome!</p>",
|
|
116
133
|
};
|
|
117
134
|
|
|
118
135
|
if (caps.features.scheduling) {
|
|
119
|
-
params.schedule = { sendAt: new Date(
|
|
136
|
+
params.schedule = { sendAt: new Date(Date.now() + 60 * 60 * 1000) };
|
|
120
137
|
}
|
|
121
138
|
|
|
122
139
|
await Send(params);
|
|
123
140
|
```
|
|
124
141
|
|
|
142
|
+
Capability limits are optional: `maxRecipients`, `maxBatchSize`, `maxAttachmentSize`, and `maxEmailSize` may be absent. Size limits are in bytes. An absent limit is not a promise of unlimited capacity; check your provider configuration. `version` is optional provider metadata.
|
|
143
|
+
|
|
125
144
|
## Next Steps
|
|
126
145
|
|
|
127
146
|
- [Sending Emails](./2.sending-emails.md) -- Learn about all email parameters, templates, batch sending, and delivery responses.
|
package/docs/2.sending-emails.md
CHANGED
|
@@ -2,6 +2,8 @@
|
|
|
2
2
|
|
|
3
3
|
The interface provides three sending functions: `Send` for single emails, `SendTemplate` for template-based emails, and `SendBatch` for multiple emails in one operation.
|
|
4
4
|
|
|
5
|
+
For a first message, start with [`EmailParams`](#the-emailparams-object), then inspect the [response](#email-response). Add [templates](#template-emails), [batches](#batch-sending), or optional fields only when the workflow needs them. Optional features depend on [provider capabilities](./1.introduction.md#provider-capabilities).
|
|
6
|
+
|
|
5
7
|
## The `EmailParams` Object
|
|
6
8
|
|
|
7
9
|
The `Send` function accepts an `EmailParams` object. Only `to` and `subject` are required -- all other fields are optional.
|
|
@@ -15,42 +17,53 @@ const response = await Send({
|
|
|
15
17
|
html: "<h1>Welcome!</h1><p>Thanks for joining.</p>",
|
|
16
18
|
text: "Welcome! Thanks for joining.",
|
|
17
19
|
});
|
|
20
|
+
|
|
21
|
+
if (!response.success) {
|
|
22
|
+
throw new Error(
|
|
23
|
+
response.error?.message ?? "The provider did not accept the email",
|
|
24
|
+
);
|
|
25
|
+
}
|
|
26
|
+
console.log(response.status); // Acceptance is not proof of inbox delivery.
|
|
18
27
|
```
|
|
19
28
|
|
|
29
|
+
This example uses the configured default sender. Handle rejected promises at your
|
|
30
|
+
application boundary as well as unsuccessful responses. See [Email Response](#email-response)
|
|
31
|
+
for optional fields and retry precautions.
|
|
32
|
+
|
|
20
33
|
### Required Fields
|
|
21
34
|
|
|
22
|
-
| Field
|
|
23
|
-
|
|
|
24
|
-
| `to`
|
|
25
|
-
| `subject` | `string`
|
|
35
|
+
| Field | Type | Description |
|
|
36
|
+
| --------- | -------------------------------- | ---------------------- |
|
|
37
|
+
| `to` | `EmailAddress \| EmailAddress[]` | One or more recipients |
|
|
38
|
+
| `subject` | `string` | The email subject line |
|
|
26
39
|
|
|
27
40
|
### Content Fields
|
|
28
41
|
|
|
29
|
-
Provide at least one of `text` or `html
|
|
42
|
+
Provide at least one of `text` or `html`, even though the TypeScript type makes both optional. Including both gives readers a plain-text alternative to HTML.
|
|
30
43
|
|
|
31
|
-
| Field
|
|
32
|
-
|
|
|
44
|
+
| Field | Type | Description |
|
|
45
|
+
| ------ | -------- | --------------- |
|
|
33
46
|
| `text` | `string` | Plain text body |
|
|
34
|
-
| `html` | `string` | HTML body
|
|
47
|
+
| `html` | `string` | HTML body |
|
|
35
48
|
|
|
36
49
|
### Address Fields
|
|
37
50
|
|
|
38
|
-
| Field
|
|
39
|
-
|
|
|
40
|
-
| `from`
|
|
41
|
-
| `replyTo` | `EmailAddress \| EmailAddress[]` | Reply-to address(es)
|
|
42
|
-
| `cc`
|
|
43
|
-
| `bcc`
|
|
51
|
+
| Field | Type | Description |
|
|
52
|
+
| --------- | -------------------------------- | ------------------------------------------------- |
|
|
53
|
+
| `from` | `EmailAddress` | Sender address (uses provider default if omitted) |
|
|
54
|
+
| `replyTo` | `EmailAddress \| EmailAddress[]` | Reply-to address(es) |
|
|
55
|
+
| `cc` | `EmailAddress \| EmailAddress[]` | CC recipients |
|
|
56
|
+
| `bcc` | `EmailAddress \| EmailAddress[]` | BCC recipients |
|
|
44
57
|
|
|
45
58
|
### Threading Fields
|
|
46
59
|
|
|
47
60
|
Use these fields to place an email within an existing thread:
|
|
48
61
|
|
|
49
|
-
| Field
|
|
50
|
-
|
|
|
51
|
-
| `messageId`
|
|
52
|
-
| `inReplyTo`
|
|
53
|
-
| `references` | `string \| string[]` | Message-IDs of the thread
|
|
62
|
+
| Field | Type | Description |
|
|
63
|
+
| ------------ | -------------------- | ---------------------------------------- |
|
|
64
|
+
| `messageId` | `string` | Custom Message-ID header |
|
|
65
|
+
| `inReplyTo` | `string` | Message-ID of the email being replied to |
|
|
66
|
+
| `references` | `string \| string[]` | Message-IDs of the thread |
|
|
54
67
|
|
|
55
68
|
```ts
|
|
56
69
|
import { Send } from "@antelopejs/interface-email";
|
|
@@ -66,13 +79,13 @@ await Send({
|
|
|
66
79
|
|
|
67
80
|
## Email Priority
|
|
68
81
|
|
|
69
|
-
The `priority` field
|
|
82
|
+
The `priority` field requests a priority from providers that support it. It does not guarantee faster delivery. Check `features.priority` on the awaited provider capabilities before relying on this option.
|
|
70
83
|
|
|
71
|
-
| Value
|
|
72
|
-
|
|
|
73
|
-
| `"high"`
|
|
74
|
-
| `"normal"` | Standard delivery priority (default)
|
|
75
|
-
| `"low"`
|
|
84
|
+
| Value | Description |
|
|
85
|
+
| ---------- | ------------------------------------------- |
|
|
86
|
+
| `"high"` | Request high priority for an urgent message |
|
|
87
|
+
| `"normal"` | Standard delivery priority (default) |
|
|
88
|
+
| `"low"` | Non-urgent emails such as newsletters |
|
|
76
89
|
|
|
77
90
|
```ts
|
|
78
91
|
import { Send } from "@antelopejs/interface-email";
|
|
@@ -89,12 +102,12 @@ await Send({
|
|
|
89
102
|
|
|
90
103
|
The `tracking` field configures open and click tracking through the `TrackingOptions` interface.
|
|
91
104
|
|
|
92
|
-
| Field
|
|
93
|
-
|
|
|
94
|
-
| `opens`
|
|
95
|
-
| `clicks`
|
|
96
|
-
| `trackingDomain` | `string`
|
|
97
|
-
| `disabled`
|
|
105
|
+
| Field | Type | Description |
|
|
106
|
+
| ---------------- | --------- | ---------------------------------------- |
|
|
107
|
+
| `opens` | `boolean` | Track when the recipient opens the email |
|
|
108
|
+
| `clicks` | `boolean` | Track when the recipient clicks links |
|
|
109
|
+
| `trackingDomain` | `string` | Custom domain for tracking URLs |
|
|
110
|
+
| `disabled` | `boolean` | Disable all tracking |
|
|
98
111
|
|
|
99
112
|
```ts
|
|
100
113
|
import { Send } from "@antelopejs/interface-email";
|
|
@@ -115,10 +128,10 @@ await Send({
|
|
|
115
128
|
|
|
116
129
|
The `schedule` field delays email delivery to a specified time using the `ScheduleOptions` interface.
|
|
117
130
|
|
|
118
|
-
| Field
|
|
119
|
-
|
|
|
120
|
-
| `sendAt`
|
|
121
|
-
| `timezone` | `string`
|
|
131
|
+
| Field | Type | Description |
|
|
132
|
+
| ---------- | ---------------- | ------------------------------------------------------- |
|
|
133
|
+
| `sendAt` | `Date \| string` | When to send the email (ISO 8601 string or Date object) |
|
|
134
|
+
| `timezone` | `string` | IANA timezone identifier (e.g., `"Europe/Paris"`) |
|
|
122
135
|
|
|
123
136
|
```ts
|
|
124
137
|
import { Send } from "@antelopejs/interface-email";
|
|
@@ -128,21 +141,23 @@ await Send({
|
|
|
128
141
|
subject: "Monday Standup Reminder",
|
|
129
142
|
text: "Standup in 15 minutes.",
|
|
130
143
|
schedule: {
|
|
131
|
-
sendAt: new Date("
|
|
144
|
+
sendAt: new Date("2027-04-05T06:45:00Z"),
|
|
132
145
|
timezone: "Europe/Paris",
|
|
133
146
|
},
|
|
134
147
|
});
|
|
135
148
|
```
|
|
136
149
|
|
|
137
|
-
> **Note:** Check `GetCapabilities().features.scheduling` before using scheduling to confirm the provider supports it.
|
|
150
|
+
> **Note:** Check `(await GetCapabilities()).features.scheduling` before using scheduling to confirm the provider supports it.
|
|
151
|
+
|
|
152
|
+
Await `GetCapabilities()` before reading its flags. Use an explicit UTC offset when constructing a `Date`; the example is 08:45 in Paris on that date. A `timezone` field does not change how JavaScript parses a timezone-less date string.
|
|
138
153
|
|
|
139
154
|
## Tags and Metadata
|
|
140
155
|
|
|
141
156
|
Tags and metadata help categorize and track emails for analytics.
|
|
142
157
|
|
|
143
|
-
| Field
|
|
144
|
-
|
|
|
145
|
-
| `tags`
|
|
158
|
+
| Field | Type | Description |
|
|
159
|
+
| ---------- | ------------------------ | ------------------------------------------------- |
|
|
160
|
+
| `tags` | `string[]` | Labels for categorization and analytics |
|
|
146
161
|
| `metadata` | `Record<string, string>` | Custom key-value pairs returned in webhook events |
|
|
147
162
|
|
|
148
163
|
```ts
|
|
@@ -162,7 +177,7 @@ await Send({
|
|
|
162
177
|
|
|
163
178
|
## Provider Options
|
|
164
179
|
|
|
165
|
-
The `providerOptions` field passes provider-specific configuration that falls outside the standard interface. Use it sparingly, as it reduces portability.
|
|
180
|
+
The `providerOptions` field passes provider-specific configuration that falls outside the standard interface. Use it sparingly, as it reduces portability. The value is a `JsonObject`: every nested value must be a string, number, boolean, `null`, an array of such values, or an object of them. A key whose value is `undefined` is accepted, so an optional field can be passed as is; the provider drops it.
|
|
166
181
|
|
|
167
182
|
```ts
|
|
168
183
|
import { Send } from "@antelopejs/interface-email";
|
|
@@ -216,6 +231,8 @@ const response = await SendTemplate({
|
|
|
216
231
|
});
|
|
217
232
|
```
|
|
218
233
|
|
|
234
|
+
Template variables are a `JsonObject` too, so `variables` and each `recipientVariables` entry cannot carry a `Date`, a `Buffer` or a function. Convert such a value (for example with `toISOString()`) before sending. An object declared with an `interface` is rejected because it has no index signature: declare it with a `type` alias or spread it into a literal (`{ ...user }`).
|
|
235
|
+
|
|
219
236
|
### Per-recipient variables
|
|
220
237
|
|
|
221
238
|
When sending to multiple recipients, provide unique variable values for each one using `recipientVariables`:
|
|
@@ -246,13 +263,13 @@ const result = await SendBatch({
|
|
|
246
263
|
{
|
|
247
264
|
to: "alice@example.com",
|
|
248
265
|
subject: "Your invoice",
|
|
249
|
-
html: "<p>
|
|
266
|
+
html: "<p>Your invoice #001 is ready in your account.</p>",
|
|
250
267
|
batchId: "invoice-001",
|
|
251
268
|
},
|
|
252
269
|
{
|
|
253
270
|
to: "bob@example.com",
|
|
254
271
|
subject: "Your invoice",
|
|
255
|
-
html: "<p>
|
|
272
|
+
html: "<p>Your invoice #002 is ready in your account.</p>",
|
|
256
273
|
batchId: "invoice-002",
|
|
257
274
|
},
|
|
258
275
|
],
|
|
@@ -273,13 +290,16 @@ The `defaults` field applies shared values to all messages. Individual message f
|
|
|
273
290
|
When `continueOnError` is `true` (the default), the batch continues sending even if individual messages fail. The response includes per-message results:
|
|
274
291
|
|
|
275
292
|
```ts
|
|
276
|
-
console.log(result.total);
|
|
277
|
-
console.log(result.successful);
|
|
278
|
-
console.log(result.failed);
|
|
293
|
+
console.log(result.total); // Total messages in batch
|
|
294
|
+
console.log(result.successful); // Number sent successfully
|
|
295
|
+
console.log(result.failed); // Number that failed
|
|
279
296
|
|
|
280
297
|
for (const res of result.responses) {
|
|
281
298
|
if (!res.success) {
|
|
282
|
-
console.error(
|
|
299
|
+
console.error(
|
|
300
|
+
`Message ${res.batchId} to ${res.recipient} failed:`,
|
|
301
|
+
res.error,
|
|
302
|
+
);
|
|
283
303
|
}
|
|
284
304
|
}
|
|
285
305
|
```
|
|
@@ -288,20 +308,22 @@ for (const res of result.responses) {
|
|
|
288
308
|
|
|
289
309
|
The `Send` and `SendTemplate` functions return an `EmailResponse` object:
|
|
290
310
|
|
|
291
|
-
| Field
|
|
292
|
-
|
|
|
293
|
-
| `success`
|
|
294
|
-
| `status`
|
|
295
|
-
| `messageId` | `string`
|
|
296
|
-
| `error`
|
|
297
|
-
| `timestamp` | `Date`
|
|
298
|
-
| `provider`
|
|
311
|
+
| Field | Type | Description |
|
|
312
|
+
| ----------- | ------------- | --------------------------------------------- |
|
|
313
|
+
| `success` | `boolean` | Whether the email was accepted |
|
|
314
|
+
| `status` | `EmailStatus` | Current delivery status |
|
|
315
|
+
| `messageId` | `string` | Provider-assigned ID for tracking |
|
|
316
|
+
| `error` | `EmailError` | Error details if the send failed |
|
|
317
|
+
| `timestamp` | `Date` | When the email was accepted |
|
|
318
|
+
| `provider` | `string` | Name of the provider that handled the request |
|
|
299
319
|
|
|
300
320
|
The `EmailStatus` type includes these values: `"queued"`, `"sent"`, `"delivered"`, `"failed"`, `"rejected"`, `"scheduled"`, and `"unknown"`.
|
|
301
321
|
|
|
322
|
+
Only `success` and `status` are required on `EmailResponse`. Message IDs, errors, timestamps, and provider names may be absent. In a batch, each result also has an `index` into the original messages and a `recipient`; `batchId` is optional. The batch-level `success` is true only when every message succeeds.
|
|
323
|
+
|
|
302
324
|
### Error handling
|
|
303
325
|
|
|
304
|
-
When `success` is `false`, the `error` field
|
|
326
|
+
When `success` is `false`, inspect the optional `error` field for an `EmailError` object:
|
|
305
327
|
|
|
306
328
|
```ts
|
|
307
329
|
import { Send } from "@antelopejs/interface-email";
|
|
@@ -316,11 +338,13 @@ if (!response.success && response.error) {
|
|
|
316
338
|
console.error(`Error [${response.error.code}]: ${response.error.message}`);
|
|
317
339
|
|
|
318
340
|
if (response.error.retryable) {
|
|
319
|
-
//
|
|
341
|
+
// A retry may succeed; apply your retry and duplicate-send policy.
|
|
320
342
|
}
|
|
321
343
|
}
|
|
322
344
|
```
|
|
323
345
|
|
|
346
|
+
`retryable` is a hint, not an idempotency guarantee. Retrying can send another message; the interface does not define a deduplication key. `EmailError` requires `code` and `message`, with optional `field` and `retryable`. Also handle rejected promises from the configured implementation.
|
|
347
|
+
|
|
324
348
|
## Next Steps
|
|
325
349
|
|
|
326
350
|
- [Attachments](./3.attachments.md) -- Learn how to attach files using buffers, base64, file paths, or URLs.
|
package/docs/3.attachments.md
CHANGED
|
@@ -2,16 +2,16 @@
|
|
|
2
2
|
|
|
3
3
|
The interface supports four attachment types, each suited to a different source of file data. All types share a common `BaseAttachment` structure and are passed through the `attachments` field of `EmailParams`.
|
|
4
4
|
|
|
5
|
-
##
|
|
5
|
+
## Choose the source of the bytes
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
| You already have | Use | Supply |
|
|
8
|
+
| -------------------------------------- | ------------------ | ------------------------------------------ |
|
|
9
|
+
| Bytes in memory | `BufferAttachment` | `content: Buffer` |
|
|
10
|
+
| Base64-encoded bytes | `Base64Attachment` | `content: string` and `encoding: "base64"` |
|
|
11
|
+
| A file available to the implementation | `PathAttachment` | `path` |
|
|
12
|
+
| A file reachable by the implementation | `UrlAttachment` | `url` |
|
|
8
13
|
|
|
9
|
-
|
|
10
|
-
| --- | --- | --- | --- |
|
|
11
|
-
| `filename` | `string` | Yes | The filename shown to the recipient |
|
|
12
|
-
| `contentType` | `string` | No | MIME type (e.g., `"application/pdf"`) |
|
|
13
|
-
| `cid` | `string` | No | Content-ID for inline images (reference in HTML as `cid:yourCid`) |
|
|
14
|
-
| `inline` | `boolean` | No | If `true`, embed in the HTML body instead of attaching as a file |
|
|
14
|
+
Paths are server-side paths, not paths on the recipient's computer. Use trusted or validated paths and URLs; do not let untrusted input select arbitrary local files or internal network addresses. Check provider size limits before sending.
|
|
15
15
|
|
|
16
16
|
## Attachment Types
|
|
17
17
|
|
|
@@ -20,14 +20,17 @@ Every attachment type extends `BaseAttachment`, which defines shared metadata fi
|
|
|
20
20
|
Use `BufferAttachment` when you have file data in memory as a Node.js `Buffer`. This is common when generating files dynamically or reading from streams.
|
|
21
21
|
|
|
22
22
|
```ts
|
|
23
|
-
import { Send, BufferAttachment } from "@antelopejs/interface-email";
|
|
23
|
+
import { Send, type BufferAttachment } from "@antelopejs/interface-email";
|
|
24
24
|
|
|
25
|
-
const
|
|
25
|
+
const reportBuffer = Buffer.from(
|
|
26
|
+
"Quarterly report\nRevenue: 12500 EUR\n",
|
|
27
|
+
"utf8",
|
|
28
|
+
);
|
|
26
29
|
|
|
27
30
|
const attachment: BufferAttachment = {
|
|
28
|
-
filename: "report.
|
|
29
|
-
contentType: "
|
|
30
|
-
content:
|
|
31
|
+
filename: "report.txt",
|
|
32
|
+
contentType: "text/plain",
|
|
33
|
+
content: reportBuffer,
|
|
31
34
|
};
|
|
32
35
|
|
|
33
36
|
await Send({
|
|
@@ -46,16 +49,16 @@ Use `Base64Attachment` when you have file data encoded as a base64 string. Set t
|
|
|
46
49
|
import { Send, Base64Attachment } from "@antelopejs/interface-email";
|
|
47
50
|
|
|
48
51
|
const attachment: Base64Attachment = {
|
|
49
|
-
filename: "
|
|
50
|
-
contentType: "
|
|
51
|
-
content: "
|
|
52
|
+
filename: "notes.txt",
|
|
53
|
+
contentType: "text/plain",
|
|
54
|
+
content: "SGVsbG8h", // Base64 for "Hello!"
|
|
52
55
|
encoding: "base64",
|
|
53
56
|
};
|
|
54
57
|
|
|
55
58
|
await Send({
|
|
56
59
|
to: "user@example.com",
|
|
57
|
-
subject: "
|
|
58
|
-
text: "
|
|
60
|
+
subject: "Meeting Notes",
|
|
61
|
+
text: "Notes attached.",
|
|
59
62
|
attachments: [attachment],
|
|
60
63
|
});
|
|
61
64
|
```
|
|
@@ -106,10 +109,13 @@ await Send({
|
|
|
106
109
|
|
|
107
110
|
Inline attachments embed images directly in the HTML body using Content-ID references. Set `inline` to `true` and assign a `cid` value, then reference it in your HTML with the `cid:` protocol.
|
|
108
111
|
|
|
112
|
+
The following example reads a real PNG at `./assets/logo.png`, relative to the server's working directory. Supply that file before running it.
|
|
113
|
+
|
|
109
114
|
```ts
|
|
110
|
-
import {
|
|
115
|
+
import { readFile } from "node:fs/promises";
|
|
116
|
+
import { Send } from "@antelopejs/interface-email";
|
|
111
117
|
|
|
112
|
-
const logoBuffer =
|
|
118
|
+
const logoBuffer = await readFile("./assets/logo.png");
|
|
113
119
|
|
|
114
120
|
await Send({
|
|
115
121
|
to: "user@example.com",
|
|
@@ -132,7 +138,7 @@ await Send({
|
|
|
132
138
|
});
|
|
133
139
|
```
|
|
134
140
|
|
|
135
|
-
> **Note:** Check `GetCapabilities().features.inlineAttachments` to confirm the provider supports inline images.
|
|
141
|
+
> **Note:** Check `(await GetCapabilities()).features.inlineAttachments` to confirm the provider supports inline images.
|
|
136
142
|
|
|
137
143
|
## Multiple Attachments
|
|
138
144
|
|
|
@@ -165,12 +171,24 @@ await Send({
|
|
|
165
171
|
});
|
|
166
172
|
```
|
|
167
173
|
|
|
174
|
+
## The `BaseAttachment` Interface
|
|
175
|
+
|
|
176
|
+
Every attachment requires a filename. These shared fields apply to all four sources:
|
|
177
|
+
|
|
178
|
+
| Field | Type | Required | Description |
|
|
179
|
+
| ------------- | --------- | -------- | ----------------------------------------------------------------- |
|
|
180
|
+
| `filename` | `string` | Yes | The filename shown to the recipient |
|
|
181
|
+
| `contentType` | `string` | No | MIME type (e.g., `"application/pdf"`) |
|
|
182
|
+
| `cid` | `string` | No | Content-ID for inline images (reference in HTML as `cid:yourCid`) |
|
|
183
|
+
| `inline` | `boolean` | No | If `true`, embed in the HTML body instead of attaching as a file |
|
|
184
|
+
|
|
168
185
|
## The `Attachment` Union Type
|
|
169
186
|
|
|
170
187
|
The `Attachment` type is a union of all four attachment interfaces:
|
|
171
188
|
|
|
172
189
|
```ts
|
|
173
|
-
type Attachment =
|
|
190
|
+
type Attachment =
|
|
191
|
+
BufferAttachment | Base64Attachment | PathAttachment | UrlAttachment;
|
|
174
192
|
```
|
|
175
193
|
|
|
176
194
|
When constructing attachments dynamically, TypeScript narrows the type based on the presence of distinguishing fields (`content` with `encoding`, `path`, or `url`).
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
<svg xmlns="http://www.w3.org/2000/svg" width="480" height="650" viewBox="0 0 480 650" role="img" aria-labelledby="title desc">
|
|
2
|
+
<title id="title">From message to provider response</title>
|
|
3
|
+
<desc id="desc">Send, SendTemplate, and SendBatch lead to a configured provider. Inspect acceptance, status, and per-message errors. Acceptance is not proof of inbox delivery.</desc>
|
|
4
|
+
<defs><marker id="arrow" markerWidth="8" markerHeight="8" refX="7" refY="4" orient="auto"><path d="M0 0 8 4 0 8" fill="#627d98"/></marker></defs>
|
|
5
|
+
<rect width="480" height="650" rx="16" fill="#f4f7fb"/>
|
|
6
|
+
<g font-family="system-ui, sans-serif" fill="#17324d" font-size="18">
|
|
7
|
+
<text x="24" y="36" font-size="24" font-weight="700">Choose content.</text><text x="24" y="65" font-size="24" font-weight="700">Inspect the outcome.</text>
|
|
8
|
+
<text x="24" y="96">Configured email provider required</text>
|
|
9
|
+
<rect x="24" y="118" width="432" height="132" rx="10" fill="#e2edf8" stroke="#b0c9e0"/>
|
|
10
|
+
<text x="44" y="153" font-size="20" font-weight="600">Send · one message</text><text x="44" y="190" font-size="20" font-weight="600">SendTemplate · from a template</text><text x="44" y="227" font-size="20" font-weight="600">SendBatch · multiple messages</text>
|
|
11
|
+
<path d="M240 250V284" stroke="#627d98" stroke-width="2" marker-end="url(#arrow)"/>
|
|
12
|
+
<rect x="24" y="294" width="432" height="86" rx="10" fill="#17324d"/>
|
|
13
|
+
<text x="44" y="328" fill="#fff" font-size="22" font-weight="700">Email provider</text><text x="44" y="357" fill="#d5e5f3">Capabilities + limits</text>
|
|
14
|
+
<path d="M240 380V414" stroke="#627d98" stroke-width="2" marker-end="url(#arrow)"/>
|
|
15
|
+
<rect x="24" y="424" width="432" height="116" rx="10" fill="#e2f3ec" stroke="#91c7ae"/>
|
|
16
|
+
<text x="44" y="456" font-size="22" font-weight="700">Read the response</text><text x="44" y="486">success + status · optional ID and error</text><text x="44" y="516">Batch: inspect each result</text>
|
|
17
|
+
<rect x="24" y="562" width="432" height="66" rx="8" fill="#fff0cf"/><text x="40" y="589" font-weight="600">Accepted ≠ delivered.</text><text x="40" y="614" font-size="16">Retries need a duplicate-send policy.</text>
|
|
18
|
+
</g>
|
|
19
|
+
</svg>
|
package/package.json
CHANGED
|
@@ -1,55 +1,77 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@antelopejs/interface-email",
|
|
3
|
-
"version": "0.0
|
|
4
|
-
"description": "AntelopeJS interface for
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "AntelopeJS interface for sending email: single, batch and template messages with attachments",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"antelopejs",
|
|
7
|
-
"interface",
|
|
8
7
|
"email",
|
|
8
|
+
"interface",
|
|
9
9
|
"mailing"
|
|
10
10
|
],
|
|
11
|
+
"homepage": "https://github.com/AntelopeJS/interface-email/tree/main/docs",
|
|
12
|
+
"bugs": {
|
|
13
|
+
"url": "https://github.com/AntelopeJS/interface-email/issues"
|
|
14
|
+
},
|
|
15
|
+
"license": "Apache-2.0",
|
|
11
16
|
"repository": {
|
|
12
17
|
"type": "git",
|
|
13
18
|
"url": "git+https://github.com/AntelopeJS/interface-email.git"
|
|
14
19
|
},
|
|
15
|
-
"license": "Apache-2.0",
|
|
16
|
-
"packageManager": "pnpm@10.6.5",
|
|
17
|
-
"main": "dist/index.js",
|
|
18
|
-
"types": "dist/index.d.ts",
|
|
19
20
|
"files": [
|
|
20
21
|
"dist",
|
|
21
22
|
"docs",
|
|
22
23
|
"skills"
|
|
23
24
|
],
|
|
25
|
+
"main": "dist/index.js",
|
|
26
|
+
"types": "dist/index.d.ts",
|
|
24
27
|
"exports": {
|
|
25
28
|
".": {
|
|
26
29
|
"types": "./dist/index.d.ts",
|
|
27
30
|
"default": "./dist/index.js"
|
|
28
31
|
}
|
|
29
32
|
},
|
|
33
|
+
"publishConfig": {
|
|
34
|
+
"access": "public",
|
|
35
|
+
"provenance": true
|
|
36
|
+
},
|
|
30
37
|
"scripts": {
|
|
31
|
-
"build": "rimraf dist && tsc",
|
|
32
|
-
"format": "
|
|
33
|
-
"lint:fix": "
|
|
34
|
-
"lint": "
|
|
38
|
+
"build": "rimraf dist && tsc -p tsconfig.build.json",
|
|
39
|
+
"format": "oxfmt .",
|
|
40
|
+
"lint:fix": "oxlint --fix",
|
|
41
|
+
"lint": "oxlint",
|
|
35
42
|
"prepack": "pnpm run build",
|
|
36
|
-
"release": "pnpm run lint && pnpm run prepack && release-it"
|
|
43
|
+
"release": "pnpm run lint && pnpm run prepack && release-it",
|
|
44
|
+
"format:check": "oxfmt --check .",
|
|
45
|
+
"knip": "knip",
|
|
46
|
+
"prepare": "if git rev-parse --is-inside-work-tree >/dev/null 2>&1 && command -v lefthook >/dev/null 2>&1; then lefthook install; fi",
|
|
47
|
+
"checks": "antelopejs-checks",
|
|
48
|
+
"size": "antelopejs-check-size",
|
|
49
|
+
"sync": "antelopejs-sync",
|
|
50
|
+
"sync:check": "antelopejs-sync --check",
|
|
51
|
+
"typecheck": "tsc --noEmit",
|
|
52
|
+
"test": "pnpm run build",
|
|
53
|
+
"suppressions": "antelopejs-suppressions",
|
|
54
|
+
"suppressions:update": "antelopejs-suppressions --update"
|
|
37
55
|
},
|
|
38
56
|
"devDependencies": {
|
|
39
|
-
"@antelopejs/interface-core": ">=0.
|
|
40
|
-
"@
|
|
57
|
+
"@antelopejs/interface-core": ">=0.2.4 <1.0.0",
|
|
58
|
+
"@antelopejs/tooling-configs": "^0.2.11",
|
|
41
59
|
"@types/node": "^22.19.15",
|
|
60
|
+
"eslint-plugin-perfectionist": "^5.11.0",
|
|
61
|
+
"knip": "^6.34.0",
|
|
62
|
+
"lefthook": "^2.2.2",
|
|
63
|
+
"oxfmt": "^0.66.0",
|
|
64
|
+
"oxlint": "1.81.0",
|
|
65
|
+
"oxlint-tsgolint": "^7.0.2001",
|
|
42
66
|
"release-it": "^19.2.4",
|
|
43
67
|
"release-it-changelogen": "^0.1.0",
|
|
44
68
|
"rimraf": "^6.1.3",
|
|
45
69
|
"typescript": "^5.9.3"
|
|
46
70
|
},
|
|
47
71
|
"peerDependencies": {
|
|
48
|
-
"@antelopejs/interface-core": ">=0.
|
|
49
|
-
},
|
|
50
|
-
"publishConfig": {
|
|
51
|
-
"access": "public"
|
|
72
|
+
"@antelopejs/interface-core": ">=0.2.4 <1.0.0"
|
|
52
73
|
},
|
|
74
|
+
"packageManager": "pnpm@10.6.5",
|
|
53
75
|
"antelopeJs": {
|
|
54
76
|
"skills": [
|
|
55
77
|
"./skills"
|
|
@@ -14,8 +14,21 @@ Provider-agnostic email sending: consumers call four `InterfaceFunction` proxy p
|
|
|
14
14
|
The package has a single root export:
|
|
15
15
|
|
|
16
16
|
```ts
|
|
17
|
-
import {
|
|
18
|
-
|
|
17
|
+
import {
|
|
18
|
+
Send,
|
|
19
|
+
SendBatch,
|
|
20
|
+
SendTemplate,
|
|
21
|
+
GetCapabilities,
|
|
22
|
+
} from "@antelopejs/interface-email";
|
|
23
|
+
import type {
|
|
24
|
+
EmailParams,
|
|
25
|
+
TemplateEmailParams,
|
|
26
|
+
BatchEmailParams,
|
|
27
|
+
EmailResponse,
|
|
28
|
+
BatchEmailResponse,
|
|
29
|
+
Attachment,
|
|
30
|
+
ProviderCapabilities,
|
|
31
|
+
} from "@antelopejs/interface-email";
|
|
19
32
|
```
|
|
20
33
|
|
|
21
34
|
## Consuming
|
|
@@ -30,14 +43,20 @@ const response = await Send({
|
|
|
30
43
|
subject: "Your loan is due back Friday",
|
|
31
44
|
html: "<h1>Return reminder</h1>",
|
|
32
45
|
text: "Return reminder",
|
|
33
|
-
attachments: [
|
|
46
|
+
attachments: [
|
|
47
|
+
{
|
|
48
|
+
filename: "loan-receipt.pdf",
|
|
49
|
+
contentType: "application/pdf",
|
|
50
|
+
path: "/data/loan-receipt.pdf",
|
|
51
|
+
},
|
|
52
|
+
],
|
|
34
53
|
});
|
|
35
54
|
if (!response.success) {
|
|
36
55
|
// response.error: { code, message, field?, retryable? }
|
|
37
56
|
}
|
|
38
57
|
```
|
|
39
58
|
|
|
40
|
-
`SendTemplate` takes `template: { id }` (provider-hosted) or `{ content, type }` (inline) plus `variables` / `recipientVariables`. `SendBatch` takes `{ messages, defaults?, continueOnError? }` and returns per-message results.
|
|
59
|
+
`SendTemplate` takes `template: { id }` (provider-hosted) or `{ content, type }` (inline) plus `variables` / `recipientVariables`. These and `providerOptions` are typed `JsonObject` (exported with `JsonValue`): strings, numbers, booleans, `null`, arrays and objects of them, with `undefined` accepted as a key's value. Convert a `Date` or `Buffer` first; an object typed as an `interface` is rejected, so use a `type` alias or spread it into a literal. `SendBatch` takes `{ messages, defaults?, continueOnError? }` and returns per-message results.
|
|
41
60
|
|
|
42
61
|
## Providing
|
|
43
62
|
|
|
@@ -49,9 +68,28 @@ import * as EmailInterface from "@antelopejs/interface-email";
|
|
|
49
68
|
|
|
50
69
|
ImplementInterface(EmailInterface, {
|
|
51
70
|
Send: async (params) => ({ success: true, status: "sent", messageId: "..." }),
|
|
52
|
-
SendBatch: async (params) => ({
|
|
71
|
+
SendBatch: async (params) => ({
|
|
72
|
+
success: true,
|
|
73
|
+
total: 0,
|
|
74
|
+
successful: 0,
|
|
75
|
+
failed: 0,
|
|
76
|
+
responses: [],
|
|
77
|
+
}),
|
|
53
78
|
SendTemplate: async (params) => ({ success: true, status: "sent" }),
|
|
54
|
-
GetCapabilities: async () => ({
|
|
79
|
+
GetCapabilities: async () => ({
|
|
80
|
+
name: "my-provider",
|
|
81
|
+
features: {
|
|
82
|
+
batch: true,
|
|
83
|
+
templates: false,
|
|
84
|
+
scheduling: false,
|
|
85
|
+
openTracking: false,
|
|
86
|
+
clickTracking: false,
|
|
87
|
+
inlineAttachments: true,
|
|
88
|
+
tags: false,
|
|
89
|
+
metadata: false,
|
|
90
|
+
priority: true,
|
|
91
|
+
},
|
|
92
|
+
}),
|
|
55
93
|
});
|
|
56
94
|
```
|
|
57
95
|
|
|
@@ -64,7 +102,7 @@ Also declare `"antelopeJs": { "implements": ["@antelopejs/interface-email"] }` i
|
|
|
64
102
|
- Feature support varies by provider — gate `schedule`, `tracking`, `tags`, `metadata`, `priority` and templates on `(await GetCapabilities()).features` before relying on them.
|
|
65
103
|
- `EmailParams` requires only `to` and `subject`; provide at least one of `text` / `html` (both for client compatibility). `from` falls back to the provider default.
|
|
66
104
|
- `Attachment` is a union with exactly one source field: `content: Buffer`, `content` + `encoding: "base64"`, `path`, or `url`. Inline images need `cid` (referenced as `cid:yourCid` in HTML) and `inline: true`.
|
|
67
|
-
- Batch: `continueOnError` defaults to `true`; `BatchEmailResponse.success` is `true` only if
|
|
105
|
+
- Batch: `continueOnError` defaults to `true`; `BatchEmailResponse.success` is `true` only if _all_ messages succeeded — correlate individual results via `batchId` or `index`.
|
|
68
106
|
- `EmailStatus` includes `"queued"` and `"scheduled"` — a successful response does not mean delivered.
|
|
69
107
|
|
|
70
108
|
## Deeper reference
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
{
|
|
2
|
+
"version": 1,
|
|
3
|
+
"cases": [
|
|
4
|
+
{
|
|
5
|
+
"id": "email-interface-send-attachment",
|
|
6
|
+
"area": "framework",
|
|
7
|
+
"style": "clean",
|
|
8
|
+
"prompt": "In my AntelopeJS module, how do I send an HTML email with a PDF attached?",
|
|
9
|
+
"expect": {
|
|
10
|
+
"skills": ["email-interface"],
|
|
11
|
+
"acceptable": ["antelopejs", "ajs-consume-interface"],
|
|
12
|
+
"mustMention": ["Send", "attachments"]
|
|
13
|
+
}
|
|
14
|
+
},
|
|
15
|
+
{
|
|
16
|
+
"id": "email-interface-batch-casual",
|
|
17
|
+
"area": "framework",
|
|
18
|
+
"style": "casual",
|
|
19
|
+
"prompt": "need to fire off a bunch of emails at once from my module, which call do i use",
|
|
20
|
+
"expect": {
|
|
21
|
+
"skills": ["email-interface"],
|
|
22
|
+
"acceptable": ["antelopejs", "ajs-consume-interface"],
|
|
23
|
+
"mustMention": ["SendBatch"]
|
|
24
|
+
}
|
|
25
|
+
},
|
|
26
|
+
{
|
|
27
|
+
"id": "email-interface-template-variables",
|
|
28
|
+
"area": "framework",
|
|
29
|
+
"style": "clean",
|
|
30
|
+
"prompt": "I want to send a templated email with per-recipient values through the AntelopeJS email interface. What do I pass?",
|
|
31
|
+
"expect": {
|
|
32
|
+
"skills": ["email-interface"],
|
|
33
|
+
"acceptable": ["antelopejs", "ajs-consume-interface"],
|
|
34
|
+
"mustMention": ["SendTemplate", "recipientVariables"]
|
|
35
|
+
}
|
|
36
|
+
},
|
|
37
|
+
{
|
|
38
|
+
"id": "email-interface-dms-mailing-neighbour",
|
|
39
|
+
"area": "modules",
|
|
40
|
+
"style": "clean",
|
|
41
|
+
"prompt": "How do I ship email templates and template categories as code in a DMS module?",
|
|
42
|
+
"expect": {
|
|
43
|
+
"skills": ["dms-mailing"],
|
|
44
|
+
"acceptable": ["dms", "antelopejs"],
|
|
45
|
+
"avoid": ["email-interface"]
|
|
46
|
+
}
|
|
47
|
+
}
|
|
48
|
+
]
|
|
49
|
+
}
|