@antelopejs/interface-email 0.1.0 → 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 CHANGED
@@ -1,10 +1,10 @@
1
- # @antelopejs/interface-email
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/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>
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 individual message results; `GetCapabilities` returns provider features and limits, not delivery results.
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: ./package.json#peerDependencies -->
69
+ <!-- antelopejs-docs-compat:start -->
69
70
 
70
- | Package | Range |
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
- 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.
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
 
@@ -1,6 +1,10 @@
1
- # Introduction
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-neutral contract. `@antelopejs/interface-email` defines the request and response types; an implementing module supplies the email provider and its configuration.
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
- ![Choose a sending API, then inspect the provider response; acceptance does not prove inbox delivery.](./assets/message-lifecycle.svg){width="480"}
19
+ ![Choose a sending API, then inspect the provider response. Acceptance does not prove inbox delivery.](./assets/message-lifecycle.svg "illustration"){width="480"}
16
20
 
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.
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 Concepts
23
+ ## Core concepts
20
24
 
21
- The interface separates email operations into four functions:
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; inspect `status` rather than treating acceptance as confirmed delivery.
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 Address Types
42
+ ## Email address types
39
43
 
40
- Recipients, senders, and reply-to addresses all accept the `EmailAddress` type. This type supports two formats: a plain string or an object with an optional display name.
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 format to include a display name alongside the address:
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
- The `EmailAddress` type is a union of both formats. All address fields in the interface accept either form:
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
- Fields like `to`, `cc`, and `bcc` also accept arrays of `EmailAddress`, so you can mix formats freely:
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,38 @@ await Send({
86
90
  });
87
91
  ```
88
92
 
89
- ## Provider Capabilities
93
+ ## Provider capabilities
90
94
 
91
- Not all email providers support every feature. The `GetCapabilities` function returns a `ProviderCapabilities` object describing the provider's name, limits, and supported features.
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); // e.g., "sendgrid"
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); // e.g., 1000
105
+ console.log(capabilities.maxRecipients); // undefined when the provider reports no limit
102
106
  ```
103
107
 
104
- The `ProviderFeatures` object includes the following flags:
108
+ The `ProviderFeatures` object has these flags:
105
109
 
106
110
  | Feature | Description |
107
111
  | ------------------- | ----------------------------------------------- |
108
112
  | `batch` | Supports sending multiple emails in one request |
109
- | `templates` | Supports provider-hosted templates |
113
+ | `templates` | Supports `SendTemplate` |
110
114
  | `scheduling` | Supports delayed email delivery |
111
115
  | `openTracking` | Tracks when recipients open emails |
112
116
  | `clickTracking` | Tracks when recipients click links |
113
- | `inlineAttachments` | Supports inline/embedded images |
117
+ | `inlineAttachments` | Supports inline, embedded images |
114
118
  | `tags` | Supports email tagging for analytics |
115
119
  | `metadata` | Supports custom metadata on emails |
116
120
  | `priority` | Supports email priority levels |
117
121
 
118
- Check capabilities before using optional features to ensure your code works across providers:
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:
119
125
 
120
126
  ```ts
121
127
  import {
@@ -139,9 +145,9 @@ if (caps.features.scheduling) {
139
145
  await Send(params);
140
146
  ```
141
147
 
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.
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.
143
149
 
144
- ## Next Steps
150
+ ## Next steps
145
151
 
