@antelopejs/interface-email 0.0.3 → 0.0.5

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.
@@ -0,0 +1,128 @@
1
+ # Introduction
2
+
3
+ The `@antelopejs/interface-email` package defines a provider-agnostic email interface for AntelopeJS applications. It exposes a consistent API for sending emails regardless of the underlying provider (SendGrid, Mailgun, Amazon SES, etc.).
4
+
5
+ ## Core Concepts
6
+
7
+ The interface separates email operations into four functions:
8
+
9
+ | Function | Purpose |
10
+ | --- | --- |
11
+ | `Send` | Send a single email with full control over content and options |
12
+ | `SendBatch` | Send multiple emails in a single operation |
13
+ | `SendTemplate` | Send an email rendered from a template |
14
+ | `GetCapabilities` | Query the provider's supported features and limits |
15
+
16
+ Each function returns a typed response that includes delivery status, provider message IDs, and error details when applicable.
17
+
18
+ ## Installation
19
+
20
+ ```bash
21
+ npm install @antelopejs/interface-email
22
+ ```
23
+
24
+ ## Email Address Types
25
+
26
+ 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.
27
+
28
+ ### String format
29
+
30
+ Pass an email address directly as a string:
31
+
32
+ ```ts
33
+ const to: EmailAddress = "user@example.com";
34
+ ```
35
+
36
+ ### Object format with `EmailAddressObject`
37
+
38
+ Use the object format to include a display name alongside the address:
39
+
40
+ ```ts
41
+ import { EmailAddressObject } from "@antelopejs/interface-email";
42
+
43
+ const sender: EmailAddressObject = {
44
+ email: "support@myapp.com",
45
+ name: "MyApp Support",
46
+ };
47
+ ```
48
+
49
+ ### The `EmailAddress` union type
50
+
51
+ The `EmailAddress` type is a union of both formats. All address fields in the interface accept either form:
52
+
53
+ ```ts
54
+ import { EmailAddress } from "@antelopejs/interface-email";
55
+
56
+ // Both are valid EmailAddress values
57
+ const simple: EmailAddress = "hello@example.com";
58
+ const detailed: EmailAddress = { email: "hello@example.com", name: "Hello" };
59
+ ```
60
+
61
+ Fields like `to`, `cc`, and `bcc` also accept arrays of `EmailAddress`, so you can mix formats freely:
62
+
63
+ ```ts
64
+ import { Send } from "@antelopejs/interface-email";
65
+
66
+ await Send({
67
+ to: [
68
+ "alice@example.com",
69
+ { email: "bob@example.com", name: "Bob" },
70
+ ],
71
+ subject: "Team Update",
72
+ text: "Here is the latest update.",
73
+ });
74
+ ```
75
+
76
+ ## Provider Capabilities
77
+
78
+ Not all email providers support every feature. The `GetCapabilities` function returns a `ProviderCapabilities` object describing the provider's name, limits, and supported features.
79
+
80
+ ```ts
81
+ import { GetCapabilities } from "@antelopejs/interface-email";
82
+
83
+ const capabilities = await GetCapabilities();
84
+
85
+ console.log(capabilities.name); // e.g., "sendgrid"
86
+ console.log(capabilities.features.batch); // true or false
87
+ console.log(capabilities.features.scheduling); // true or false
88
+ console.log(capabilities.maxRecipients); // e.g., 1000
89
+ ```
90
+
91
+ The `ProviderFeatures` object includes the following flags:
92
+
93
+ | Feature | Description |
94
+ | --- | --- |
95
+ | `batch` | Supports sending multiple emails in one request |
96
+ | `templates` | Supports provider-hosted templates |
97
+ | `scheduling` | Supports delayed email delivery |
98
+ | `openTracking` | Tracks when recipients open emails |
99
+ | `clickTracking` | Tracks when recipients click links |
100
+ | `inlineAttachments` | Supports inline/embedded images |
101
+ | `tags` | Supports email tagging for analytics |
102
+ | `metadata` | Supports custom metadata on emails |
103
+ | `priority` | Supports email priority levels |
104
+
105
+ Check capabilities before using optional features to ensure your code works across providers:
106
+
107
+ ```ts
108
+ import { GetCapabilities, Send } from "@antelopejs/interface-email";
109
+
110
+ const caps = await GetCapabilities();
111
+
112
+ const params: any = {
113
+ to: "user@example.com",
114
+ subject: "Hello",
115
+ html: "<p>Welcome!</p>",
116
+ };
117
+
118
+ if (caps.features.scheduling) {
119
+ params.schedule = { sendAt: new Date("2026-04-01T09:00:00Z") };
120
+ }
121
+
122
+ await Send(params);
123
+ ```
124
+
125
+ ## Next Steps
126
+
127
+ - [Sending Emails](./2.sending-emails.md) -- Learn about all email parameters, templates, batch sending, and delivery responses.
128
+ - [Attachments](./3.attachments.md) -- Attach files using buffers, base64, file paths, or URLs.
@@ -0,0 +1,326 @@
1
+ # Sending Emails
2
+
3
+ The interface provides three sending functions: `Send` for single emails, `SendTemplate` for template-based emails, and `SendBatch` for multiple emails in one operation.
4
+
5
+ ## The `EmailParams` Object
6
+
7
+ The `Send` function accepts an `EmailParams` object. Only `to` and `subject` are required -- all other fields are optional.
8
+
9
+ ```ts
10
+ import { Send } from "@antelopejs/interface-email";
11
+
12
+ const response = await Send({
13
+ to: "user@example.com",
14
+ subject: "Welcome aboard",
15
+ html: "<h1>Welcome!</h1><p>Thanks for joining.</p>",
16
+ text: "Welcome! Thanks for joining.",
17
+ });
18
+ ```
19
+
20
+ ### Required Fields
21
+
22
+ | Field | Type | Description |
23
+ | --- | --- | --- |
24
+ | `to` | `EmailAddress \| EmailAddress[]` | One or more recipients |
25
+ | `subject` | `string` | The email subject line |
26
+
27
+ ### Content Fields
28
+
29
+ Provide at least one of `text` or `html`. Including both ensures compatibility with all email clients.
30
+
31
+ | Field | Type | Description |
32
+ | --- | --- | --- |
33
+ | `text` | `string` | Plain text body |
34
+ | `html` | `string` | HTML body |
35
+
36
+ ### Address Fields
37
+
38
+ | Field | Type | Description |
39
+ | --- | --- | --- |
40
+ | `from` | `EmailAddress` | Sender address (uses provider default if omitted) |
41
+ | `replyTo` | `EmailAddress \| EmailAddress[]` | Reply-to address(es) |
42
+ | `cc` | `EmailAddress \| EmailAddress[]` | CC recipients |
43
+ | `bcc` | `EmailAddress \| EmailAddress[]` | BCC recipients |
44
+
45
+ ### Threading Fields
46
+
47
+ Use these fields to place an email within an existing thread:
48
+
49
+ | Field | Type | Description |
50
+ | --- | --- | --- |
51
+ | `messageId` | `string` | Custom Message-ID header |
52
+ | `inReplyTo` | `string` | Message-ID of the email being replied to |
53
+ | `references` | `string \| string[]` | Message-IDs of the thread |
54
+
55
+ ```ts
56
+ import { Send } from "@antelopejs/interface-email";
57
+
58
+ await Send({
59
+ to: "user@example.com",
60
+ subject: "Re: Project update",
61
+ text: "Thanks for the update!",
62
+ inReplyTo: "<original-message-id@example.com>",
63
+ references: ["<original-message-id@example.com>"],
64
+ });
65
+ ```
66
+
67
+ ## Email Priority
68
+
69
+ The `priority` field controls the email's delivery priority. It accepts one of three values:
70
+
71
+ | Value | Description |
72
+ | --- | --- |
73
+ | `"high"` | Urgent emails that should be delivered immediately |
74
+ | `"normal"` | Standard delivery priority (default) |
75
+ | `"low"` | Non-urgent emails such as newsletters |
76
+
77
+ ```ts
78
+ import { Send } from "@antelopejs/interface-email";
79
+
80
+ await Send({
81
+ to: "admin@example.com",
82
+ subject: "Server Alert",
83
+ text: "CPU usage exceeded 95%.",
84
+ priority: "high",
85
+ });
86
+ ```
87
+
88
+ ## Tracking Options
89
+
90
+ The `tracking` field configures open and click tracking through the `TrackingOptions` interface.
91
+
92
+ | Field | Type | Description |
93
+ | --- | --- | --- |
94
+ | `opens` | `boolean` | Track when the recipient opens the email |
95
+ | `clicks` | `boolean` | Track when the recipient clicks links |
96
+ | `trackingDomain` | `string` | Custom domain for tracking URLs |
97
+ | `disabled` | `boolean` | Disable all tracking |
98
+
99
+ ```ts
100
+ import { Send } from "@antelopejs/interface-email";
101
+
102
+ await Send({
103
+ to: "user@example.com",
104
+ subject: "Monthly Report",
105
+ html: "<p>Your report is ready. <a href='https://app.example.com/reports'>View it here</a>.</p>",
106
+ tracking: {
107
+ opens: true,
108
+ clicks: true,
109
+ trackingDomain: "track.example.com",
110
+ },
111
+ });
112
+ ```
113
+
114
+ ## Schedule Options
115
+
116
+ The `schedule` field delays email delivery to a specified time using the `ScheduleOptions` interface.
117
+
118
+ | Field | Type | Description |
119
+ | --- | --- | --- |
120
+ | `sendAt` | `Date \| string` | When to send the email (ISO 8601 string or Date object) |
121
+ | `timezone` | `string` | IANA timezone identifier (e.g., `"Europe/Paris"`) |
122
+
123
+ ```ts
124
+ import { Send } from "@antelopejs/interface-email";
125
+
126
+ await Send({
127
+ to: "team@example.com",
128
+ subject: "Monday Standup Reminder",
129
+ text: "Standup in 15 minutes.",
130
+ schedule: {
131
+ sendAt: new Date("2026-04-06T08:45:00"),
132
+ timezone: "Europe/Paris",
133
+ },
134
+ });
135
+ ```
136
+
137
+ > **Note:** Check `GetCapabilities().features.scheduling` before using scheduling to confirm the provider supports it.
138
+
139
+ ## Tags and Metadata
140
+
141
+ Tags and metadata help categorize and track emails for analytics.
142
+
143
+ | Field | Type | Description |
144
+ | --- | --- | --- |
145
+ | `tags` | `string[]` | Labels for categorization and analytics |
146
+ | `metadata` | `Record<string, string>` | Custom key-value pairs returned in webhook events |
147
+
148
+ ```ts
149
+ import { Send } from "@antelopejs/interface-email";
150
+
151
+ await Send({
152
+ to: "user@example.com",
153
+ subject: "Order Confirmation",
154
+ html: "<p>Your order #12345 has been confirmed.</p>",
155
+ tags: ["transactional", "order-confirmation"],
156
+ metadata: {
157
+ orderId: "12345",
158
+ userId: "usr_abc",
159
+ },
160
+ });
161
+ ```
162
+
163
+ ## Provider Options
164
+
165
+ The `providerOptions` field passes provider-specific configuration that falls outside the standard interface. Use it sparingly, as it reduces portability.
166
+
167
+ ```ts
168
+ import { Send } from "@antelopejs/interface-email";
169
+
170
+ await Send({
171
+ to: "user@example.com",
172
+ subject: "Test",
173
+ text: "Hello",
174
+ providerOptions: {
175
+ sendgridIpPoolName: "transactional",
176
+ },
177
+ });
178
+ ```
179
+
180
+ ## Template Emails
181
+
182
+ The `SendTemplate` function renders an email from a template before sending. Templates can be provider-hosted or defined inline.
183
+
184
+ ### Provider-hosted templates
185
+
186
+ Reference a template stored in the provider's system by its ID:
187
+
188
+ ```ts
189
+ import { SendTemplate } from "@antelopejs/interface-email";
190
+
191
+ const response = await SendTemplate({
192
+ to: "user@example.com",
193
+ template: { id: "welcome-v2", version: "3" },
194
+ variables: {
195
+ name: "Alice",
196
+ activationUrl: "https://app.example.com/activate?token=xyz",
197
+ },
198
+ });
199
+ ```
200
+
201
+ ### Inline templates
202
+
203
+ Define the template content directly with an optional engine hint:
204
+
205
+ ```ts
206
+ import { SendTemplate } from "@antelopejs/interface-email";
207
+
208
+ const response = await SendTemplate({
209
+ to: "user@example.com",
210
+ template: {
211
+ content: "<h1>Hello {{name}}</h1><p>Welcome to our platform.</p>",
212
+ type: "html",
213
+ engine: "handlebars",
214
+ },
215
+ variables: { name: "Alice" },
216
+ });
217
+ ```
218
+
219
+ ### Per-recipient variables
220
+
221
+ When sending to multiple recipients, provide unique variable values for each one using `recipientVariables`:
222
+
223
+ ```ts
224
+ import { SendTemplate } from "@antelopejs/interface-email";
225
+
226
+ await SendTemplate({
227
+ to: ["alice@example.com", "bob@example.com"],
228
+ template: { id: "weekly-digest" },
229
+ variables: { week: "March 23-29" },
230
+ recipientVariables: {
231
+ "alice@example.com": { name: "Alice", unreadCount: "5" },
232
+ "bob@example.com": { name: "Bob", unreadCount: "12" },
233
+ },
234
+ });
235
+ ```
236
+
237
+ ## Batch Sending
238
+
239
+ 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.
240
+
241
+ ```ts
242
+ import { SendBatch } from "@antelopejs/interface-email";
243
+
244
+ const result = await SendBatch({
245
+ messages: [
246
+ {
247
+ to: "alice@example.com",
248
+ subject: "Your invoice",
249
+ html: "<p>Invoice #001 attached.</p>",
250
+ batchId: "invoice-001",
251
+ },
252
+ {
253
+ to: "bob@example.com",
254
+ subject: "Your invoice",
255
+ html: "<p>Invoice #002 attached.</p>",
256
+ batchId: "invoice-002",
257
+ },
258
+ ],
259
+ defaults: {
260
+ from: { email: "billing@myapp.com", name: "Billing" },
261
+ tags: ["invoice"],
262
+ },
263
+ continueOnError: true,
264
+ });
265
+ ```
266
+
267
+ ### Batch defaults
268
+
269
+ The `defaults` field applies shared values to all messages. Individual message fields override defaults when both are specified.
270
+
271
+ ### Error handling in batches
272
+
273
+ When `continueOnError` is `true` (the default), the batch continues sending even if individual messages fail. The response includes per-message results:
274
+
275
+ ```ts
276
+ console.log(result.total); // Total messages in batch
277
+ console.log(result.successful); // Number sent successfully
278
+ console.log(result.failed); // Number that failed
279
+
280
+ for (const res of result.responses) {
281
+ if (!res.success) {
282
+ console.error(`Message ${res.batchId} to ${res.recipient} failed:`, res.error);
283
+ }
284
+ }
285
+ ```
286
+
287
+ ## Email Response
288
+
289
+ The `Send` and `SendTemplate` functions return an `EmailResponse` object:
290
+
291
+ | Field | Type | Description |
292
+ | --- | --- | --- |
293
+ | `success` | `boolean` | Whether the email was accepted |
294
+ | `status` | `EmailStatus` | Current delivery status |
295
+ | `messageId` | `string` | Provider-assigned ID for tracking |
296
+ | `error` | `EmailError` | Error details if the send failed |
297
+ | `timestamp` | `Date` | When the email was accepted |
298
+ | `provider` | `string` | Name of the provider that handled the request |
299
+
300
+ The `EmailStatus` type includes these values: `"queued"`, `"sent"`, `"delivered"`, `"failed"`, `"rejected"`, `"scheduled"`, and `"unknown"`.
301
+
302
+ ### Error handling
303
+
304
+ When `success` is `false`, the `error` field contains an `EmailError` object:
305
+
306
+ ```ts
307
+ import { Send } from "@antelopejs/interface-email";
308
+
309
+ const response = await Send({
310
+ to: "user@example.com",
311
+ subject: "Hello",
312
+ text: "World",
313
+ });
314
+
315
+ if (!response.success && response.error) {
316
+ console.error(`Error [${response.error.code}]: ${response.error.message}`);
317
+
318
+ if (response.error.retryable) {
319
+ // Safe to retry this request
320
+ }
321
+ }
322
+ ```
323
+
324
+ ## Next Steps
325
+
326
+ - [Attachments](./3.attachments.md) -- Learn how to attach files using buffers, base64, file paths, or URLs.
@@ -0,0 +1,176 @@
1
+ # Attachments
2
+
3
+ The interface supports four attachment types, each suited to a different source of file data. All types share a common `BaseAttachment` structure and are passed through the `attachments` field of `EmailParams`.
4
+
5
+ ## The `BaseAttachment` Interface
6
+
7
+ Every attachment type extends `BaseAttachment`, which defines shared metadata fields:
8
+
9
+ | Field | Type | Required | Description |
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 |
15
+
16
+ ## Attachment Types
17
+
18
+ ### `BufferAttachment`
19
+
20
+ Use `BufferAttachment` when you have file data in memory as a Node.js `Buffer`. This is common when generating files dynamically or reading from streams.
21
+
22
+ ```ts
23
+ import { Send, BufferAttachment } from "@antelopejs/interface-email";
24
+
25
+ const pdfBuffer = Buffer.from(/* generated PDF data */);
26
+
27
+ const attachment: BufferAttachment = {
28
+ filename: "report.pdf",
29
+ contentType: "application/pdf",
30
+ content: pdfBuffer,
31
+ };
32
+
33
+ await Send({
34
+ to: "user@example.com",
35
+ subject: "Your Report",
36
+ text: "Please find the attached report.",
37
+ attachments: [attachment],
38
+ });
39
+ ```
40
+
41
+ ### `Base64Attachment`
42
+
43
+ Use `Base64Attachment` when you have file data encoded as a base64 string. Set the `encoding` field to `"base64"` to distinguish it from a `BufferAttachment`.
44
+
45
+ ```ts
46
+ import { Send, Base64Attachment } from "@antelopejs/interface-email";
47
+
48
+ const attachment: Base64Attachment = {
49
+ filename: "logo.png",
50
+ contentType: "image/png",
51
+ content: "iVBORw0KGgoAAAANSUhEUgAA...",
52
+ encoding: "base64",
53
+ };
54
+
55
+ await Send({
56
+ to: "user@example.com",
57
+ subject: "Brand Assets",
58
+ text: "Logo attached.",
59
+ attachments: [attachment],
60
+ });
61
+ ```
62
+
63
+ ### `PathAttachment`
64
+
65
+ Use `PathAttachment` to attach a file from the local filesystem by its path. The email provider reads the file at send time.
66
+
67
+ ```ts
68
+ import { Send, PathAttachment } from "@antelopejs/interface-email";
69
+
70
+ const attachment: PathAttachment = {
71
+ filename: "data-export.csv",
72
+ contentType: "text/csv",
73
+ path: "/tmp/exports/data-export-2026.csv",
74
+ };
75
+
76
+ await Send({
77
+ to: "analyst@example.com",
78
+ subject: "Data Export",
79
+ text: "The requested export is attached.",
80
+ attachments: [attachment],
81
+ });
82
+ ```
83
+
84
+ ### `UrlAttachment`
85
+
86
+ Use `UrlAttachment` to attach a file from a remote URL. The email provider fetches the file from the URL at send time.
87
+
88
+ ```ts
89
+ import { Send, UrlAttachment } from "@antelopejs/interface-email";
90
+
91
+ const attachment: UrlAttachment = {
92
+ filename: "handbook.pdf",
93
+ contentType: "application/pdf",
94
+ url: "https://cdn.example.com/docs/handbook-v3.pdf",
95
+ };
96
+
97
+ await Send({
98
+ to: "new-hire@example.com",
99
+ subject: "Employee Handbook",
100
+ text: "Please review the attached handbook.",
101
+ attachments: [attachment],
102
+ });
103
+ ```
104
+
105
+ ## Inline Images
106
+
107
+ Inline attachments embed images directly in the HTML body using Content-ID references. Set `inline` to `true` and assign a `cid` value, then reference it in your HTML with the `cid:` protocol.
108
+
109
+ ```ts
110
+ import { Send, BufferAttachment } from "@antelopejs/interface-email";
111
+
112
+ const logoBuffer = Buffer.from(/* logo image data */);
113
+
114
+ await Send({
115
+ to: "user@example.com",
116
+ subject: "Welcome",
117
+ html: `
118
+ <div>
119
+ <img src="cid:company-logo" alt="Company Logo" />
120
+ <h1>Welcome to our platform!</h1>
121
+ </div>
122
+ `,
123
+ attachments: [
124
+ {
125
+ filename: "logo.png",
126
+ contentType: "image/png",
127
+ content: logoBuffer,
128
+ cid: "company-logo",
129
+ inline: true,
130
+ },
131
+ ],
132
+ });
133
+ ```
134
+
135
+ > **Note:** Check `GetCapabilities().features.inlineAttachments` to confirm the provider supports inline images.
136
+
137
+ ## Multiple Attachments
138
+
139
+ The `attachments` field accepts an array, so you can mix different attachment types in a single email:
140
+
141
+ ```ts
142
+ import { Send } from "@antelopejs/interface-email";
143
+
144
+ await Send({
145
+ to: "client@example.com",
146
+ subject: "Project Deliverables",
147
+ text: "All deliverables are attached.",
148
+ attachments: [
149
+ {
150
+ filename: "proposal.pdf",
151
+ contentType: "application/pdf",
152
+ path: "/documents/proposal.pdf",
153
+ },
154
+ {
155
+ filename: "mockup.png",
156
+ contentType: "image/png",
157
+ url: "https://cdn.example.com/mockups/v2.png",
158
+ },
159
+ {
160
+ filename: "notes.txt",
161
+ contentType: "text/plain",
162
+ content: Buffer.from("Meeting notes for the project kickoff."),
163
+ },
164
+ ],
165
+ });
166
+ ```
167
+
168
+ ## The `Attachment` Union Type
169
+
170
+ The `Attachment` type is a union of all four attachment interfaces:
171
+
172
+ ```ts
173
+ type Attachment = BufferAttachment | Base64Attachment | PathAttachment | UrlAttachment;
174
+ ```
175
+
176
+ When constructing attachments dynamically, TypeScript narrows the type based on the presence of distinguishing fields (`content` with `encoding`, `path`, or `url`).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@antelopejs/interface-email",
3
- "version": "0.0.3",
3
+ "version": "0.0.5",
4
4
  "description": "AntelopeJS interface for email sending with support for templates, batch, and attachments",
