@antelopejs/interface-email 0.0.6 → 0.1.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 +15 -12
- package/dist/index.d.ts +20 -4
- package/dist/index.js.map +1 -1
- package/docs/1.introduction.md +52 -24
- package/docs/2.sending-emails.md +76 -51
- package/docs/3.attachments.md +63 -35
- package/docs/assets/message-lifecycle.svg +19 -0
- package/docs/tsconfig.json +7 -0
- package/package.json +19 -5
- package/skills/email-interface/SKILL.md +1 -1
- package/skills/email-interface/cases.json +49 -0
package/README.md
CHANGED
|
@@ -1,10 +1,10 @@
|
|
|
1
|
-
#
|
|
1
|
+
# `@antelopejs/interface-email`
|
|
2
2
|
|
|
3
3
|
<div align="center">
|
|
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/
|
|
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>
|
|
4
|
+
<a href="https://www.npmjs.com/package/@antelopejs/interface-email"><img data-illustration 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 data-illustration 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/g4pFt6eXqu"><img data-illustration 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 data-illustration 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.
|
|
@@ -15,13 +15,14 @@ The AntelopeJS contract for sending email: one API for single, batch and templat
|
|
|
15
15
|
- `SendBatch` sends several messages in one call, with shared defaults.
|
|
16
16
|
- `SendTemplate` renders a provider template or an inline template with variables.
|
|
17
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
|
|
18
|
+
- `Send` and `SendTemplate` return a status, an optional provider message ID, and optional error details. `SendBatch` returns totals and one result per message. `GetCapabilities` returns provider features and limits, not delivery results.
|
|
19
19
|
|
|
20
20
|
## Implementations
|
|
21
21
|
|
|
22
22
|
| Module | Notes |
|
|
23
23
|
| -------------------------------------------------------------------- | ----------------------- |
|
|
24
24
|
| [`@antelopejs/nodemailer`](https://github.com/AntelopeJS/nodemailer) | SMTP through Nodemailer |
|
|
25
|
+
| [`@antelopejs/brevo`](https://github.com/AntelopeJS/brevo) | Brevo HTTP API |
|
|
25
26
|
|
|
26
27
|
## Install
|
|
27
28
|
|
|
@@ -65,14 +66,16 @@ export async function sendWelcome(address: string) {
|
|
|
65
66
|
|
|
66
67
|
## Compatibility
|
|
67
68
|
|
|
68
|
-
<!-- docs-compat:
|
|
69
|
+
<!-- antelopejs-docs-compat:start -->
|
|
69
70
|
|
|
70
|
-
| Package |
|
|
71
|
-
| ---------------------------- | ---------------- |
|
|
72
|
-
| `@antelopejs/interface-core` | `>=0.2.4 <1.0.0` |
|
|
71
|
+
| Package | Supported | Tested with |
|
|
72
|
+
| ---------------------------- | ---------------- | ----------- |
|
|
73
|
+
| `@antelopejs/interface-core` | `>=0.2.4 <1.0.0` | `0.2.4` |
|
|
73
74
|
|
|
74
|
-
|
|
75
|
-
|
|
75
|
+
<!-- antelopejs-docs-compat:end -->
|
|
76
|
+
|
|
77
|
+
The table repeats the peer range in `package.json`. The package declares no
|
|
78
|
+
`@antelopejs/core` peer range, so check the requirements of the implementing module too.
|
|
76
79
|
|
|
77
80
|
## Contributing
|
|
78
81
|
|
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,10 +1,28 @@
|
|
|
1
|
-
|
|
1
|
+
---
|
|
2
|
+
title: Introduction
|
|
3
|
+
description: Install the email interface, pick the function for your task, write recipient addresses, and check provider capabilities before you use an optional feature.
|
|
4
|
+
mode: how-to
|
|
5
|
+
---
|
|
2
6
|
|
|
3
|
-
|
|
7
|
+
Send transactional messages, templates, and batches through one contract that does not depend on the provider. `@antelopejs/interface-email` defines the request and response types. An implementing module supplies the email provider and its configuration.
|
|
4
8
|
|
|
5
|
-
##
|
|
9
|
+
## Choose your sending path
|
|
6
10
|
|
|
7
|
-
|
|
11
|
+
| Your task | Start here |
|
|
12
|
+
| -------------------------------------------------- | -------------------------------------------------------------- |
|
|
13
|
+
| Send a welcome email or receipt | [Send a message](./2.sending-emails.md#the-emailparams-object) |
|
|
14
|
+
| Personalize provider-hosted or inline content | [Template emails](./2.sending-emails.md#template-emails) |
|
|
15
|
+
| Send several messages and inspect partial failures | [Batch sending](./2.sending-emails.md#batch-sending) |
|
|
16
|
+
| Include a document or inline image | [Attachments](./3.attachments.md) |
|
|
17
|
+
| Keep optional features portable | [Provider capabilities](#provider-capabilities) |
|
|
18
|
+
|
|
19
|
+
{width="480"}
|
|
20
|
+
|
|
21
|
+
**Before sending.** Configure an implementation with credentials and an authorized sender. This contract alone does not connect an email service. The examples use placeholder recipients and send no mail from this documentation.
|
|
22
|
+
|
|
23
|
+
## Core concepts
|
|
24
|
+
|
|
25
|
+
The interface splits email operations into four functions:
|
|
8
26
|
|
|
9
27
|
| Function | Purpose |
|
|
10
28
|
| ----------------- | -------------------------------------------------------------- |
|
|
@@ -13,7 +31,7 @@ The interface separates email operations into four functions:
|
|
|
13
31
|
| `SendTemplate` | Send an email rendered from a template |
|
|
14
32
|
| `GetCapabilities` | Query the provider's supported features and limits |
|
|
15
33
|
|
|
16
|
-
|
|
34
|
+
The sending functions return typed delivery responses. `GetCapabilities` returns feature flags and limits instead. A successful send means that the provider accepted the request. It does not confirm delivery, so read `status` as well.
|
|
17
35
|
|
|
18
36
|
## Installation
|
|
19
37
|
|
|
@@ -21,21 +39,23 @@ Each function returns a typed response that includes delivery status, provider m
|
|
|
21
39
|
npm install @antelopejs/interface-email
|
|
22
40
|
```
|
|
23
41
|
|
|
24
|
-
## Email
|
|
42
|
+
## Email address types
|
|
25
43
|
|
|
26
|
-
Recipients, senders, and reply-to addresses all accept the `EmailAddress` type.
|
|
44
|
+
Recipients, senders, and reply-to addresses all accept the `EmailAddress` type. It has two forms: a plain string, or an object with an optional display name.
|
|
27
45
|
|
|
28
46
|
### String format
|
|
29
47
|
|
|
30
48
|
Pass an email address directly as a string:
|
|
31
49
|
|
|
32
50
|
```ts
|
|
51
|
+
import type { EmailAddress } from "@antelopejs/interface-email";
|
|
52
|
+
|
|
33
53
|
const to: EmailAddress = "user@example.com";
|
|
34
54
|
```
|
|
35
55
|
|
|
36
56
|
### Object format with `EmailAddressObject`
|
|
37
57
|
|
|
38
|
-
Use the object
|
|
58
|
+
Use the object form to add a display name to the address:
|
|
39
59
|
|
|
40
60
|
```ts
|
|
41
61
|
import { EmailAddressObject } from "@antelopejs/interface-email";
|
|
@@ -48,7 +68,7 @@ const sender: EmailAddressObject = {
|
|
|
48
68
|
|
|
49
69
|
### The `EmailAddress` union type
|
|
50
70
|
|
|
51
|
-
|
|
71
|
+
`EmailAddress` is the union of both forms. Every address field in the interface accepts either form:
|
|
52
72
|
|
|
53
73
|
```ts
|
|
54
74
|
import { EmailAddress } from "@antelopejs/interface-email";
|
|
@@ -58,7 +78,7 @@ const simple: EmailAddress = "hello@example.com";
|
|
|
58
78
|
const detailed: EmailAddress = { email: "hello@example.com", name: "Hello" };
|
|
59
79
|
```
|
|
60
80
|
|
|
61
|
-
|
|
81
|
+
The `to`, `replyTo`, `cc`, and `bcc` fields also accept an array of `EmailAddress`, and the array can mix both forms. `from` takes a single address.
|
|
62
82
|
|
|
63
83
|
```ts
|
|
64
84
|
import { Send } from "@antelopejs/interface-email";
|
|
@@ -70,56 +90,64 @@ await Send({
|
|
|
70
90
|
});
|
|
71
91
|
```
|
|
72
92
|
|
|
73
|
-
## Provider
|
|
93
|
+
## Provider capabilities
|
|
74
94
|
|
|
75
|
-
|
|
95
|
+
Providers differ in what they support. `GetCapabilities` returns a `ProviderCapabilities` object with the provider's name, limits, and supported features.
|
|
76
96
|
|
|
77
97
|
```ts
|
|
78
98
|
import { GetCapabilities } from "@antelopejs/interface-email";
|
|
79
99
|
|
|
80
100
|
const capabilities = await GetCapabilities();
|
|
81
101
|
|
|
82
|
-
console.log(capabilities.name); //
|
|
102
|
+
console.log(capabilities.name); // "nodemailer" with @antelopejs/nodemailer
|
|
83
103
|
console.log(capabilities.features.batch); // true or false
|
|
84
104
|
console.log(capabilities.features.scheduling); // true or false
|
|
85
|
-
console.log(capabilities.maxRecipients); //
|
|
105
|
+
console.log(capabilities.maxRecipients); // undefined when the provider reports no limit
|
|
86
106
|
```
|
|
87
107
|
|
|
88
|
-
The `ProviderFeatures` object
|
|
108
|
+
The `ProviderFeatures` object has these flags:
|
|
89
109
|
|
|
90
110
|
| Feature | Description |
|
|
91
111
|
| ------------------- | ----------------------------------------------- |
|
|
92
112
|
| `batch` | Supports sending multiple emails in one request |
|
|
93
|
-
| `templates` | Supports
|
|
113
|
+
| `templates` | Supports `SendTemplate` |
|
|
94
114
|
| `scheduling` | Supports delayed email delivery |
|
|
95
115
|
| `openTracking` | Tracks when recipients open emails |
|
|
96
116
|
| `clickTracking` | Tracks when recipients click links |
|
|
97
|
-
| `inlineAttachments` | Supports inline
|
|
117
|
+
| `inlineAttachments` | Supports inline, embedded images |
|
|
98
118
|
| `tags` | Supports email tagging for analytics |
|
|
99
119
|
| `metadata` | Supports custom metadata on emails |
|
|
100
120
|
| `priority` | Supports email priority levels |
|
|
101
121
|
|
|
102
|
-
|
|
122
|
+
The interface does not say which template kinds `templates` covers. `@antelopejs/nodemailer` sets it to `true` but renders inline templates only, and answers a provider-hosted template with an unsuccessful response ([AntelopeJS/nodemailer#45](https://github.com/AntelopeJS/nodemailer/issues/45)). A flag is the module's own claim. `@antelopejs/brevo` reports `openTracking`, `clickTracking` and `inlineAttachments` as `true` but applies none of them ([AntelopeJS/brevo#44](https://github.com/AntelopeJS/brevo/issues/44)).
|
|
123
|
+
|
|
124
|
+
Each implementing module decides which fields it applies. A module can drop a field that it does not apply and still report the send as successful. To keep your code portable, check the capabilities before you use an optional feature:
|
|
103
125
|
|
|
104
126
|
```ts
|
|
105
|
-
import {
|
|
127
|
+
import {
|
|
128
|
+
GetCapabilities,
|
|
129
|
+
Send,
|
|
130
|
+
type EmailParams,
|
|
131
|
+
} from "@antelopejs/interface-email";
|
|
106
132
|
|
|
107
133
|
const caps = await GetCapabilities();
|
|
108
134
|
|
|
109
|
-
const params:
|
|
135
|
+
const params: EmailParams = {
|
|
110
136
|
to: "user@example.com",
|
|
111
137
|
subject: "Hello",
|
|
112
138
|
html: "<p>Welcome!</p>",
|
|
113
139
|
};
|
|
114
140
|
|
|
115
141
|
if (caps.features.scheduling) {
|
|
116
|
-
params.schedule = { sendAt: new Date(
|
|
142
|
+
params.schedule = { sendAt: new Date(Date.now() + 60 * 60 * 1000) };
|
|
117
143
|
}
|
|
118
144
|
|
|
119
145
|
await Send(params);
|
|
120
146
|
```
|
|
121
147
|
|
|
122
|
-
|
|
148
|
+
The capability limits `maxRecipients`, `maxBatchSize`, `maxAttachmentSize`, and `maxEmailSize` are optional. Size limits are in bytes. An absent limit does not mean that capacity is unlimited, so check your provider configuration. `version` is optional provider metadata.
|
|
149
|
+
|
|
150
|
+
## Next steps
|
|
123
151
|
|
|
124
|
-
- [Sending
|
|
125
|
-
- [Attachments](./3.attachments.md)
|
|
152
|
+
- [Sending emails](./2.sending-emails.md) lists every email parameter and covers templates, batch sending, and delivery responses.
|
|
153
|
+
- [Attachments](./3.attachments.md) shows how to attach files from buffers, base64 strings, file paths, or URLs.
|
package/docs/2.sending-emails.md
CHANGED
|
@@ -1,10 +1,16 @@
|
|
|
1
|
-
|
|
1
|
+
---
|
|
2
|
+
title: Sending emails
|
|
3
|
+
description: Reference for Send, SendTemplate, and SendBatch, with every EmailParams field, the template and batch parameters, and the response and error types.
|
|
4
|
+
mode: reference
|
|
5
|
+
---
|
|
2
6
|
|
|
3
|
-
The interface
|
|
7
|
+
The interface has three sending functions: `Send` for single emails, `SendTemplate` for template-based emails, and `SendBatch` for multiple emails in one operation.
|
|
4
8
|
|
|
5
|
-
|
|
9
|
+
For a first message, start with [`EmailParams`](#the-emailparams-object), then read 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
10
|
|
|
7
|
-
The `
|
|
11
|
+
## The `EmailParams` object
|
|
12
|
+
|
|
13
|
+
The `Send` function takes an `EmailParams` object. Only `to` and `subject` are required. Every other field is optional.
|
|
8
14
|
|
|
9
15
|
```ts
|
|
10
16
|
import { Send } from "@antelopejs/interface-email";
|
|
@@ -15,36 +21,47 @@ const response = await Send({
|
|
|
15
21
|
html: "<h1>Welcome!</h1><p>Thanks for joining.</p>",
|
|
16
22
|
text: "Welcome! Thanks for joining.",
|
|
17
23
|
});
|
|
24
|
+
|
|
25
|
+
if (!response.success) {
|
|
26
|
+
throw new Error(
|
|
27
|
+
response.error?.message ?? "The provider did not accept the email",
|
|
28
|
+
);
|
|
29
|
+
}
|
|
30
|
+
console.log(response.status); // Acceptance is not proof of inbox delivery.
|
|
18
31
|
```
|
|
19
32
|
|
|
20
|
-
|
|
33
|
+
This example uses the configured default sender. Handle rejected promises at your
|
|
34
|
+
application boundary as well as unsuccessful responses. [Email response](#email-response)
|
|
35
|
+
lists the optional fields and the precautions for retries.
|
|
36
|
+
|
|
37
|
+
### Required fields
|
|
21
38
|
|
|
22
39
|
| Field | Type | Description |
|
|
23
40
|
| --------- | -------------------------------- | ---------------------- |
|
|
24
41
|
| `to` | `EmailAddress \| EmailAddress[]` | One or more recipients |
|
|
25
42
|
| `subject` | `string` | The email subject line |
|
|
26
43
|
|
|
27
|
-
### Content
|
|
44
|
+
### Content fields
|
|
28
45
|
|
|
29
|
-
Provide
|
|
46
|
+
Provide `text`, `html`, or both, even though the TypeScript type makes both optional. With both, readers get a plain-text alternative to the HTML.
|
|
30
47
|
|
|
31
48
|
| Field | Type | Description |
|
|
32
49
|
| ------ | -------- | --------------- |
|
|
33
50
|
| `text` | `string` | Plain text body |
|
|
34
51
|
| `html` | `string` | HTML body |
|
|
35
52
|
|
|
36
|
-
### Address
|
|
53
|
+
### Address fields
|
|
37
54
|
|
|
38
|
-
| Field | Type | Description
|
|
39
|
-
| --------- | -------------------------------- |
|
|
40
|
-
| `from` | `EmailAddress` | Sender address (
|
|
41
|
-
| `replyTo` | `EmailAddress \| EmailAddress[]` |
|
|
42
|
-
| `cc` | `EmailAddress \| EmailAddress[]` | CC recipients
|
|
43
|
-
| `bcc` | `EmailAddress \| EmailAddress[]` | BCC recipients
|
|
55
|
+
| Field | Type | Description |
|
|
56
|
+
| --------- | -------------------------------- | ------------------------------------------------ |
|
|
57
|
+
| `from` | `EmailAddress` | Sender address (the provider default if omitted) |
|
|
58
|
+
| `replyTo` | `EmailAddress \| EmailAddress[]` | One or more reply-to addresses |
|
|
59
|
+
| `cc` | `EmailAddress \| EmailAddress[]` | CC recipients |
|
|
60
|
+
| `bcc` | `EmailAddress \| EmailAddress[]` | BCC recipients |
|
|
44
61
|
|
|
45
|
-
### Threading
|
|
62
|
+
### Threading fields
|
|
46
63
|
|
|
47
|
-
|
|
64
|
+
These fields place an email in an existing thread:
|
|
48
65
|
|
|
49
66
|
| Field | Type | Description |
|
|
50
67
|
| ------------ | -------------------- | ---------------------------------------- |
|
|
@@ -64,15 +81,15 @@ await Send({
|
|
|
64
81
|
});
|
|
65
82
|
```
|
|
66
83
|
|
|
67
|
-
## Email
|
|
84
|
+
## Email priority
|
|
68
85
|
|
|
69
|
-
The `priority` field
|
|
86
|
+
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 you rely on this option. The interface sets no default priority.
|
|
70
87
|
|
|
71
|
-
| Value | Description
|
|
72
|
-
| ---------- |
|
|
73
|
-
| `"high"` |
|
|
74
|
-
| `"normal"` | Standard delivery priority
|
|
75
|
-
| `"low"` | Non-urgent emails such as newsletters
|
|
88
|
+
| Value | Description |
|
|
89
|
+
| ---------- | ------------------------------------------- |
|
|
90
|
+
| `"high"` | Request high priority for an urgent message |
|
|
91
|
+
| `"normal"` | Standard delivery priority |
|
|
92
|
+
| `"low"` | Non-urgent emails such as newsletters |
|
|
76
93
|
|
|
77
94
|
```ts
|
|
78
95
|
import { Send } from "@antelopejs/interface-email";
|
|
@@ -85,9 +102,9 @@ await Send({
|
|
|
85
102
|
});
|
|
86
103
|
```
|
|
87
104
|
|
|
88
|
-
## Tracking
|
|
105
|
+
## Tracking options
|
|
89
106
|
|
|
90
|
-
The `tracking` field
|
|
107
|
+
The `tracking` field sets open and click tracking through the `TrackingOptions` interface. Whether a provider applies it is provider behaviour. `@antelopejs/brevo` reports `openTracking` and `clickTracking` as `true` in its capabilities, but it does not send `tracking` to the Brevo API, so the field has no effect there ([AntelopeJS/brevo#44](https://github.com/AntelopeJS/brevo/issues/44)).
|
|
91
108
|
|
|
92
109
|
| Field | Type | Description |
|
|
93
110
|
| ---------------- | --------- | ---------------------------------------- |
|
|
@@ -111,14 +128,14 @@ await Send({
|
|
|
111
128
|
});
|
|
112
129
|
```
|
|
113
130
|
|
|
114
|
-
## Schedule
|
|
131
|
+
## Schedule options
|
|
115
132
|
|
|
116
|
-
The `schedule` field delays
|
|
133
|
+
The `schedule` field delays delivery to a given time through the `ScheduleOptions` interface.
|
|
117
134
|
|
|
118
135
|
| Field | Type | Description |
|
|
119
136
|
| ---------- | ---------------- | ------------------------------------------------------- |
|
|
120
137
|
| `sendAt` | `Date \| string` | When to send the email (ISO 8601 string or Date object) |
|
|
121
|
-
| `timezone` | `string` | IANA timezone identifier
|
|
138
|
+
| `timezone` | `string` | IANA timezone identifier, such as `"Europe/Paris"` |
|
|
122
139
|
|
|
123
140
|
```ts
|
|
124
141
|
import { Send } from "@antelopejs/interface-email";
|
|
@@ -128,17 +145,19 @@ await Send({
|
|
|
128
145
|
subject: "Monday Standup Reminder",
|
|
129
146
|
text: "Standup in 15 minutes.",
|
|
130
147
|
schedule: {
|
|
131
|
-
sendAt: new Date("
|
|
148
|
+
sendAt: new Date("2027-04-05T06:45:00Z"),
|
|
132
149
|
timezone: "Europe/Paris",
|
|
133
150
|
},
|
|
134
151
|
});
|
|
135
152
|
```
|
|
136
153
|
|
|
137
|
-
|
|
154
|
+
Before you schedule a message, check `(await GetCapabilities()).features.scheduling` to confirm that the provider supports it.
|
|
155
|
+
|
|
156
|
+
Await `GetCapabilities()` before you read its flags. Give an explicit UTC offset when you construct a `Date`. The example is 08:45 in Paris on that date. A `timezone` field does not change how JavaScript parses a date string that has no timezone.
|
|
138
157
|
|
|
139
|
-
## Tags and
|
|
158
|
+
## Tags and metadata
|
|
140
159
|
|
|
141
|
-
Tags and metadata
|
|
160
|
+
Tags and metadata label emails for analytics and tracking.
|
|
142
161
|
|
|
143
162
|
| Field | Type | Description |
|
|
144
163
|
| ---------- | ------------------------ | ------------------------------------------------- |
|
|
@@ -160,9 +179,9 @@ await Send({
|
|
|
160
179
|
});
|
|
161
180
|
```
|
|
162
181
|
|
|
163
|
-
## Provider
|
|
182
|
+
## Provider options
|
|
164
183
|
|
|
165
|
-
The `providerOptions` field passes provider-specific
|
|
184
|
+
The `providerOptions` field passes provider-specific settings that the interface does not define. Use it sparingly, because it makes the code less portable. The value is a `JsonObject`. Every nested value is a string, a number, a boolean, `null`, an array of such values, or an object of them. A key whose value is `undefined` is accepted, so you can pass an optional field as is. `JSON.stringify` drops such a key. The implementing module decides which keys it reads. Neither `@antelopejs/nodemailer` nor `@antelopejs/brevo` reads `providerOptions`.
|
|
166
185
|
|
|
167
186
|
```ts
|
|
168
187
|
import { Send } from "@antelopejs/interface-email";
|
|
@@ -177,13 +196,13 @@ await Send({
|
|
|
177
196
|
});
|
|
178
197
|
```
|
|
179
198
|
|
|
180
|
-
## Template
|
|
199
|
+
## Template emails
|
|
181
200
|
|
|
182
|
-
The `SendTemplate` function renders an email from a template before
|
|
201
|
+
The `SendTemplate` function renders an email from a template before it sends. A template is either hosted by the provider or defined inline.
|
|
183
202
|
|
|
184
203
|
### Provider-hosted templates
|
|
185
204
|
|
|
186
|
-
|
|
205
|
+
A `ProviderTemplate` names a template stored in the provider's system by its ID. The ID format is provider behaviour. `@antelopejs/brevo` expects a numeric ID, and `@antelopejs/nodemailer` does not support provider-hosted templates.
|
|
187
206
|
|
|
188
207
|
```ts
|
|
189
208
|
import { SendTemplate } from "@antelopejs/interface-email";
|
|
@@ -200,7 +219,7 @@ const response = await SendTemplate({
|
|
|
200
219
|
|
|
201
220
|
### Inline templates
|
|
202
221
|
|
|
203
|
-
|
|
222
|
+
An `InlineTemplate` carries the template content, its `type`, and an optional `engine` hint:
|
|
204
223
|
|
|
205
224
|
```ts
|
|
206
225
|
import { SendTemplate } from "@antelopejs/interface-email";
|
|
@@ -216,9 +235,11 @@ const response = await SendTemplate({
|
|
|
216
235
|
});
|
|
217
236
|
```
|
|
218
237
|
|
|
238
|
+
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 before you send, for example with `toISOString()`. TypeScript rejects an object declared with an `interface`, because it has no index signature. Declare it with a `type` alias, or spread it into a literal (`{ ...user }`).
|
|
239
|
+
|
|
219
240
|
### Per-recipient variables
|
|
220
241
|
|
|
221
|
-
|
|
242
|
+
To give each recipient their own values, key `recipientVariables` by email address:
|
|
222
243
|
|
|
223
244
|
```ts
|
|
224
245
|
import { SendTemplate } from "@antelopejs/interface-email";
|
|
@@ -234,9 +255,9 @@ await SendTemplate({
|
|
|
234
255
|
});
|
|
235
256
|
```
|
|
236
257
|
|
|
237
|
-
## Batch
|
|
258
|
+
## Batch sending
|
|
238
259
|
|
|
239
|
-
The `SendBatch` function sends multiple emails in a single operation. Each message in the batch
|
|
260
|
+
The `SendBatch` function sends multiple emails in a single operation. Each message in the batch is an `EmailParams` object with an optional `batchId` to match it with its response.
|
|
240
261
|
|
|
241
262
|
```ts
|
|
242
263
|
import { SendBatch } from "@antelopejs/interface-email";
|
|
@@ -246,13 +267,13 @@ const result = await SendBatch({
|
|
|
246
267
|
{
|
|
247
268
|
to: "alice@example.com",
|
|
248
269
|
subject: "Your invoice",
|
|
249
|
-
html: "<p>
|
|
270
|
+
html: "<p>Your invoice #001 is ready in your account.</p>",
|
|
250
271
|
batchId: "invoice-001",
|
|
251
272
|
},
|
|
252
273
|
{
|
|
253
274
|
to: "bob@example.com",
|
|
254
275
|
subject: "Your invoice",
|
|
255
|
-
html: "<p>
|
|
276
|
+
html: "<p>Your invoice #002 is ready in your account.</p>",
|
|
256
277
|
batchId: "invoice-002",
|
|
257
278
|
},
|
|
258
279
|
],
|
|
@@ -266,13 +287,13 @@ const result = await SendBatch({
|
|
|
266
287
|
|
|
267
288
|
### Batch defaults
|
|
268
289
|
|
|
269
|
-
The `defaults` field
|
|
290
|
+
The `defaults` field holds values shared by all messages. The interface leaves the merge to the implementing module. `@antelopejs/nodemailer` spreads `defaults` under each message, so a field set on the message wins. `@antelopejs/brevo` merges recipients, subject, body, and attachments the same way, but takes the sender, `tags`, and `schedule` of the batch from `defaults` only.
|
|
270
291
|
|
|
271
292
|
### Error handling in batches
|
|
272
293
|
|
|
273
|
-
When `continueOnError` is `true` (the default), the batch
|
|
294
|
+
When `continueOnError` is `true` (the default), the batch keeps sending after a message fails. The response has one result per message:
|
|
274
295
|
|
|
275
|
-
```ts
|
|
296
|
+
```ts fragment
|
|
276
297
|
console.log(result.total); // Total messages in batch
|
|
277
298
|
console.log(result.successful); // Number sent successfully
|
|
278
299
|
console.log(result.failed); // Number that failed
|
|
@@ -287,7 +308,7 @@ for (const res of result.responses) {
|
|
|
287
308
|
}
|
|
288
309
|
```
|
|
289
310
|
|
|
290
|
-
## Email
|
|
311
|
+
## Email response
|
|
291
312
|
|
|
292
313
|
The `Send` and `SendTemplate` functions return an `EmailResponse` object:
|
|
293
314
|
|
|
@@ -302,9 +323,11 @@ The `Send` and `SendTemplate` functions return an `EmailResponse` object:
|
|
|
302
323
|
|
|
303
324
|
The `EmailStatus` type includes these values: `"queued"`, `"sent"`, `"delivered"`, `"failed"`, `"rejected"`, `"scheduled"`, and `"unknown"`.
|
|
304
325
|
|
|
326
|
+
Only `success` and `status` are required on `EmailResponse`. Message IDs, errors, timestamps, and provider names can be absent. In a batch, each result also has an `index` into the original messages and a `recipient`. Its `batchId` is optional. The batch-level `success` is true only when every message succeeds.
|
|
327
|
+
|
|
305
328
|
### Error handling
|
|
306
329
|
|
|
307
|
-
When `success` is `false`, the `error` field
|
|
330
|
+
When `success` is `false`, read the optional `error` field for an `EmailError` object:
|
|
308
331
|
|
|
309
332
|
```ts
|
|
310
333
|
import { Send } from "@antelopejs/interface-email";
|
|
@@ -319,11 +342,13 @@ if (!response.success && response.error) {
|
|
|
319
342
|
console.error(`Error [${response.error.code}]: ${response.error.message}`);
|
|
320
343
|
|
|
321
344
|
if (response.error.retryable) {
|
|
322
|
-
//
|
|
345
|
+
// A retry may succeed; apply your retry and duplicate-send policy.
|
|
323
346
|
}
|
|
324
347
|
}
|
|
325
348
|
```
|
|
326
349
|
|
|
327
|
-
|
|
350
|
+
`retryable` is a hint. It does not make a retry safe to repeat, because a retry can send another message and the interface defines no deduplication key. `EmailError` requires `code` and `message`, and has the optional `field` and `retryable`. Also handle rejected promises from the configured implementation.
|
|
351
|
+
|
|
352
|
+
## Next steps
|
|
328
353
|
|
|
329
|
-
- [Attachments](./3.attachments.md)
|
|
354
|
+
- [Attachments](./3.attachments.md) shows how to attach files from buffers, base64 strings, file paths, or URLs.
|
package/docs/3.attachments.md
CHANGED
|
@@ -1,33 +1,40 @@
|
|
|
1
|
-
|
|
1
|
+
---
|
|
2
|
+
title: Attachments
|
|
3
|
+
description: Reference for the four attachment types, their shared BaseAttachment fields, inline images, and the Attachment union.
|
|
4
|
+
mode: reference
|
|
5
|
+
---
|
|
2
6
|
|
|
3
|
-
The interface
|
|
7
|
+
The interface has four attachment types, one per source of file data. All four share the `BaseAttachment` fields. You pass them in the `attachments` field of `EmailParams` or `TemplateEmailParams`.
|
|
4
8
|
|
|
5
|
-
##
|
|
9
|
+
## Choose the source of the bytes
|
|
6
10
|
|
|
7
|
-
|
|
11
|
+
| You already have | Use | Supply |
|
|
12
|
+
| -------------------------------------- | ------------------ | ------------------------------------------ |
|
|
13
|
+
| Bytes in memory | `BufferAttachment` | `content: Buffer` |
|
|
14
|
+
| Base64-encoded bytes | `Base64Attachment` | `content: string` and `encoding: "base64"` |
|
|
15
|
+
| A file available to the implementation | `PathAttachment` | `path` |
|
|
16
|
+
| A file reachable by the implementation | `UrlAttachment` | `url` |
|
|
8
17
|
|
|
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 |
|
|
18
|
+
A path is a path on the server that runs the implementation, not on the recipient's computer. Use trusted or validated paths and URLs. Do not let untrusted input pick arbitrary local files or internal network addresses. Check the provider's size limits before you send.
|
|
15
19
|
|
|
16
|
-
## Attachment
|
|
20
|
+
## Attachment types
|
|
17
21
|
|
|
18
22
|
### `BufferAttachment`
|
|
19
23
|
|
|
20
|
-
Use `BufferAttachment` when
|
|
24
|
+
Use `BufferAttachment` when the file data is in memory as a Node.js `Buffer`, for example a file you generate or read from a stream.
|
|
21
25
|
|
|
22
26
|
```ts
|
|
23
|
-
import { Send, BufferAttachment } from "@antelopejs/interface-email";
|
|
27
|
+
import { Send, type BufferAttachment } from "@antelopejs/interface-email";
|
|
24
28
|
|
|
25
|
-
const
|
|
29
|
+
const reportBuffer = Buffer.from(
|
|
30
|
+
"Quarterly report\nRevenue: 12500 EUR\n",
|
|
31
|
+
"utf8",
|
|
32
|
+
);
|
|
26
33
|
|
|
27
34
|
const attachment: BufferAttachment = {
|
|
28
|
-
filename: "report.
|
|
29
|
-
contentType: "
|
|
30
|
-
content:
|
|
35
|
+
filename: "report.txt",
|
|
36
|
+
contentType: "text/plain",
|
|
37
|
+
content: reportBuffer,
|
|
31
38
|
};
|
|
32
39
|
|
|
33
40
|
await Send({
|
|
@@ -40,29 +47,29 @@ await Send({
|
|
|
40
47
|
|
|
41
48
|
### `Base64Attachment`
|
|
42
49
|
|
|
43
|
-
Use `Base64Attachment` when
|
|
50
|
+
Use `Base64Attachment` when the file data is a base64 string. The `encoding` field is `"base64"`, and it tells this type apart from a `BufferAttachment`.
|
|
44
51
|
|
|
45
52
|
```ts
|
|
46
53
|
import { Send, Base64Attachment } from "@antelopejs/interface-email";
|
|
47
54
|
|
|
48
55
|
const attachment: Base64Attachment = {
|
|
49
|
-
filename: "
|
|
50
|
-
contentType: "
|
|
51
|
-
content: "
|
|
56
|
+
filename: "notes.txt",
|
|
57
|
+
contentType: "text/plain",
|
|
58
|
+
content: "SGVsbG8h", // Base64 for "Hello!"
|
|
52
59
|
encoding: "base64",
|
|
53
60
|
};
|
|
54
61
|
|
|
55
62
|
await Send({
|
|
56
63
|
to: "user@example.com",
|
|
57
|
-
subject: "
|
|
58
|
-
text: "
|
|
64
|
+
subject: "Meeting Notes",
|
|
65
|
+
text: "Notes attached.",
|
|
59
66
|
attachments: [attachment],
|
|
60
67
|
});
|
|
61
68
|
```
|
|
62
69
|
|
|
63
70
|
### `PathAttachment`
|
|
64
71
|
|
|
65
|
-
Use `PathAttachment` to attach a file from the local filesystem by its path.
|
|
72
|
+
Use `PathAttachment` to attach a file from the local filesystem by its path. Reading the file is provider behaviour. `@antelopejs/nodemailer` passes the path to Nodemailer, which reads the file when it sends. `@antelopejs/brevo` does not support `PathAttachment`. It logs an error and sends the message without that file.
|
|
66
73
|
|
|
67
74
|
```ts
|
|
68
75
|
import { Send, PathAttachment } from "@antelopejs/interface-email";
|
|
@@ -83,7 +90,7 @@ await Send({
|
|
|
83
90
|
|
|
84
91
|
### `UrlAttachment`
|
|
85
92
|
|
|
86
|
-
Use `UrlAttachment` to attach a file from a remote URL.
|
|
93
|
+
Use `UrlAttachment` to attach a file from a remote URL. Fetching the file is provider behaviour. `@antelopejs/nodemailer` passes the URL to Nodemailer, which fetches it when it sends. `@antelopejs/brevo` passes the URL to the Brevo API.
|
|
87
94
|
|
|
88
95
|
```ts
|
|
89
96
|
import { Send, UrlAttachment } from "@antelopejs/interface-email";
|
|
@@ -102,14 +109,17 @@ await Send({
|
|
|
102
109
|
});
|
|
103
110
|
```
|
|
104
111
|
|
|
105
|
-
## Inline
|
|
112
|
+
## Inline images
|
|
113
|
+
|
|
114
|
+
An inline attachment puts an image in the HTML body through a Content-ID reference. Set `inline` to `true`, give the attachment a `cid` value, then reference it in your HTML with the `cid:` scheme. How the provider applies `inline` and `cid` is provider behaviour. `@antelopejs/nodemailer` passes `cid` to Nodemailer and does not read `inline`. `@antelopejs/brevo` sends neither `cid` nor `inline` to the Brevo API, so the image arrives as a plain attachment ([AntelopeJS/brevo#44](https://github.com/AntelopeJS/brevo/issues/44)).
|
|
106
115
|
|
|
107
|
-
|
|
116
|
+
The following example reads a PNG at `./assets/logo.png`, relative to the working directory of the server. Supply that file before you run it.
|
|
108
117
|
|
|
109
118
|
```ts
|
|
110
|
-
import {
|
|
119
|
+
import { readFile } from "node:fs/promises";
|
|
120
|
+
import { Send } from "@antelopejs/interface-email";
|
|
111
121
|
|
|
112
|
-
const logoBuffer =
|
|
122
|
+
const logoBuffer = await readFile("./assets/logo.png");
|
|
113
123
|
|
|
114
124
|
await Send({
|
|
115
125
|
to: "user@example.com",
|
|
@@ -132,11 +142,11 @@ await Send({
|
|
|
132
142
|
});
|
|
133
143
|
```
|
|
134
144
|
|
|
135
|
-
|
|
145
|
+
`(await GetCapabilities()).features.inlineAttachments` tells you what the implementing module reports, not what it does. `@antelopejs/brevo` reports `true` and still does not inline the image, so test inline images with your provider before you rely on them.
|
|
136
146
|
|
|
137
|
-
## Multiple
|
|
147
|
+
## Multiple attachments
|
|
138
148
|
|
|
139
|
-
The `attachments` field
|
|
149
|
+
The `attachments` field takes an array, so one email can mix attachment types:
|
|
140
150
|
|
|
141
151
|
```ts
|
|
142
152
|
import { Send } from "@antelopejs/interface-email";
|
|
@@ -165,13 +175,31 @@ await Send({
|
|
|
165
175
|
});
|
|
166
176
|
```
|
|
167
177
|
|
|
168
|
-
## The `
|
|
178
|
+
## The `BaseAttachment` interface
|
|
169
179
|
|
|
170
|
-
|
|
180
|
+
Every attachment requires a filename. These shared fields apply to all four types:
|
|
181
|
+
|
|
182
|
+
| Field | Type | Required | Description |
|
|
183
|
+
| ------------- | --------- | -------- | ----------------------------------------------------------------- |
|
|
184
|
+
| `filename` | `string` | Yes | The filename shown to the recipient |
|
|
185
|
+
| `contentType` | `string` | No | MIME type, such as `"application/pdf"` |
|
|
186
|
+
| `cid` | `string` | No | Content-ID for inline images (reference in HTML as `cid:yourCid`) |
|
|
187
|
+
| `inline` | `boolean` | No | If `true`, embed in the HTML body instead of attaching as a file |
|
|
188
|
+
|
|
189
|
+
## The `Attachment` union type
|
|
190
|
+
|
|
191
|
+
The `Attachment` type is the union of the four attachment interfaces:
|
|
171
192
|
|
|
172
193
|
```ts
|
|
194
|
+
import type {
|
|
195
|
+
Base64Attachment,
|
|
196
|
+
BufferAttachment,
|
|
197
|
+
PathAttachment,
|
|
198
|
+
UrlAttachment,
|
|
199
|
+
} from "@antelopejs/interface-email";
|
|
200
|
+
|
|
173
201
|
type Attachment =
|
|
174
202
|
BufferAttachment | Base64Attachment | PathAttachment | UrlAttachment;
|
|
175
203
|
```
|
|
176
204
|
|
|
177
|
-
When
|
|
205
|
+
When you build attachments at runtime, an `in` check on `encoding`, `path`, or `url` narrows an `Attachment` to one member. An attachment with `content` and no `encoding` is a `BufferAttachment`.
|
|
@@ -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,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@antelopejs/interface-email",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.1.1",
|
|
4
4
|
"description": "AntelopeJS interface for sending email: single, batch and template messages with attachments",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"antelopejs",
|
|
@@ -35,21 +35,32 @@
|
|
|
35
35
|
"provenance": true
|
|
36
36
|
},
|
|
37
37
|
"scripts": {
|
|
38
|
-
"build": "rimraf dist && tsc",
|
|
38
|
+
"build": "rimraf dist && tsc -p tsconfig.build.json",
|
|
39
39
|
"format": "oxfmt .",
|
|
40
40
|
"lint:fix": "oxlint --fix",
|
|
41
41
|
"lint": "oxlint",
|
|
42
42
|
"prepack": "pnpm run build",
|
|
43
43
|
"release": "pnpm run lint && pnpm run prepack && release-it",
|
|
44
44
|
"format:check": "oxfmt --check .",
|
|
45
|
-
"knip": "knip"
|
|
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"
|
|
46
55
|
},
|
|
47
56
|
"devDependencies": {
|
|
57
|
+
"@antelopejs/core": "^1.16.0",
|
|
48
58
|
"@antelopejs/interface-core": ">=0.2.4 <1.0.0",
|
|
49
|
-
"@antelopejs/tooling-configs": "^0.
|
|
59
|
+
"@antelopejs/tooling-configs": "^0.2.17",
|
|
50
60
|
"@types/node": "^22.19.15",
|
|
51
61
|
"eslint-plugin-perfectionist": "^5.11.0",
|
|
52
62
|
"knip": "^6.34.0",
|
|
63
|
+
"lefthook": "^2.2.2",
|
|
53
64
|
"oxfmt": "^0.66.0",
|
|
54
65
|
"oxlint": "1.81.0",
|
|
55
66
|
"oxlint-tsgolint": "^7.0.2001",
|
|
@@ -65,6 +76,9 @@
|
|
|
65
76
|
"antelopeJs": {
|
|
66
77
|
"skills": [
|
|
67
78
|
"./skills"
|
|
68
|
-
]
|
|
79
|
+
],
|
|
80
|
+
"docs": {
|
|
81
|
+
"standard": true
|
|
82
|
+
}
|
|
69
83
|
}
|
|
70
84
|
}
|
|
@@ -56,7 +56,7 @@ if (!response.success) {
|
|
|
56
56
|
}
|
|
57
57
|
```
|
|
58
58
|
|
|
59
|
-
`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.
|
|
60
60
|
|
|
61
61
|
## Providing
|
|
62
62
|
|
|
@@ -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
|
+
}
|