146
- - [Sending Emails](./2.sending-emails.md) -- Learn about all email parameters, templates, batch sending, and delivery responses.
147
- - [Attachments](./3.attachments.md) -- Attach files using buffers, base64, file paths, or URLs.
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.
@@ -1,12 +1,16 @@
1
- # Sending Emails
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 provides three sending functions: `Send` for single emails, `SendTemplate` for template-based emails, and `SendBatch` for multiple emails in one operation.
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 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).
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` Object
11
+ ## The `EmailParams` object
8
12
 
9
- The `Send` function accepts an `EmailParams` object. Only `to` and `subject` are required -- all other fields are optional.
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. See [Email Response](#email-response)
31
- for optional fields and retry precautions.
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 Fields
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 Fields
44
+ ### Content fields
41
45
 
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.
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 Fields
53
+ ### Address fields
50
54
 
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 |
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 Fields
62
+ ### Threading fields
59
63
 
60
- Use these fields to place an email within an existing thread:
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 Priority
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 relying on this option.
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 (default) |
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 Options
105
+ ## Tracking options
102
106
 
103
- The `tracking` field configures open and click tracking through the `TrackingOptions` interface.
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 Options
131
+ ## Schedule options
128
132
 
129
- The `schedule` field delays email delivery to a specified time using the `ScheduleOptions` interface.
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 (e.g., `"Europe/Paris"`) |
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
- > **Note:** Check `(await GetCapabilities()).features.scheduling` before using scheduling to confirm the provider supports it.
154
+ Before you schedule a message, check `(await GetCapabilities()).features.scheduling` to confirm that the provider supports it.
151
155
 
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.
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 Metadata
158
+ ## Tags and metadata
155
159
 
156
- Tags and metadata help categorize and track emails for analytics.
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 Options
182
+ ## Provider options
179
183
 
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.
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 Emails
199
+ ## Template emails
196
200
 
197
- The `SendTemplate` function renders an email from a template before sending. Templates can be provider-hosted or defined inline.
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
- Reference a template stored in the provider's system by its ID:
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.
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
- Define the template content directly with an optional engine hint:
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` 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 }`).
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
- When sending to multiple recipients, provide unique variable values for each one using `recipientVariables`:
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 Sending
258
+ ## Batch sending
255
259
 
256
- The `SendBatch` function sends multiple emails in a single operation. Each message in the batch follows the same `EmailParams` structure, with an optional `batchId` for matching responses.
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 applies shared values to all messages. Individual message fields override defaults when both are specified.
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 continues sending even if individual messages fail. The response includes per-message results:
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 Response
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 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.
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`, inspect the optional `error` field for an `EmailError` object:
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, 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.
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 Steps
352
+ ## Next steps
349
353
 
350
- - [Attachments](./3.attachments.md) -- Learn how to attach files using buffers, base64, file paths, or URLs.
354
+ - [Attachments](./3.attachments.md) shows how to attach files from buffers, base64 strings, file paths, or URLs.
@@ -1,6 +1,10 @@
1
- # Attachments
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 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`.
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
- 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.
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 Types
20
+ ## Attachment types
17
21
 
18
22
  ### `BufferAttachment`
19
23
 
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.
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 you have file data encoded as a base64 string. Set the `encoding` field to `"base64"` to distinguish it from a `BufferAttachment`.
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. The email provider reads the file at send time.
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. The email provider fetches the file from the URL at send time.
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 Images
112
+ ## Inline images
109
113
 
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.
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 real PNG at `./assets/logo.png`, relative to the server's working directory. Supply that file before running it.
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
- > **Note:** Check `(await GetCapabilities()).features.inlineAttachments` to confirm the provider supports inline images.
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 Attachments
147
+ ## Multiple attachments
144
148
 
145
- The `attachments` field accepts an array, so you can mix different attachment types in a single email:
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` Interface
178
+ ## The `BaseAttachment` interface
175
179
 
176
- Every attachment requires a filename. These shared fields apply to all four sources:
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 (e.g., `"application/pdf"`) |
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` Union Type
189
+ ## The `Attachment` union type
186
190
 
187
- The `Attachment` type is a union of all four attachment interfaces:
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 constructing attachments dynamically, TypeScript narrows the type based on the presence of distinguishing fields (`content` with `encoding`, `path`, or `url`).
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,7 @@
1
+ {
2
+ "extends": "../tsconfig.json",
3
+ "compilerOptions": {
4
+ "module": "esnext",
5
+ "moduleResolution": "bundler"
6
+ }
7
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@antelopejs/interface-email",
3
- "version": "0.1.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",
@@ -54,8 +54,9 @@
54
54
  "suppressions:update": "antelopejs-suppressions --update"
55
55
  },
56
56
  "devDependencies": {
57
+ "@antelopejs/core": "^1.16.0",
57
58
  "@antelopejs/interface-core": ">=0.2.4 <1.0.0",
58
- "@antelopejs/tooling-configs": "^0.2.11",
59
+ "@antelopejs/tooling-configs": "^0.2.17",
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
  }