5
5
  "keywords": [
6
6
  "antelopejs",
@@ -17,7 +17,9 @@
17
17
  "main": "dist/index.js",
18
18
  "types": "dist/index.d.ts",
19
19
  "files": [
20
- "dist"
20
+ "dist",
21
+ "docs",
22
+ "skills"
21
23
  ],
22
24
  "exports": {
23
25
  ".": {
@@ -33,10 +35,8 @@
33
35
  "prepack": "pnpm run build",
34
36
  "release": "pnpm run lint && pnpm run prepack && release-it"
35
37
  },
36
- "dependencies": {
37
- "@antelopejs/interface-core": "^0.0.3"
38
- },
39
38
  "devDependencies": {
39
+ "@antelopejs/interface-core": ">=0.0.3 <1.0.0",
40
40
  "@biomejs/biome": "2.3.2",
41
41
  "@types/node": "^22.19.15",
42
42
  "release-it": "^19.2.4",
@@ -44,8 +44,15 @@
44
44
  "rimraf": "^6.1.3",
45
45
  "typescript": "^5.9.3"
46
46
  },
47
+ "peerDependencies": {
48
+ "@antelopejs/interface-core": ">=0.0.3 <1.0.0"
49
+ },
47
50
  "publishConfig": {
48
51
  "access": "public"
49
52
  },
50
- "antelopeJs": {}
53
+ "antelopeJs": {
54
+ "skills": [
55
+ "./skills"
56
+ ]
57
+ }
51
58
  }
@@ -0,0 +1,72 @@
1
+ ---
2
+ name: email-interface
3
+ description: Provider-agnostic email interface for AntelopeJS exposing Send, SendBatch, SendTemplate and GetCapabilities proxy functions with typed params for attachments, templates, tracking and scheduling. Use when code imports "@antelopejs/interface-email", when asked to send email / a templated email / a batch mailing from an AntelopeJS module, or when working with symbols like EmailParams, TemplateEmailParams, BatchEmailParams, EmailResponse, Attachment or ProviderCapabilities.
4
+ category: antelopejs-interface
5
+ tags: [antelopejs, email, templates, batch, providers]
6
+ ---
7
+
8
+ # Email interface
9
+
10
+ Provider-agnostic email sending: consumers call four `InterfaceFunction` proxy points (`Send`, `SendBatch`, `SendTemplate`, `GetCapabilities`); a provider module (SendGrid, Mailgun, SES, ...) attaches the implementation at runtime. Everything else in the package is pure TypeScript types — no runtime crossing, no consumer-side helpers.
11
+
12
+ ## Imports
13
+
14
+ The package has a single root export:
15
+
16
+ ```ts
17
+ import { Send, SendBatch, SendTemplate, GetCapabilities } from "@antelopejs/interface-email";
18
+ import type { EmailParams, TemplateEmailParams, BatchEmailParams, EmailResponse, BatchEmailResponse, Attachment, ProviderCapabilities } from "@antelopejs/interface-email";
19
+ ```
20
+
21
+ ## Consuming
22
+
23
+ Add `@antelopejs/interface-email` to the module's `dependencies`, then call the functions — they are all async:
24
+
25
+ ```ts
26
+ import { Send } from "@antelopejs/interface-email";
27
+
28
+ const response = await Send({
29
+ to: { email: "marisol.vega@lakeside-library.example", name: "Marisol Vega" },
30
+ subject: "Your loan is due back Friday",
31
+ html: "<h1>Return reminder</h1>",
32
+ text: "Return reminder",
33
+ attachments: [{ filename: "loan-receipt.pdf", contentType: "application/pdf", path: "/data/loan-receipt.pdf" }],
34
+ });
35
+ if (!response.success) {
36
+ // response.error: { code, message, field?, retryable? }
37
+ }
38
+ ```
39
+
40
+ `SendTemplate` takes `template: { id }` (provider-hosted) or `{ content, type }` (inline) plus `variables` / `recipientVariables`. `SendBatch` takes `{ messages, defaults?, continueOnError? }` and returns per-message results.
41
+
42
+ ## Providing
43
+
44
+ Implementing this interface is the normal way to ship an email provider module:
45
+
46
+ ```ts
47
+ import { ImplementInterface } from "@antelopejs/interface-core";
48
+ import * as EmailInterface from "@antelopejs/interface-email";
49
+
50
+ ImplementInterface(EmailInterface, {
51
+ Send: async (params) => ({ success: true, status: "sent", messageId: "..." }),
52
+ SendBatch: async (params) => ({ success: true, total: 0, successful: 0, failed: 0, responses: [] }),
53
+ SendTemplate: async (params) => ({ success: true, status: "sent" }),
54
+ GetCapabilities: async () => ({ name: "my-provider", features: { batch: true, templates: false, scheduling: false, openTracking: false, clickTracking: false, inlineAttachments: true, tags: false, metadata: false, priority: true } }),
55
+ });
56
+ ```
57
+
58
+ Also declare `"antelopeJs": { "implements": ["@antelopejs/interface-email"] }` in the provider's `package.json`.
59
+
60
+ ## Gotchas
61
+
62
+ - All four functions are async proxy crossings. With the interface in `dependencies`, calls made before the provider attaches are queued (always `await`); startup aborts if no loaded module provides it. Use `optionalDependencies` if email may legitimately be absent.
63
+ - Failures are usually reported in the response, not thrown: check `response.success` and `response.error` (its `retryable` flag tells you whether to retry).
64
+ - Feature support varies by provider — gate `schedule`, `tracking`, `tags`, `metadata`, `priority` and templates on `(await GetCapabilities()).features` before relying on them.
65
+ - `EmailParams` requires only `to` and `subject`; provide at least one of `text` / `html` (both for client compatibility). `from` falls back to the provider default.
66
+ - `Attachment` is a union with exactly one source field: `content: Buffer`, `content` + `encoding: "base64"`, `path`, or `url`. Inline images need `cid` (referenced as `cid:yourCid` in HTML) and `inline: true`.
67
+ - Batch: `continueOnError` defaults to `true`; `BatchEmailResponse.success` is `true` only if *all* messages succeeded — correlate individual results via `batchId` or `index`.
68
+ - `EmailStatus` includes `"queued"` and `"scheduled"` — a successful response does not mean delivered.
69
+
70
+ ## Deeper reference
71
+
72
+ See the shipped `dist/index.d.ts` for the full field-by-field contract, and this package's `docs/` chapters — Introduction, Sending Emails, Attachments — for prose guides. Do not restate them here.