@antelopejs/interface-email 0.1.0 → 0.2.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 +17 -12
- package/dist/index.d.ts +3 -0
- package/dist/index.js.map +1 -1
- package/docs/1.introduction.md +40 -33
- package/docs/2.sending-emails.md +54 -50
- package/docs/3.attachments.md +31 -20
- package/docs/tsconfig.json +7 -0
- package/package.json +10 -6
- package/skills/email-interface/SKILL.md +2 -1
package/README.md
CHANGED
|
@@ -1,27 +1,30 @@
|
|
|
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.
|
|
11
11
|
|
|
12
|
+
Part of [AntelopeJS](https://github.com/AntelopeJS/antelopejs). Used by [AntelopeJS DMS](https://github.com/AntelopeJS/dms), the open-source back office for your PostgreSQL, MongoDB or RethinkDB database.
|
|
13
|
+
|
|
12
14
|
## What it offers
|
|
13
15
|
|
|
14
16
|
- `Send` sends one message with text or HTML, recipients, threading headers and attachments.
|
|
15
17
|
- `SendBatch` sends several messages in one call, with shared defaults.
|
|
16
18
|
- `SendTemplate` renders a provider template or an inline template with variables.
|
|
17
19
|
- `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
|
|
20
|
+
- `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
21
|
|
|
20
22
|
## Implementations
|
|
21
23
|
|
|
22
24
|
| Module | Notes |
|
|
23
25
|
| -------------------------------------------------------------------- | ----------------------- |
|
|
24
26
|
| [`@antelopejs/nodemailer`](https://github.com/AntelopeJS/nodemailer) | SMTP through Nodemailer |
|
|
27
|
+
| [`@antelopejs/brevo`](https://github.com/AntelopeJS/brevo) | Brevo HTTP API |
|
|
25
28
|
|
|
26
29
|
## Install
|
|
27
30
|
|
|
@@ -65,14 +68,16 @@ export async function sendWelcome(address: string) {
|
|
|
65
68
|
|
|
66
69
|
## Compatibility
|
|
67
70
|
|
|
68
|
-
<!-- docs-compat:
|
|
71
|
+
<!-- antelopejs-docs-compat:start -->
|
|
72
|
+
|
|
73
|
+
| Package | Supported | Tested with |
|
|
74
|
+
| ---------------------------- | ---------------- | ----------- |
|
|
75
|
+
| `@antelopejs/interface-core` | `>=0.2.4 <1.0.0` | `0.2.4` |
|
|
69
76
|
|
|
70
|
-
|
|
71
|
-
| ---------------------------- | ---------------- |
|
|
72
|
-
| `@antelopejs/interface-core` | `>=0.2.4 <1.0.0` |
|
|
77
|
+
<!-- antelopejs-docs-compat:end -->
|
|
73
78
|
|
|
74
|
-
|
|
75
|
-
`@antelopejs/core` peer range
|
|
79
|
+
The table repeats the peer range in `package.json`. The package declares no
|
|
80
|
+
`@antelopejs/core` peer range, so check the requirements of the implementing module too.
|
|
76
81
|
|
|
77
82
|
## Contributing
|
|
78
83
|
|
package/dist/index.d.ts
CHANGED
|
@@ -200,7 +200,10 @@ export interface BatchEmailResponse {
|
|
|
200
200
|
/** Supported features of the email provider */
|
|
201
201
|
export interface ProviderFeatures {
|
|
202
202
|
batch: boolean;
|
|
203
|
+
/** SendTemplate works for at least inline templates */
|
|
203
204
|
templates: boolean;
|
|
205
|
+
/** SendTemplate accepts a ProviderTemplate (a template stored by the provider, named by id) */
|
|
206
|
+
providerTemplates: boolean;
|
|
204
207
|
scheduling: boolean;
|
|
205
208
|
openTracking: boolean;
|
|
206
209
|
clickTracking: boolean;
|
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;AAqS/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,6 +1,10 @@
|
|
|
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
|
-
Send transactional messages, templates, and batches through one provider
|
|
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
|
|
|
@@ -12,13 +16,13 @@ Send transactional messages, templates, and batches through one provider-neutral
|
|
|
12
16
|
| Include a document or inline image | [Attachments](./3.attachments.md) |
|
|
13
17
|
| Keep optional features portable | [Provider capabilities](#provider-capabilities) |
|
|
14
18
|
|
|
15
|
-
{width="480"}
|
|
16
20
|
|
|
17
|
-
**Before sending
|
|
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.
|
|
18
22
|
|
|
19
|
-
## Core
|
|
23
|
+
## Core concepts
|
|
20
24
|
|
|
21
|
-
The interface
|
|
25
|
+
The interface splits email operations into four functions:
|
|
22
26
|
|
|
23
27
|
| Function | Purpose |
|
|
24
28
|
| ----------------- | -------------------------------------------------------------- |
|
|
@@ -27,7 +31,7 @@ The interface separates email operations into four functions:
|
|
|
27
31
|
| `SendTemplate` | Send an email rendered from a template |
|
|
28
32
|
| `GetCapabilities` | Query the provider's supported features and limits |
|
|
29
33
|
|
|
30
|
-
The sending functions return typed delivery responses. `GetCapabilities` returns feature flags and limits instead. A successful send means the provider accepted the request
|
|
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.
|
|
31
35
|
|
|
32
36
|
## Installation
|
|
33
37
|
|
|
@@ -35,9 +39,9 @@ The sending functions return typed delivery responses. `GetCapabilities` returns
|
|
|
35
39
|
npm install @antelopejs/interface-email
|
|
36
40
|
```
|
|
37
41
|
|
|
38
|
-
## Email
|
|
42
|
+
## Email address types
|
|
39
43
|
|
|
40
|
-
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.
|
|
41
45
|
|
|
42
46
|
### String format
|
|
43
47
|
|
|
@@ -51,7 +55,7 @@ const to: EmailAddress = "user@example.com";
|
|
|
51
55
|
|
|
52
56
|
### Object format with `EmailAddressObject`
|
|
53
57
|
|
|
54
|
-
Use the object
|
|
58
|
+
Use the object form to add a display name to the address:
|
|
55
59
|
|
|
56
60
|
```ts
|
|
57
61
|
import { EmailAddressObject } from "@antelopejs/interface-email";
|
|
@@ -64,7 +68,7 @@ const sender: EmailAddressObject = {
|
|
|
64
68
|
|
|
65
69
|
### The `EmailAddress` union type
|
|
66
70
|
|
|
67
|
-
|
|
71
|
+
`EmailAddress` is the union of both forms. Every address field in the interface accepts either form:
|
|
68
72
|
|
|
69
73
|
```ts
|
|
70
74
|
import { EmailAddress } from "@antelopejs/interface-email";
|
|
@@ -74,7 +78,7 @@ const simple: EmailAddress = "hello@example.com";
|
|
|
74
78
|
const detailed: EmailAddress = { email: "hello@example.com", name: "Hello" };
|
|
75
79
|
```
|
|
76
80
|
|
|
77
|
-
|
|
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.
|
|
78
82
|
|
|
79
83
|
```ts
|
|
80
84
|
import { Send } from "@antelopejs/interface-email";
|
|
@@ -86,36 +90,39 @@ await Send({
|
|
|
86
90
|
});
|
|
87
91
|
```
|
|
88
92
|
|
|
89
|
-
## Provider
|
|
93
|
+
## Provider capabilities
|
|
90
94
|
|
|
91
|
-
|
|
95
|
+
Providers differ in what they support. `GetCapabilities` returns a `ProviderCapabilities` object with the provider's name, limits, and supported features.
|
|
92
96
|
|
|
93
97
|
```ts
|
|
94
98
|
import { GetCapabilities } from "@antelopejs/interface-email";
|
|
95
99
|
|
|
96
100
|
const capabilities = await GetCapabilities();
|
|
97
101
|
|
|
98
|
-
console.log(capabilities.name); //
|
|
102
|
+
console.log(capabilities.name); // "nodemailer" with @antelopejs/nodemailer
|
|
99
103
|
console.log(capabilities.features.batch); // true or false
|
|
100
104
|
console.log(capabilities.features.scheduling); // true or false
|
|
101
|
-
console.log(capabilities.maxRecipients); //
|
|
105
|
+
console.log(capabilities.maxRecipients); // undefined when the provider reports no limit
|
|
102
106
|
```
|
|
103
107
|
|
|
104
|
-
The `ProviderFeatures` object
|
|
108
|
+
The `ProviderFeatures` object has these flags:
|
|
105
109
|
|
|
106
|
-
| Feature | Description
|
|
107
|
-
| ------------------- |
|
|
108
|
-
| `batch` | Supports sending multiple emails in one request
|
|
109
|
-
| `templates` |
|
|
110
|
-
| `
|
|
111
|
-
| `
|
|
112
|
-
| `
|
|
113
|
-
| `
|
|
114
|
-
| `
|
|
115
|
-
| `
|
|
116
|
-
| `
|
|
110
|
+
| Feature | Description |
|
|
111
|
+
| ------------------- | -------------------------------------------------------------------------------------------- |
|
|
112
|
+
| `batch` | Supports sending multiple emails in one request |
|
|
113
|
+
| `templates` | `SendTemplate` works for at least inline templates |
|
|
114
|
+
| `providerTemplates` | `SendTemplate` accepts a `ProviderTemplate` (a template stored by the provider, named by id) |
|
|
115
|
+
| `scheduling` | Supports delayed email delivery |
|
|
116
|
+
| `openTracking` | Tracks when recipients open emails |
|
|
117
|
+
| `clickTracking` | Tracks when recipients click links |
|
|
118
|
+
| `inlineAttachments` | Supports inline, embedded images |
|
|
119
|
+
| `tags` | Supports email tagging for analytics |
|
|
120
|
+
| `metadata` | Supports custom metadata on emails |
|
|
121
|
+
| `priority` | Supports email priority levels |
|
|
117
122
|
|
|
118
|
-
Check
|
|
123
|
+
Check `providerTemplates` before you pass a `ProviderTemplate`: `templates` alone promises only inline templates. A provider built before this flag omits it, so treat a missing `providerTemplates` as `false`. `@antelopejs/nodemailer` releases that predate the flag set `templates` to `true`, render inline templates only, and answer 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)).
|
|
124
|
+
|
|
125
|
+
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:
|
|
119
126
|
|
|
120
127
|
```ts
|
|
121
128
|
import {
|
|
@@ -139,9 +146,9 @@ if (caps.features.scheduling) {
|
|
|
139
146
|
await Send(params);
|
|
140
147
|
```
|
|
141
148
|
|
|
142
|
-
|
|
149
|
+
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.
|
|
143
150
|
|
|
144
|
-
## Next
|
|
151
|
+
## Next steps
|
|
145
152
|
|
|
146
|
-
- [Sending
|
|
147
|
-
- [Attachments](./3.attachments.md)
|
|
153
|
+
- [Sending emails](./2.sending-emails.md) lists every email parameter and covers templates, batch sending, and delivery responses.
|
|
154
|
+
- [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,12 +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
|
-
For a first message, start with [`EmailParams`](#the-emailparams-object), then
|
|
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 `EmailParams`
|
|
11
|
+
## The `EmailParams` object
|
|
8
12
|
|
|
9
|
-
The `Send` function
|
|
13
|
+
The `Send` function takes an `EmailParams` object. Only `to` and `subject` are required. Every other field is optional.
|
|
10
14
|
|
|
11
15
|
```ts
|
|
12
16
|
import { Send } from "@antelopejs/interface-email";
|
|
@@ -27,37 +31,37 @@ console.log(response.status); // Acceptance is not proof of inbox delivery.
|
|
|
27
31
|
```
|
|
28
32
|
|
|
29
33
|
This example uses the configured default sender. Handle rejected promises at your
|
|
30
|
-
application boundary as well as unsuccessful responses.
|
|
31
|
-
|
|
34
|
+
application boundary as well as unsuccessful responses. [Email response](#email-response)
|
|
35
|
+
lists the optional fields and the precautions for retries.
|
|
32
36
|
|
|
33
|
-
### Required
|
|
37
|
+
### Required fields
|
|
34
38
|
|
|
35
39
|
| Field | Type | Description |
|
|
36
40
|
| --------- | -------------------------------- | ---------------------- |
|
|
37
41
|
| `to` | `EmailAddress \| EmailAddress[]` | One or more recipients |
|
|
38
42
|
| `subject` | `string` | The email subject line |
|
|
39
43
|
|
|
40
|
-
### Content
|
|
44
|
+
### Content fields
|
|
41
45
|
|
|
42
|
-
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.
|
|
43
47
|
|
|
44
48
|
| Field | Type | Description |
|
|
45
49
|
| ------ | -------- | --------------- |
|
|
46
50
|
| `text` | `string` | Plain text body |
|
|
47
51
|
| `html` | `string` | HTML body |
|
|
48
52
|
|
|
49
|
-
### Address
|
|
53
|
+
### Address fields
|
|
50
54
|
|
|
51
|
-
| Field | Type | Description
|
|
52
|
-
| --------- | -------------------------------- |
|
|
53
|
-
| `from` | `EmailAddress` | Sender address (
|
|
54
|
-
| `replyTo` | `EmailAddress \| EmailAddress[]` |
|
|
55
|
-
| `cc` | `EmailAddress \| EmailAddress[]` | CC recipients
|
|
56
|
-
| `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 |
|
|
57
61
|
|
|
58
|
-
### Threading
|
|
62
|
+
### Threading fields
|
|
59
63
|
|
|
60
|
-
|
|
64
|
+
These fields place an email in an existing thread:
|
|
61
65
|
|
|
62
66
|
| Field | Type | Description |
|
|
63
67
|
| ------------ | -------------------- | ---------------------------------------- |
|
|
@@ -77,14 +81,14 @@ await Send({
|
|
|
77
81
|
});
|
|
78
82
|
```
|
|
79
83
|
|
|
80
|
-
## Email
|
|
84
|
+
## Email priority
|
|
81
85
|
|
|
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
|
|
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.
|
|
83
87
|
|
|
84
88
|
| Value | Description |
|
|
85
89
|
| ---------- | ------------------------------------------- |
|
|
86
90
|
| `"high"` | Request high priority for an urgent message |
|
|
87
|
-
| `"normal"` | Standard delivery priority
|
|
91
|
+
| `"normal"` | Standard delivery priority |
|
|
88
92
|
| `"low"` | Non-urgent emails such as newsletters |
|
|
89
93
|
|
|
90
94
|
```ts
|
|
@@ -98,9 +102,9 @@ await Send({
|
|
|
98
102
|
});
|
|
99
103
|
```
|
|
100
104
|
|
|
101
|
-
## Tracking
|
|
105
|
+
## Tracking options
|
|
102
106
|
|
|
103
|
-
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)).
|
|
104
108
|
|
|
105
109
|
| Field | Type | Description |
|
|
106
110
|
| ---------------- | --------- | ---------------------------------------- |
|
|
@@ -124,14 +128,14 @@ await Send({
|
|
|
124
128
|
});
|
|
125
129
|
```
|
|
126
130
|
|
|
127
|
-
## Schedule
|
|
131
|
+
## Schedule options
|
|
128
132
|
|
|
129
|
-
The `schedule` field delays
|
|
133
|
+
The `schedule` field delays delivery to a given time through the `ScheduleOptions` interface.
|
|
130
134
|
|
|
131
135
|
| Field | Type | Description |
|
|
132
136
|
| ---------- | ---------------- | ------------------------------------------------------- |
|
|
133
137
|
| `sendAt` | `Date \| string` | When to send the email (ISO 8601 string or Date object) |
|
|
134
|
-
| `timezone` | `string` | IANA timezone identifier
|
|
138
|
+
| `timezone` | `string` | IANA timezone identifier, such as `"Europe/Paris"` |
|
|
135
139
|
|
|
136
140
|
```ts
|
|
137
141
|
import { Send } from "@antelopejs/interface-email";
|
|
@@ -147,13 +151,13 @@ await Send({
|
|
|
147
151
|
});
|
|
148
152
|
```
|
|
149
153
|
|
|
150
|
-
|
|
154
|
+
Before you schedule a message, check `(await GetCapabilities()).features.scheduling` to confirm that the provider supports it.
|
|
151
155
|
|
|
152
|
-
Await `GetCapabilities()` before
|
|
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.
|
|
153
157
|
|
|
154
|
-
## Tags and
|
|
158
|
+
## Tags and metadata
|
|
155
159
|
|
|
156
|
-
Tags and metadata
|
|
160
|
+
Tags and metadata label emails for analytics and tracking.
|
|
157
161
|
|
|
158
162
|
| Field | Type | Description |
|
|
159
163
|
| ---------- | ------------------------ | ------------------------------------------------- |
|
|
@@ -175,9 +179,9 @@ await Send({
|
|
|
175
179
|
});
|
|
176
180
|
```
|
|
177
181
|
|
|
178
|
-
## Provider
|
|
182
|
+
## Provider options
|
|
179
183
|
|
|
180
|
-
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`.
|
|
181
185
|
|
|
182
186
|
```ts
|
|
183
187
|
import { Send } from "@antelopejs/interface-email";
|
|
@@ -192,13 +196,13 @@ await Send({
|
|
|
192
196
|
});
|
|
193
197
|
```
|
|
194
198
|
|
|
195
|
-
## Template
|
|
199
|
+
## Template emails
|
|
196
200
|
|
|
197
|
-
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.
|
|
198
202
|
|
|
199
203
|
### Provider-hosted templates
|
|
200
204
|
|
|
201
|
-
|
|
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. Check `capabilities.features.providerTemplates` before you send one.
|
|
202
206
|
|
|
203
207
|
```ts
|
|
204
208
|
import { SendTemplate } from "@antelopejs/interface-email";
|
|
@@ -215,7 +219,7 @@ const response = await SendTemplate({
|
|
|
215
219
|
|
|
216
220
|
### Inline templates
|
|
217
221
|
|
|
218
|
-
|
|
222
|
+
An `InlineTemplate` carries the template content, its `type`, and an optional `engine` hint:
|
|
219
223
|
|
|
220
224
|
```ts
|
|
221
225
|
import { SendTemplate } from "@antelopejs/interface-email";
|
|
@@ -231,11 +235,11 @@ const response = await SendTemplate({
|
|
|
231
235
|
});
|
|
232
236
|
```
|
|
233
237
|
|
|
234
|
-
Template variables are a `JsonObject` too, so `variables` and each `recipientVariables` entry cannot carry a `Date`, a `Buffer
|
|
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 }`).
|
|
235
239
|
|
|
236
240
|
### Per-recipient variables
|
|
237
241
|
|
|
238
|
-
|
|
242
|
+
To give each recipient their own values, key `recipientVariables` by email address:
|
|
239
243
|
|
|
240
244
|
```ts
|
|
241
245
|
import { SendTemplate } from "@antelopejs/interface-email";
|
|
@@ -251,9 +255,9 @@ await SendTemplate({
|
|
|
251
255
|
});
|
|
252
256
|
```
|
|
253
257
|
|
|
254
|
-
## Batch
|
|
258
|
+
## Batch sending
|
|
255
259
|
|
|
256
|
-
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.
|
|
257
261
|
|
|
258
262
|
```ts
|
|
259
263
|
import { SendBatch } from "@antelopejs/interface-email";
|
|
@@ -283,13 +287,13 @@ const result = await SendBatch({
|
|
|
283
287
|
|
|
284
288
|
### Batch defaults
|
|
285
289
|
|
|
286
|
-
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.
|
|
287
291
|
|
|
288
292
|
### Error handling in batches
|
|
289
293
|
|
|
290
|
-
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:
|
|
291
295
|
|
|
292
|
-
```ts
|
|
296
|
+
```ts fragment
|
|
293
297
|
console.log(result.total); // Total messages in batch
|
|
294
298
|
console.log(result.successful); // Number sent successfully
|
|
295
299
|
console.log(result.failed); // Number that failed
|
|
@@ -304,7 +308,7 @@ for (const res of result.responses) {
|
|
|
304
308
|
}
|
|
305
309
|
```
|
|
306
310
|
|
|
307
|
-
## Email
|
|
311
|
+
## Email response
|
|
308
312
|
|
|
309
313
|
The `Send` and `SendTemplate` functions return an `EmailResponse` object:
|
|
310
314
|
|
|
@@ -319,11 +323,11 @@ The `Send` and `SendTemplate` functions return an `EmailResponse` object:
|
|
|
319
323
|
|
|
320
324
|
The `EmailStatus` type includes these values: `"queued"`, `"sent"`, `"delivered"`, `"failed"`, `"rejected"`, `"scheduled"`, and `"unknown"`.
|
|
321
325
|
|
|
322
|
-
Only `success` and `status` are required on `EmailResponse`. Message IDs, errors, timestamps, and provider names
|
|
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.
|
|
323
327
|
|
|
324
328
|
### Error handling
|
|
325
329
|
|
|
326
|
-
When `success` is `false`,
|
|
330
|
+
When `success` is `false`, read the optional `error` field for an `EmailError` object:
|
|
327
331
|
|
|
328
332
|
```ts
|
|
329
333
|
import { Send } from "@antelopejs/interface-email";
|
|
@@ -343,8 +347,8 @@ if (!response.success && response.error) {
|
|
|
343
347
|
}
|
|
344
348
|
```
|
|
345
349
|
|
|
346
|
-
`retryable` is a hint
|
|
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.
|
|
347
351
|
|
|
348
|
-
## Next
|
|
352
|
+
## Next steps
|
|
349
353
|
|
|
350
|
-
- [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,6 +1,10 @@
|
|
|
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
|
|
|
@@ -11,13 +15,13 @@ The interface supports four attachment types, each suited to a different source
|
|
|
11
15
|
| A file available to the implementation | `PathAttachment` | `path` |
|
|
12
16
|
| A file reachable by the implementation | `UrlAttachment` | `url` |
|
|
13
17
|
|
|
14
|
-
|
|
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
27
|
import { Send, type BufferAttachment } from "@antelopejs/interface-email";
|
|
@@ -43,7 +47,7 @@ await Send({
|
|
|
43
47
|
|
|
44
48
|
### `Base64Attachment`
|
|
45
49
|
|
|
46
|
-
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`.
|
|
47
51
|
|
|
48
52
|
```ts
|
|
49
53
|
import { Send, Base64Attachment } from "@antelopejs/interface-email";
|
|
@@ -65,7 +69,7 @@ await Send({
|
|
|
65
69
|
|
|
66
70
|
### `PathAttachment`
|
|
67
71
|
|
|
68
|
-
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.
|
|
69
73
|
|
|
70
74
|
```ts
|
|
71
75
|
import { Send, PathAttachment } from "@antelopejs/interface-email";
|
|
@@ -86,7 +90,7 @@ await Send({
|
|
|
86
90
|
|
|
87
91
|
### `UrlAttachment`
|
|
88
92
|
|
|
89
|
-
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.
|
|
90
94
|
|
|
91
95
|
```ts
|
|
92
96
|
import { Send, UrlAttachment } from "@antelopejs/interface-email";
|
|
@@ -105,11 +109,11 @@ await Send({
|
|
|
105
109
|
});
|
|
106
110
|
```
|
|
107
111
|
|
|
108
|
-
## Inline
|
|
112
|
+
## Inline images
|
|
109
113
|
|
|
110
|
-
|
|
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)).
|
|
111
115
|
|
|
112
|
-
The following example reads a
|
|
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.
|
|
113
117
|
|
|
114
118
|
```ts
|
|
115
119
|
import { readFile } from "node:fs/promises";
|
|
@@ -138,11 +142,11 @@ await Send({
|
|
|
138
142
|
});
|
|
139
143
|
```
|
|
140
144
|
|
|
141
|
-
|
|
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.
|
|
142
146
|
|
|
143
|
-
## Multiple
|
|
147
|
+
## Multiple attachments
|
|
144
148
|
|
|
145
|
-
The `attachments` field
|
|
149
|
+
The `attachments` field takes an array, so one email can mix attachment types:
|
|
146
150
|
|
|
147
151
|
```ts
|
|
148
152
|
import { Send } from "@antelopejs/interface-email";
|
|
@@ -171,24 +175,31 @@ await Send({
|
|
|
171
175
|
});
|
|
172
176
|
```
|
|
173
177
|
|
|
174
|
-
## The `BaseAttachment`
|
|
178
|
+
## The `BaseAttachment` interface
|
|
175
179
|
|
|
176
|
-
Every attachment requires a filename. These shared fields apply to all four
|
|
180
|
+
Every attachment requires a filename. These shared fields apply to all four types:
|
|
177
181
|
|
|
178
182
|
| Field | Type | Required | Description |
|
|
179
183
|
| ------------- | --------- | -------- | ----------------------------------------------------------------- |
|
|
180
184
|
| `filename` | `string` | Yes | The filename shown to the recipient |
|
|
181
|
-
| `contentType` | `string` | No | MIME type
|
|
185
|
+
| `contentType` | `string` | No | MIME type, such as `"application/pdf"` |
|
|
182
186
|
| `cid` | `string` | No | Content-ID for inline images (reference in HTML as `cid:yourCid`) |
|
|
183
187
|
| `inline` | `boolean` | No | If `true`, embed in the HTML body instead of attaching as a file |
|
|
184
188
|
|
|
185
|
-
## The `Attachment`
|
|
189
|
+
## The `Attachment` union type
|
|
186
190
|
|
|
187
|
-
The `Attachment` type is
|
|
191
|
+
The `Attachment` type is the union of the four attachment interfaces:
|
|
188
192
|
|
|
189
193
|
```ts
|
|
194
|
+
import type {
|
|
195
|
+
Base64Attachment,
|
|
196
|
+
BufferAttachment,
|
|
197
|
+
PathAttachment,
|
|
198
|
+
UrlAttachment,
|
|
199
|
+
} from "@antelopejs/interface-email";
|
|
200
|
+
|
|
190
201
|
type Attachment =
|
|
191
202
|
BufferAttachment | Base64Attachment | PathAttachment | UrlAttachment;
|
|
192
203
|
```
|
|
193
204
|
|
|
194
|
-
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`.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@antelopejs/interface-email",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.2.0",
|
|
4
4
|
"description": "AntelopeJS interface for sending email: single, batch and template messages with attachments",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"antelopejs",
|
|
@@ -35,15 +35,15 @@
|
|
|
35
35
|
"provenance": true
|
|
36
36
|
},
|
|
37
37
|
"scripts": {
|
|
38
|
-
"build": "rimraf dist && tsc -p tsconfig.build.json",
|
|
38
|
+
"build": "rimraf dist && tsc -p tsconfig.build.json --skipLibCheck",
|
|
39
39
|
"format": "oxfmt .",
|
|
40
40
|
"lint:fix": "oxlint --fix",
|
|
41
41
|
"lint": "oxlint",
|
|
42
42
|
"prepack": "pnpm run build",
|
|
43
|
-
"release": "pnpm run lint && pnpm run prepack && release-it",
|
|
43
|
+
"release": "pnpm run lint && pnpm run typecheck && pnpm run prepack && release-it",
|
|
44
44
|
"format:check": "oxfmt --check .",
|
|
45
45
|
"knip": "knip",
|
|
46
|
-
"prepare": "if
|
|
46
|
+
"prepare": "if [ -e .git ] && command -v git >/dev/null 2>&1 && command -v lefthook >/dev/null 2>&1 && GIT_DIR=.git GIT_WORK_TREE=. git rev-parse --git-dir >/dev/null 2>&1; then GIT_DIR=.git GIT_WORK_TREE=. lefthook install; fi",
|
|
47
47
|
"checks": "antelopejs-checks",
|
|
48
48
|
"size": "antelopejs-check-size",
|
|
49
49
|
"sync": "antelopejs-sync",
|
|
@@ -54,8 +54,9 @@
|
|
|
54
54
|
"suppressions:update": "antelopejs-suppressions --update"
|
|
55
55
|
},
|
|
56
56
|
"devDependencies": {
|
|
57
|
+
"@antelopejs/core": "^1.21.0",
|
|
57
58
|
"@antelopejs/interface-core": ">=0.2.4 <1.0.0",
|
|
58
|
-
"@antelopejs/tooling-configs": "^0.
|
|
59
|
+
"@antelopejs/tooling-configs": "^0.4.0",
|
|
59
60
|
"@types/node": "^22.19.15",
|
|
60
61
|
"eslint-plugin-perfectionist": "^5.11.0",
|
|
61
62
|
"knip": "^6.34.0",
|
|
@@ -75,6 +76,9 @@
|
|
|
75
76
|
"antelopeJs": {
|
|
76
77
|
"skills": [
|
|
77
78
|
"./skills"
|
|
78
|
-
]
|
|
79
|
+
],
|
|
80
|
+
"docs": {
|
|
81
|
+
"standard": true
|
|
82
|
+
}
|
|
79
83
|
}
|
|
80
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`. 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.
|
|
59
|
+
`SendTemplate` takes `template: { id }` (provider-hosted, gated on `features.providerTemplates`) or `{ content, type }` (inline, gated on `features.templates`) 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
|
|
|
@@ -81,6 +81,7 @@ ImplementInterface(EmailInterface, {
|
|
|
81
81
|
features: {
|
|
82
82
|
batch: true,
|
|
83
83
|
templates: false,
|
|
84
|
+
providerTemplates: false,
|
|
84
85
|
scheduling: false,
|
|
85
86
|
openTracking: false,
|
|
86
87
|
clickTracking: false,
|