unione 1.1.3 → 1.2.4

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/AGENTS.md CHANGED
@@ -1,77 +1,51 @@
1
1
  # AGENTS.md
2
2
 
3
- UniOne Node.js SDK — client for the UniOne transactional email Web API (Web API 1.90).
3
+ UniOne Node.js SDK — client for the UniOne transactional email Web API (Web API 1.90). How to integrate UniOne into an application comes first; the last section is about changing this package.
4
4
 
5
- ## Working on this repository
6
-
7
- - **Generated code.** The whole package is generated by the UniOne team from the UniOne Web API OpenAPI spec (Web API 1.90): sources, docs, README.md and this file. Do not hand-edit it: the next release replaces the content of this repository. Report problems and requests in the issues of this repository (https://github.com/unione-repo/unione-node-sdk).
8
- - **Build and check:**
9
-
10
- ```bash
11
- npm install
12
- npm pack --dry-run
13
- ```
14
-
15
- - **Source label.** Every request carries the query parameter `platform=node-sdk.1.1.3`, added in one place, the shared request client (`ApiClient`); a package built on this SDK puts its own label in front: `<package>.<version>,node-sdk.1.1.3`.
16
- - **Tests.** Before a release the generator builds and lints the package and runs every example of docs/ and of this file against a mock of the API: no real API key, no real sends.
17
- - **Release.** The version (1.1.3 in package.json) and the tag `v1.1.3` come from the generator; README.md states the Web API version the release was generated from.
18
- - **Secrets.** Never commit API keys; the examples read `UNIONE_API_KEY` from the environment.
19
-
20
- ## Integrating UniOne with this SDK
5
+ ## Integrating UniOne
21
6
 
22
- Full quickstart: [README.md](README.md). Install:
7
+ ### Install
23
8
 
24
9
  ```bash
25
10
  npm install unione
26
11
  ```
27
12
 
28
- Requirements: Node.js 14+.
29
-
30
- Rules that generated code must follow:
31
-
32
- - Server-side only. Read the API key from `UNIONE_API_KEY`; never put it in browser or mobile code, never commit it.
33
- - Base URL `https://api.unione.io/en/transactional/api/v1` (an account registered on another host uses that one: `eu1.unione.io`, `us1.unione.io`); every method is POST with a JSON body; auth header `X-API-KEY`. The SDK does all of it.
34
- - First email without DNS: `domain/get-sandbox-domain` → `confirmed-email/create` (the user clicks the link within 48 hours) → `email/send` from `noreply@<sandbox-domain>` to the confirmed address. Account API key only; up to 10 confirmed addresses, 100 emails a day; the domain expires after 31 days.
35
- - Never ship a sandbox domain as the production sender (it is not in `domain/list`); read `from_email` from config. Production needs a verified domain: `domain/get-dns-records` → DNS records → `domain/validate-verification-record`, `domain/validate-dkim` → `domain/list`.
36
- - Set `message.idempotence_key` on retryable sends; retry network errors, `429` and `5xx` with backoff, not other errors unchanged. Up to 500 recipients and 10 MB per request, each attachment up to 7 MB; always `body.html` or `body.plaintext`.
37
- - Delivery events via webhook (`webhook/set`) with a fast, idempotent HTTPS handler, not polling; check the `auth` field of every notification: the MD5 of the request body with the `auth` value replaced by the API key.
38
- - Keep the default unsubscribe and tracking behaviour; changes go through UniOne support.
39
- - Do not invent methods or fields. Check [docs/](docs/) of this package, the [API reference](https://docs.unione.io/en/web-api-ref) or [llms.txt](https://docs.unione.io/llms.txt).
13
+ Requirements: Node.js 14+. The API key goes to `UNIONE_API_KEY`.
40
14
 
41
15
  ### Send an email
42
16
 
43
- The client reads the API key from `UNIONE_API_KEY`:
44
-
45
17
  ```javascript
46
18
  import { UniOneClient } from "unione";
47
- import { EmailSendRequest, MessageObject, MessageObjectRecipientsItem } from "unione/api/email";
48
- import { BodyObject } from "unione/common";
19
+ import { MessageObjectRecipientsItem as Recipient } from "unione/api/email";
49
20
 
50
21
  const client = new UniOneClient(process.env.UNIONE_API_KEY);
51
22
 
52
- const response = await client.email.send(new EmailSendRequest({
53
- message: new MessageObject({
54
- recipients: [
55
- new MessageObjectRecipientsItem({
56
- email: "user@example.com",
57
- substitutions: {
58
- "CustomerId": "12452",
59
- "to_name": "John Smith",
60
- },
61
- }),
62
- ],
63
- body: new BodyObject({
64
- html: "<b>Hello, {{to_name}}</b>",
65
- plaintext: "Hello, {{to_name}}",
66
- }),
67
- subject: "UniOne test email ",
68
- fromEmail: "email@example.com",
69
- fromName: "John Smith",
70
- }),
71
- }));
72
- console.log(response.jobId);
23
+ const { jobId } = await client.email.send({
24
+ message: {
25
+ recipients: [Recipient.fromAddress("Alex <alex@example.com>")],
26
+ from_email: "shop@example.com",
27
+ from_name: "Shop",
28
+ subject: "Your order",
29
+ body: { html: "<p>Hello, {{to_name}}! Your order has shipped.</p>" },
30
+ },
31
+ });
32
+ console.log(jobId);
73
33
  ```
74
34
 
35
+ Personalization, attachments, CC/BCC, scheduling, safe retries, error handling, the webhook handler and the sandbox flow: the recipes of [README.md](README.md#recipes).
36
+
37
+ ### Rules for generated code
38
+
39
+ - Server-side only. Read the API key from `UNIONE_API_KEY`; never put it in browser or mobile code, never commit it.
40
+ - Build the recipients and the body with the short forms of the SDK (the recipient from `"Name <email>"`, the name goes to `to_name`; per-recipient metadata; the HTML / text body), as in "Send an email" and the README recipes, not with hand-built nested objects.
41
+ - Base URL `https://api.unione.io/en/transactional/api/v1` (an account registered on another host uses that one: `eu1.unione.io`, `us1.unione.io`); every method is POST with a JSON body; auth header `X-API-KEY`. The SDK does all of it.
42
+ - First email without DNS: `domain/get-sandbox-domain` → `confirmed-email/create` (the user clicks the link within 48 hours) → `email/send` from `noreply@<sandbox-domain>` to the confirmed address. Account API key only; up to 10 confirmed addresses, 100 emails a day. The domain is deleted 31 days after it was created: the next `domain/get-sandbox-domain` call creates a new one with another name, so read the name from the response, never hardcode it.
43
+ - Never ship a sandbox domain as the production sender (it is not in `domain/list`); read `from_email` from config. Production needs a verified domain: `domain/get-dns-records` → DNS records (verification TXT as is, DKIM TXT `v=DKIM1; k=rsa; p=<dkim>` on `<selector>._domainkey`, CNAME `_dmarc` → the `dmarc` field; SPF `include:spf.unione.io` is not in the response) → `domain/validate-verification-record`, `domain/validate-dkim` → `domain/list`.
44
+ - Set `message.idempotence_key` on retryable sends; retry network errors, `429` and `5xx` with backoff, not other errors unchanged. Up to 500 recipients and 10 MB per request with the attachments in base64 (a third larger than the files); always `body.html` or `body.plaintext`.
45
+ - Delivery events via webhook (`webhook/set`), not polling. Check the `auth` field of every notification (MD5 of the raw request body with the `auth` value replaced by the API key) and answer 401 to a wrong one. Answer 200 within 3 seconds and process the events from a queue, otherwise the request is repeated every 10 minutes for 24 hours; take at least 5 parallel requests of up to 100 events each; deduplicate.
46
+ - Keep the default unsubscribe and tracking behaviour; changes go through UniOne support.
47
+ - Do not invent methods or fields. Check [docs/](docs/) of this package, the [API reference](https://docs.unione.io/en/web-api-ref) or [llms.txt](https://docs.unione.io/llms.txt).
48
+
75
49
  ### Errors
76
50
 
77
51
  Every method throws `ApiError` when the request fails: the HTTP status (0 for a network error or a timeout), the [API error code](https://docs.unione.io/en/web-api-ref#api-errors) and the message.
@@ -94,3 +68,18 @@ try {
94
68
  - Methods and models of every section: [Email](docs/Email.md), [EmailValidation](docs/EmailValidation.md), [ConfirmedEmail](docs/ConfirmedEmail.md), [Template](docs/Template.md), [Webhook](docs/Webhook.md), [Suppression](docs/Suppression.md), [Domain](docs/Domain.md), [EventDump](docs/EventDump.md), [Tag](docs/Tag.md), [Project](docs/Project.md), [System](docs/System.md), [Obsolete](docs/Obsolete.md)
95
69
  - [API reference](https://docs.unione.io/en/web-api-ref)
96
70
  - [Full API reference for LLMs](https://docs.unione.io/llms-full.txt)
71
+
72
+ ## Working on this repository
73
+
74
+ - **Generated code.** The whole package is generated by the UniOne team from the UniOne Web API OpenAPI spec (Web API 1.90): sources, docs, README.md and this file. Do not hand-edit it: the next release replaces the content of this repository. Report problems and requests in the issues of this repository (https://github.com/unione-repo/unione-node-sdk).
75
+ - **Build and check:**
76
+
77
+ ```bash
78
+ npm install
79
+ npm pack --dry-run
80
+ ```
81
+
82
+ - **Source label.** Every request carries the query parameter `platform=node-sdk.1.2.4`, added in one place, the shared request client (`ApiClient`); a package built on this SDK puts its own label in front: `<package>.<version>,node-sdk.1.2.4`.
83
+ - **Tests.** Before a release the generator builds and lints the package and runs every example of docs/ and of this file against a mock of the API: no real API key, no real sends.
84
+ - **Release.** The version (1.2.4 in package.json) and the tag `v1.2.4` come from the generator; README.md states the Web API version the release was generated from.
85
+ - **Secrets.** Never commit API keys; the examples read `UNIONE_API_KEY` from the environment.
package/README.md CHANGED
@@ -1,10 +1,12 @@
1
- # UniOne Node.js SDK 1.1.3
1
+ # UniOne Node.js SDK
2
2
 
3
- Web API 1.90
3
+ [![Node.js](https://img.shields.io/npm/v/unione)](https://www.npmjs.com/package/unione) [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
4
4
 
5
5
  Official Node.js library for the [UniOne](https://unione.io) transactional email API.
6
6
 
7
- Quickstart guide: [Send emails with Node.js](https://docs.unione.io/en/send-with-nodejs) · Docs for LLMs: [llms.txt](https://docs.unione.io/llms.txt) · [API reference](https://docs.unione.io/en/web-api-ref)
7
+ [API reference](https://docs.unione.io/en/web-api-ref) · Docs for LLMs: [llms.txt](https://docs.unione.io/llms.txt)
8
+
9
+ > **On Express or NestJS?** Install [`unione-express`](https://github.com/unione-repo/unione-express) or [`unione-nestjs`](https://github.com/unione-repo/unione-nestjs) instead: this SDK plus configuration, a mailer and a webhook route.
8
10
 
9
11
  ## Install
10
12
 
@@ -16,104 +18,214 @@ Requirements: Node.js 14+. No third-party dependencies.
16
18
 
17
19
  This is the 1.x line (branch `1.x`) for Node.js 14. Newer runtimes: the 2.x line (branch `main`), the same API.
18
20
 
19
- ## Get an API key
20
-
21
- 1. Sign up at [cp.unione.io](https://cp.unione.io/en/user/registration/).
22
- 2. Copy your API key from [Settings → Security → API](https://cp.unione.io/en/settings/security/api).
23
- 3. Put it in an environment variable:
21
+ Get an API key in the [control panel](https://cp.unione.io/en/settings/security/api) and keep it in the environment, never in code:
24
22
 
25
23
  ```bash
26
24
  export UNIONE_API_KEY="your-api-key"
27
25
  ```
28
26
 
29
- > **Server-side only.** Use this SDK in backend code: API routes, server functions, workers.
30
- > Never ship the API key to a browser or a mobile app, and never commit it.
27
+ ## Send an email
28
+
29
+ ```javascript
30
+ import { UniOneClient } from "unione";
31
+ import { MessageObjectRecipientsItem as Recipient } from "unione/api/email";
32
+
33
+ const client = new UniOneClient(process.env.UNIONE_API_KEY);
34
+
35
+ const { jobId } = await client.email.send({
36
+ message: {
37
+ recipients: [Recipient.fromAddress("Alex <alex@example.com>")],
38
+ from_email: "shop@example.com",
39
+ from_name: "Shop",
40
+ subject: "Your order",
41
+ body: { html: "<p>Hello, {{to_name}}! Your order has shipped.</p>" },
42
+ },
43
+ });
44
+ console.log(jobId);
45
+ ```
46
+
47
+ The sender address must be on a domain verified in your account. No domain yet? Send from the [sandbox domain](#no-domain-yet-the-test-sandbox-domain) in three steps.
31
48
 
32
- ## Send your first email — no DNS setup
49
+ ## Contents
33
50
 
34
- Every account can send test email right away from a **sandbox domain**: pre-verified, DKIM and SPF already set.
35
- It delivers only to addresses you confirm.
51
+ - [Recipes](#recipes): personalization · attachments · CC and BCC · scheduling · safe retries · errors · webhooks
52
+ - [No domain yet: the test sandbox domain](#no-domain-yet-the-test-sandbox-domain)
53
+ - [Going to production](#going-to-production)
54
+ - [Reference](#reference)
55
+ - [Help](#help)
36
56
 
37
- <!-- checked examples -->
57
+ ## Recipes
38
58
 
39
- **1. Get your sandbox domain** (`domain/get-sandbox-domain`). The call creates the domain on first use and returns the same one afterwards.
59
+ Every recipe continues the example above: the client and its imports are there.
40
60
 
41
- ```javascript
42
- import { UniOneClient } from "unione";
61
+ ### Personalize for each recipient
43
62
 
44
- const client = new UniOneClient(process.env.UNIONE_API_KEY);
63
+ Up to 500 recipients per call, each gets a separate copy with its own substitutions. Metadata of a recipient comes back in its webhook events.
45
64
 
46
- const response = await client.domain.getSandboxDomain();
47
- console.log(response.domain);
65
+ ```javascript
66
+ await client.email.send({
67
+ message: {
68
+ recipients: [
69
+ Recipient.fromAddress("Alex <alex@example.com>", { order: "1001" })
70
+ .withMetadata({ user_id: "42" }),
71
+ Recipient.fromAddress("Maria <maria@example.com>", { order: "1002" })
72
+ .withMetadata({ user_id: "43" }),
73
+ ],
74
+ from_email: "shop@example.com",
75
+ subject: "Order #{{order}}",
76
+ body: { html: "<p>{{to_name}}, order #{{order}} has shipped.</p>" },
77
+ },
78
+ });
48
79
  ```
49
80
 
50
- **2. Confirm your inbox** (`confirmed-email/create`). UniOne sends a confirmation email; click the link in it within 48 hours.
81
+ ### Attach a file
51
82
 
52
83
  ```javascript
53
- import { UniOneClient } from "unione";
54
- import { ConfirmedEmailRequest } from "unione/api/confirmed-email";
84
+ import { readFile } from "node:fs/promises";
55
85
 
56
- const client = new UniOneClient(process.env.UNIONE_API_KEY);
86
+ const content = (await readFile("invoice.pdf")).toString("base64");
57
87
 
58
- const response = await client.confirmedEmail.create(new ConfirmedEmailRequest({
59
- email: "you@example.com",
60
- }));
61
- console.log(response.confirmedEmail);
88
+ await client.email.send({
89
+ message: {
90
+ recipients: [Recipient.fromAddress("alex@example.com")],
91
+ from_email: "shop@example.com",
92
+ subject: "Invoice",
93
+ body: { html: "<p>Your invoice is attached.</p>" },
94
+ attachments: [{ type: "application/pdf", name: "invoice.pdf", content }],
95
+ },
96
+ });
62
97
  ```
63
98
 
64
- Check the status with `confirmed-email/list` — your address should show `"status": "confirmed"`.
99
+ ### CC and BCC
65
100
 
66
- **3. Send the email** (`email/send`) from any address on the sandbox domain to the confirmed address.
101
+ Every address goes to `recipients` (each gets a copy); the visible ones also go to the headers. `audit@example.com` is in neither header: a BCC. The rules and limits: [CC and BCC](https://docs.unione.io/en/cc-and-bcc).
67
102
 
68
103
  ```javascript
69
- import { UniOneClient } from "unione";
70
- import { EmailSendRequest, MessageObject, MessageObjectRecipientsItem } from "unione/api/email";
71
- import { BodyObject } from "unione/common";
104
+ await client.email.send({
105
+ message: {
106
+ recipients: ["alex@example.com", "boss@example.com", "audit@example.com"].map((a) => Recipient.fromAddress(a)),
107
+ from_email: "shop@example.com",
108
+ subject: "Weekly report",
109
+ body: { html: "<p>The report is attached.</p>" },
110
+ headers: { To: "alex@example.com", CC: "boss@example.com" },
111
+ },
112
+ });
113
+ ```
72
114
 
73
- const client = new UniOneClient(process.env.UNIONE_API_KEY);
115
+ ### Schedule
74
116
 
75
- const response = await client.email.send(new EmailSendRequest({
76
- message: new MessageObject({
77
- recipients: [
78
- new MessageObjectRecipientsItem({
79
- email: "you@example.com",
80
- }),
81
- ],
82
- body: new BodyObject({
83
- html: "<p>It works!</p>",
84
- }),
85
- subject: "Hello from UniOne",
86
- fromEmail: "noreply@<sandbox-domain>",
87
- }),
88
- }));
89
- console.log(response.jobId);
117
+ `send_at` is UTC, up to 24 hours ahead.
118
+
119
+ ```javascript
120
+ // UTC, "YYYY-MM-DD hh:mm:ss"
121
+ const inOneHour = new Date(Date.now() + 3600_000).toISOString().slice(0, 19).replace("T", " ");
122
+
123
+ await client.email.send({
124
+ message: {
125
+ recipients: [Recipient.fromAddress("alex@example.com")],
126
+ from_email: "shop@example.com",
127
+ subject: "Reminder",
128
+ body: { plaintext: "See you tomorrow!" },
129
+ options: { send_at: inOneHour },
130
+ },
131
+ });
132
+ ```
133
+
134
+ ### Retry safely
135
+
136
+ A repeat with the same `idempotence_key` within a minute is not sent twice: retry network errors, timeouts, 429 and 5xx with it.
137
+
138
+ ```javascript
139
+ await client.email.send({
140
+ message: {
141
+ recipients: [Recipient.fromAddress("alex@example.com")],
142
+ from_email: "shop@example.com",
143
+ subject: "Reset your password",
144
+ body: { html: "<p>Use this link to reset your password.</p>" },
145
+ idempotence_key: "password-reset-8f3a",
146
+ },
147
+ });
90
148
  ```
91
149
 
92
- <!-- /checked examples -->
150
+ ### Handle errors
93
151
 
94
- ### What you get back
152
+ Recipients the API drops (unsubscribed, invalid, suppressed) are not an error: they are in `failed_emails` of the response, the rest still get the message.
153
+
154
+ ```javascript
155
+ import { ApiError } from "unione";
95
156
 
96
- ```json
97
- {
98
- "status": "success",
99
- "job_id": "1ZymBc-00041N-9X",
100
- "emails": [
101
- "you@example.com"
102
- ]
157
+ try {
158
+ await client.email.send(request);
159
+ } catch (e) {
160
+ if (!(e instanceof ApiError)) throw e;
161
+ // HTTP status (0: network error or timeout), API error code, message
162
+ console.error(e.httpStatus, e.errorCode, e.message);
103
163
  }
104
164
  ```
105
165
 
106
- On error the API returns `status: "error"`, a `message` and a numeric `code`:
166
+ ### Receive delivery events
167
+
168
+ Register your HTTPS endpoint once (`webhook/set`). Then check the signature of every notification (`auth`: MD5 of the raw body with the `auth` value replaced by your API key; a wrong one gets 401) and process the events.
107
169
 
108
- ```json
109
- {
110
- "status": "error",
111
- "code": 102,
112
- "message": "Error ID:83274F98-C7D5-11F1-B221-6214FF8707B1. Can not decode key wrongkey"
170
+ ```javascript
171
+ import { createHash } from "node:crypto";
172
+ import { WebhookApi } from "unione/api/webhook";
173
+
174
+ // rawBody: the body of the POST request as received; returns the HTTP status to answer
175
+ function handleWebhook(rawBody) {
176
+ const callback = WebhookApi.parseCallback(rawBody);
177
+ // auth: MD5 of the raw body with the auth value replaced by your API key
178
+ const signed = rawBody.replace(callback.auth, process.env.UNIONE_API_KEY);
179
+ if (createHash("md5").update(signed).digest("hex") !== callback.auth) return 401;
180
+
181
+ for (const user of callback.eventsByUser ?? []) {
182
+ for (const event of user.events ?? []) {
183
+ // event.eventData: email, status (delivered, opened, hard_bounced, spam, ...), jobId, metadata
184
+ }
185
+ }
186
+ return 200;
113
187
  }
114
188
  ```
115
189
 
116
- ### Same flow with curl
190
+ > **Answer 200 within 3 seconds** and process the events in the background (a queue): otherwise UniOne repeats the request every 10 minutes for 24 hours (`retry_count` grows), and a handler that failed every request for at least 10 events of a day is turned inactive. The handler must take at least **5 parallel requests of up to 100 events each**; deduplicate, a repeat delivers the same events again.
191
+
192
+ ## No domain yet: the test sandbox domain
193
+
194
+ Until your domain is verified, send from the **sandbox domain**: a test domain every account has, already verified, with DKIM and SPF set. It delivers only to addresses you confirm (the confirmation link comes by email, valid 48 hours), up to 100 emails a day. The sandbox domain is deleted 31 days after it was created, but you can get it again: the next `domain/get-sandbox-domain` call creates a new one (with a new name, so read it from the call, do not hardcode it).
195
+
196
+ ```javascript
197
+ // 1. Your sandbox domain: created on the first call, the same one afterwards
198
+ const { domain } = await client.domain.getSandboxDomain();
199
+
200
+ // 2. Confirm your inbox: UniOne sends a link, click it within 48 hours
201
+ await client.confirmedEmail.create({ email: "you@example.com" });
202
+
203
+ // 3. Send from any address on the sandbox domain to the confirmed one
204
+ await client.email.send({
205
+ message: {
206
+ recipients: [Recipient.fromAddress("you@example.com")],
207
+ from_email: `noreply@${domain}`,
208
+ subject: "Hello from UniOne",
209
+ body: { html: "<p>It works!</p>" },
210
+ },
211
+ });
212
+ ```
213
+
214
+ <details>
215
+ <summary>Sandbox limits</summary>
216
+
217
+ - Sends only to confirmed addresses: up to 10 per account.
218
+ - Up to 100 emails a day.
219
+ - The sandbox domain expires after 31 days; call `domain/get-sandbox-domain` again to get a new one.
220
+ - Works only with the account API key, not a project key.
221
+ - Not listed in `domain/list`; the other `domain/*` methods do not apply to it.
222
+
223
+ The sandbox is for development and testing. Do not use a sandbox domain as the sender in production.
224
+
225
+ </details>
226
+
227
+ <details>
228
+ <summary>The same with curl</summary>
117
229
 
118
230
  ```bash
119
231
  BASE=https://api.unione.io/en/transactional/api/v1
@@ -143,58 +255,51 @@ curl -s -X POST $BASE/email/send.json \
143
255
  }'
144
256
  ```
145
257
 
146
- ## Sandbox limits
147
-
148
- - Sends only to confirmed addresses: up to 10 per account.
149
- - Up to 100 emails a day.
150
- - The sandbox domain expires after 31 days; call `domain/get-sandbox-domain` again to get a new one.
151
- - Works only with the account API key, not a project key.
152
- - Not listed in `domain/list`; the other `domain/*` methods do not apply to it.
153
-
154
- The sandbox is for development and testing. Do not use a sandbox domain as the sender in production.
155
-
156
- ## Before production: verify your domain
258
+ </details>
157
259
 
158
- 1. `domain/get-dns-records` — returns the values for your DNS records.
159
- 2. Add these records at your DNS provider (the domain page of the control panel shows them too):
260
+ ## Going to production
160
261
 
161
- | Type | Host | Value |
162
- |---|---|---|
163
- | TXT | `@` | the `verification-record` value (`unione-validate-hash=…`) |
164
- | TXT | `<selector>._domainkey` (the selector is on the domain page of the control panel, e.g. `us`) | `v=DKIM1; k=rsa; p=<dkim>` |
165
- | TXT | `@` | `v=spf1 include:spf.unione.io ~all` |
166
- | CNAME | `_dmarc` | the `dmarc` value |
262
+ **1. Verify your sending domain.** `domain/get-dns-records` returns the verification record, the DKIM key and the DMARC target; add the records at your DNS provider, then `domain/validate-verification-record` and `domain/validate-dkim`.
167
263
 
168
- 3. `domain/validate-verification-record`, then `domain/validate-dkim`.
169
- 4. `domain/list` — wait until the verification record is confirmed and DKIM is active.
170
- 5. Read `from_email` from your config, so switching from the sandbox needs no code change.
264
+ | Type | Host | Value | Where it comes from |
265
+ |---|---|---|---|
266
+ | TXT | `@` | `unione-validate-hash=…` | `verification-record` of the response, as is |
267
+ | TXT | `<selector>._domainkey` (the selector is on the domain page of the control panel, e.g. `us`) | `v=DKIM1; k=rsa; p=<dkim>` | `dkim` of the response after `v=DKIM1; k=rsa; p=` |
268
+ | TXT | `@` | `v=spf1 include:spf.unione.io ~all` | not in the response; add the include to your SPF record if you have one |
269
+ | CNAME | `_dmarc` | `<domain>.dmarc.…` | `dmarc` of the response (UniOne publishes the DMARC policy); keep your own DMARC TXT record instead if the domain has one |
171
270
 
172
- ## Sending reliably
271
+ **2. Make sending reliable.**
173
272
 
174
- - **Retries:** set `message.idempotence_key` on sends that may be retried, so a repeated request does not send twice.
175
- - **Limits:** up to 500 recipients and 10 MB per request; each attachment up to 7 MB.
176
- - **Body:** always include `body.html` or `body.plaintext`.
177
- - **Delivery status:** register a webhook (`webhook/set`) with a fast, idempotent HTTPS handler instead of polling.
178
- - **Defaults:** keep the default unsubscribe footer and tracking; changing them requires UniOne support.
179
- - **Errors:** retry `429` and `5xx` with backoff; do not retry other errors unchanged.
273
+ | | |
274
+ |---|---|
275
+ | Retries | `429` and `5xx` with backoff and the same `idempotence_key`; fix other errors instead of retrying |
276
+ | Limits | 500 recipients and 10 MB per request, attachments included: base64 makes a file about a third larger |
277
+ | Body | always `html` or `plaintext` (a template can supply it) |
278
+ | Delivery status | a webhook, not polling |
279
+ | Queue | send from a background job, not inside the web request |
280
+ | Config | `from_email` from config, so the sandbox → production switch needs no code change |
281
+ | Defaults | keep the unsubscribe footer and tracking; changing them needs UniOne support |
180
282
 
181
- ## Links
283
+ ## Reference
182
284
 
183
- - [Send emails with Node.js](https://docs.unione.io/en/send-with-nodejs) and other [integration guides](https://docs.unione.io/en/integrations/)
184
- - [Web API reference](https://docs.unione.io/en/web-api-ref)
185
- - [llms.txt](https://docs.unione.io/llms.txt) for AI coding agents
186
- - [UniOne MCP server and agent setup](https://unione.io/en/agents)
187
- - [Support](https://cp.unione.io/en/support)
285
+ ### Sections
188
286
 
189
- ## For SDK contributors
190
-
191
- See [AGENTS.md](AGENTS.md): how this SDK is generated from the OpenAPI spec, built, tested and released.
192
-
193
- ---
194
-
195
- # SDK reference
287
+ | Section | Methods | Description |
288
+ |---|---|---|
289
+ | [Email](docs/Email.md) | `send`, `subscribe` | This group of methods is related with email sending. |
290
+ | [EmailValidation](docs/EmailValidation.md) | `single` | Email validation methods. As a result of the check, you’ll get detailed information on email validity. It will help eliminate nonexistent emails, decrease the number of complaints, clean up the subscribers list and eventually enhance your sender reputation score. For example, you may add validation to a subscription form on your site to let users know they’ve just entered an invalid address. |
291
+ | [ConfirmedEmail](docs/ConfirmedEmail.md) | `create`, `list`, `delete` | Manage email addresses confirmed for sandbox-domain sending. These methods are available only with a main account API key. |
292
+ | [Template](docs/Template.md) | `set`, `get`, `list`, `delete` | You have the option of storing a template on the UniOne side and then using it by id, which is highly recommended for sending repetitive messages or high volume traffic. UniOne supports two different [template engines](https://docs.unione.io/en/template-engines). |
293
+ | [Webhook](docs/Webhook.md) | `set`, `get`, `list`, `delete` | UniOne lets you recieve notifications about email status changes or spam blocks. You provide an URL and every time a watched event occurs we will notify you by submitting a request with JSON data to this URL. |
294
+ | [Suppression](docs/Suppression.md) | `set`, `get`, `list`, `delete` | Methods for managing suppression lists. An email can be added to suppression list because of unsubscription, bounce or complain. |
295
+ | [Domain](docs/Domain.md) | `getDnsRecords`, `validateVerificationRecord`, `validateDkim`, `list`, `getSandboxDomain`, `delete` | You can use these methods to setup sender domains and check their statuses. They might be useful in case you want to automate adding domains for your own clients. |
296
+ | [EventDump](docs/EventDump.md) | `create`, `get`, `list`, `delete` | These methods are used to obtain a list of events for a given period of time. The data is stored for up to 45 days, depending on your tariff, i. e. you may fetch all event data starting from 00:00:00 31 days ago and up to current time. For custom tarifs with big sending volumes event dumps are available only for the last 7 days. |
297
+ | [Tag](docs/Tag.md) | `list`, `delete` | This family of methods is used to manage user-defined tags. Tags are used to categorize letters based on your own criteria, e. g. to create a distinction between marketing and transactional letters or group together all notifications for a particular order type. UniOne allows you to assign tags to all outgoing emails, and the tags you’ve set may then be used to filter and analyze delivery statistics. |
298
+ | [Project](docs/Project.md) | `create`, `update`, `list`, `delete` | Projects allow you to group several independent domains, webhooks, templates, and unsubscription lists together. It's very useful if you have your own clients and manage their data from a single UniOne account. Each project receives its own API key, and all API calls with that API key only deal with the data of that project. This way, you can assign a separate project for each client and be sure that they won't conflict; e.g. unsubscribing from one project won't affect another. |
299
+ | [System](docs/System.md) | `ping`, `info` | System operations. |
300
+ | [Obsolete](docs/Obsolete.md) | `unsubscribedSet`, `unsubscribedCheck`, `unsubscribedList` | Obsolete methods dealing with unsubscribes. We recommend using the more flexible [suppression](https://docs.unione.io/en/web-api-ref#suppression) methods instead. Note that you can't resubscribe an unsubscribed recipient using WebAPI, but you can send him an email with subscription link using email/subscribe method. |
196
301
 
197
- ## API host
302
+ ### API host
198
303
 
199
304
  The second argument selects the API host (datacenter) or a full base URL.
200
305
 
@@ -205,11 +310,11 @@ const client = new UniOneClient("YOUR_API_KEY", "us1.unione.io");
205
310
  const other = new UniOneClient("YOUR_API_KEY", Host.US1, { timeout: 10000 });
206
311
  ```
207
312
 
208
- ## Error handling
313
+ ### Error handling
209
314
 
210
315
  Every method raises `ApiError` when the API returns an error; it carries the [API error code](https://docs.unione.io/en/web-api-ref#api-errors) and the HTTP status.
211
316
 
212
- ## Custom HTTP client and headers
317
+ ### Custom HTTP client and headers
213
318
 
214
319
  `headers` adds headers to every request; `fetch` replaces the function the requests go through (default: the built-in `http`/`https` modules): undici, node-fetch or a wrapper that adds retries, logging or a proxy. Network errors, timeouts and errors of reading the response raise `ApiError` (the original error is its `cause`).
215
320
 
@@ -243,7 +348,7 @@ try {
243
348
  }
244
349
  ```
245
350
 
246
- ## Models
351
+ ### Models
247
352
 
248
353
  Request models take an object of their fields; a nested model can be given as a model or as a plain object in the API format (the keys of the API: `global_language`, not `globalLanguage`), it is converted by `fromJSON()` of its class. A request may also be a plain object in the API format. Models that take any key (`HeadersObject`) keep the keys besides their named fields in the `extra` map: it is sent next to the fields (a named field wins over the same key of `extra`), and the keys of a response that are not named fields go there.
249
354
 
@@ -271,7 +376,7 @@ const request = new EmailSendRequest({
271
376
  console.log(JSON.stringify(request));
272
377
  ```
273
378
 
274
- ## TypeScript
379
+ ### TypeScript
275
380
 
276
381
  The package has type declarations: the client, the API classes, the models (with their `...JSON` shape in the API format and `...Init` constructor options) and the enums (frozen objects and string literal types).
277
382
 
@@ -315,19 +420,9 @@ const response: EmailSendResponse = await client.email.send(new EmailSendRequest
315
420
  }));
316
421
  ```
317
422
 
318
- ## Sections
423
+ ## Help
319
424
 
320
- | Section | Methods | Description |
321
- |---|---|---|
322
- | [Email](docs/Email.md) | `send`, `subscribe` | This group of methods is related with email sending. |
323
- | [EmailValidation](docs/EmailValidation.md) | `single` | Email validation methods. As a result of the check, you’ll get detailed information on email validity. It will help eliminate nonexistent emails, decrease the number of complaints, clean up the subscribers list and eventually enhance your sender reputation score. For example, you may add validation to a subscription form on your site to let users know they’ve just entered an invalid address. |
324
- | [ConfirmedEmail](docs/ConfirmedEmail.md) | `create`, `list`, `delete` | Manage email addresses confirmed for sandbox-domain sending. These methods are available only with a main account API key. |
325
- | [Template](docs/Template.md) | `set`, `get`, `list`, `delete` | You have the option of storing a template on the UniOne side and then using it by id, which is highly recommended for sending repetitive messages or high volume traffic. UniOne supports two different [template engines](https://docs.unione.io/en/template-engines). |
326
- | [Webhook](docs/Webhook.md) | `set`, `get`, `list`, `delete` | UniOne lets you recieve notifications about email status changes or spam blocks. You provide an URL and every time a watched event occurs we will notify you by submitting a request with JSON data to this URL. |
327
- | [Suppression](docs/Suppression.md) | `set`, `get`, `list`, `delete` | Methods for managing suppression lists. An email can be added to suppression list because of unsubscription, bounce or complain. |
328
- | [Domain](docs/Domain.md) | `getDnsRecords`, `validateVerificationRecord`, `validateDkim`, `list`, `getSandboxDomain`, `delete` | You can use these methods to setup sender domains and check their statuses. They might be useful in case you want to automate adding domains for your own clients. |
329
- | [EventDump](docs/EventDump.md) | `create`, `get`, `list`, `delete` | These methods are used to obtain a list of events for a given period of time. The data is stored for up to 45 days, depending on your tariff, i. e. you may fetch all event data starting from 00:00:00 31 days ago and up to current time. For custom tarifs with big sending volumes event dumps are available only for the last 7 days. |
330
- | [Tag](docs/Tag.md) | `list`, `delete` | This family of methods is used to manage user-defined tags. Tags are used to categorize letters based on your own criteria, e. g. to create a distinction between marketing and transactional letters or group together all notifications for a particular order type. UniOne allows you to assign tags to all outgoing emails, and the tags you’ve set may then be used to filter and analyze delivery statistics. |
331
- | [Project](docs/Project.md) | `create`, `update`, `list`, `delete` | Projects allow you to group several independent domains, webhooks, templates, and unsubscription lists together. It's very useful if you have your own clients and manage their data from a single UniOne account. Each project receives its own API key, and all API calls with that API key only deal with the data of that project. This way, you can assign a separate project for each client and be sure that they won't conflict; e.g. unsubscribing from one project won't affect another. |
332
- | [System](docs/System.md) | `ping`, `info` | System operations. |
333
- | [Obsolete](docs/Obsolete.md) | `unsubscribedSet`, `unsubscribedCheck`, `unsubscribedList` | Obsolete methods dealing with unsubscribes. We recommend using the more flexible [suppression](https://docs.unione.io/en/web-api-ref#suppression) methods instead. Note that you can't resubscribe an unsubscribed recipient using WebAPI, but you can send him an email with subscription link using email/subscribe method. |
425
+ - [Integration guides](https://docs.unione.io/en/integrations)
426
+ - AI coding agents: [llms.txt](https://docs.unione.io/llms.txt), the [MCP server](https://unione.io/en/agents), skills: `npx skills add https://github.com/unione-repo/unione-skills.git`
427
+ - [Support](https://cp.unione.io/en/support) · [Issues](https://github.com/unione-repo/unione-node-sdk/issues)
428
+ - Contributing: [AGENTS.md](AGENTS.md) — the SDK is generated from the OpenAPI spec.
package/docs/Domain.md CHANGED
@@ -33,13 +33,16 @@ You should add then DNS records like this to all of the domains you want to conf
33
33
 
34
34
  `@ IN TXT "unione-validate-hash=483bb362ebdbeedd755cfb1d4d661"`
35
35
 
36
- `us._domainkey IN TXT "k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDo7"`
36
+ `us._domainkey IN TXT "v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDo7"`
37
37
 
38
38
  `@ IN TXT "v=spf1 include:spf.unione.io ~all"`
39
39
 
40
+ `_dmarc IN CNAME "example.com.dmarc.unione.io."`
41
+
40
42
  - First record value should contain "verification-record" field returned by get-dns-records method "as is".
41
- - Second record value should contain "dkim" field value after "p=". Mind the name of this record! "us._domainkey." prefix is important for DKIM selector of UniOne to work properly.
42
- - Third record contains optional, but very recommended SPF entry. Probably you already have one, then just add append include:spf.unione.io right after v=spf1.
43
+ - Second record value should contain "dkim" field value after "v=DKIM1; k=rsa; p=". Mind the name of this record! "us._domainkey." prefix is important for DKIM selector of UniOne to work properly.
44
+ - Third record contains optional, but very recommended SPF entry. It is not returned by the method. Probably you already have one, then just add append include:spf.unione.io right after v=spf1.
45
+ - Fourth record is a CNAME of the "_dmarc" host to the "dmarc" field value: UniOne then publishes the DMARC policy of the domain. If the domain already has its own DMARC TXT record, keep it instead.
43
46
 
44
47
  Syntax requirements of different DNS providers may differ:
45
48
  - sometimes it's necesarry to put full domain name instead of @ sign.
@@ -192,6 +195,8 @@ Creates a sandbox domain for the account or returns the existing one.
192
195
 
193
196
  Returns an account sandbox domain that is ready for use in the `from_email` field of [email/send](https://docs.unione.io/en/web-api-ref#email-send). If the account has no sandbox domain, UniOne creates one and returns it. Repeated calls return the same domain.
194
197
 
198
+ The sandbox domain is removed 31 days after it was created; the next call creates a new one. Up to 100 emails a day can be sent from it (the default limit of the account).
199
+
195
200
  The method is available only with an account API key. Project API keys cannot create sandbox domains.
196
201
 
197
202
  ### Request
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "unione",
3
- "version": "1.1.3",
3
+ "version": "1.2.4",
4
4
  "description": "UniOne Web API client library for Node.js",
5
5
  "type": "module",
6
6
  "main": "./src/index.js",
@@ -28,13 +28,16 @@ export declare class DomainApi {
28
28
  *
29
29
  * `@ IN TXT "unione-validate-hash=483bb362ebdbeedd755cfb1d4d661"`
30
30
  *
31
- * `us._domainkey IN TXT "k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDo7"`
31
+ * `us._domainkey IN TXT "v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDo7"`
32
32
  *
33
33
  * `@ IN TXT "v=spf1 include:spf.unione.io ~all"`
34
34
  *
35
+ * `_dmarc IN CNAME "example.com.dmarc.unione.io."`
36
+ *
35
37
  * - First record value should contain "verification-record" field returned by get-dns-records method "as is".
36
- * - Second record value should contain "dkim" field value after "p=". Mind the name of this record! "us._domainkey." prefix is important for DKIM selector of UniOne to work properly.
37
- * - Third record contains optional, but very recommended SPF entry. Probably you already have one, then just add append include:spf.unione.io right after v=spf1.
38
+ * - Second record value should contain "dkim" field value after "v=DKIM1; k=rsa; p=". Mind the name of this record! "us._domainkey." prefix is important for DKIM selector of UniOne to work properly.
39
+ * - Third record contains optional, but very recommended SPF entry. It is not returned by the method. Probably you already have one, then just add append include:spf.unione.io right after v=spf1.
40
+ * - Fourth record is a CNAME of the "_dmarc" host to the "dmarc" field value: UniOne then publishes the DMARC policy of the domain. If the domain already has its own DMARC TXT record, keep it instead.
38
41
  *
39
42
  * Syntax requirements of different DNS providers may differ:
40
43
  * - sometimes it's necesarry to put full domain name instead of @ sign.
@@ -92,6 +95,9 @@ export declare class DomainApi {
92
95
  * [email/send](https://docs.unione.io/en/web-api-ref#email-send). If the account has no sandbox
93
96
  * domain, UniOne creates one and returns it. Repeated calls return the same domain.
94
97
  *
98
+ * The sandbox domain is removed 31 days after it was created; the next call creates a new one. Up to
99
+ * 100 emails a day can be sent from it (the default limit of the account).
100
+ *
95
101
  * The method is available only with an account API key. Project API keys cannot create sandbox
96
102
  * domains.
97
103
  *
@@ -29,13 +29,16 @@ export class DomainApi {
29
29
  *
30
30
  * `@ IN TXT "unione-validate-hash=483bb362ebdbeedd755cfb1d4d661"`
31
31
  *
32
- * `us._domainkey IN TXT "k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDo7"`
32
+ * `us._domainkey IN TXT "v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDo7"`
33
33
  *
34
34
  * `@ IN TXT "v=spf1 include:spf.unione.io ~all"`
35
35
  *
36
+ * `_dmarc IN CNAME "example.com.dmarc.unione.io."`
37
+ *
36
38
  * - First record value should contain "verification-record" field returned by get-dns-records method "as is".
37
- * - Second record value should contain "dkim" field value after "p=". Mind the name of this record! "us._domainkey." prefix is important for DKIM selector of UniOne to work properly.
38
- * - Third record contains optional, but very recommended SPF entry. Probably you already have one, then just add append include:spf.unione.io right after v=spf1.
39
+ * - Second record value should contain "dkim" field value after "v=DKIM1; k=rsa; p=". Mind the name of this record! "us._domainkey." prefix is important for DKIM selector of UniOne to work properly.
40
+ * - Third record contains optional, but very recommended SPF entry. It is not returned by the method. Probably you already have one, then just add append include:spf.unione.io right after v=spf1.
41
+ * - Fourth record is a CNAME of the "_dmarc" host to the "dmarc" field value: UniOne then publishes the DMARC policy of the domain. If the domain already has its own DMARC TXT record, keep it instead.
39
42
  *
40
43
  * Syntax requirements of different DNS providers may differ:
41
44
  * - sometimes it's necesarry to put full domain name instead of @ sign.
@@ -109,6 +112,9 @@ export class DomainApi {
109
112
  * [email/send](https://docs.unione.io/en/web-api-ref#email-send). If the account has no sandbox
110
113
  * domain, UniOne creates one and returns it. Repeated calls return the same domain.
111
114
  *
115
+ * The sandbox domain is removed 31 days after it was created; the next call creates a new one. Up to
116
+ * 100 emails a day can be sent from it (the default limit of the account).
117
+ *
112
118
  * The method is available only with an account API key. Project API keys cannot create sandbox
113
119
  * domains.
114
120
  *
@@ -421,6 +421,10 @@ export declare class MessageObjectRecipientsItem {
421
421
  metadata?: Record<string, string>;
422
422
  /** Builds the object from decoded JSON. */
423
423
  static fromJSON(data: Record<string, any>): MessageObjectRecipientsItem;
424
+ /** A recipient from "email" or "Name <email>": the name goes to the to_name substitution. */
425
+ static fromAddress(address: string, substitutions?: Record<string, string>): MessageObjectRecipientsItem;
426
+ /** Sets the metadata of the recipient (returned in its webhook events) and returns the recipient. */
427
+ withMetadata(metadata: Record<string, string>): this;
424
428
  /** JSON-ready object in the API format, empty fields are omitted. */
425
429
  toJSON(): MessageObjectRecipientsItemJSON;
426
430
  }
@@ -381,6 +381,35 @@ export class MessageObjectRecipientsItem {
381
381
  });
382
382
  }
383
383
 
384
+ /**
385
+ * A recipient from "email" or "Name <email>": the name goes to the to_name substitution (the name in the
386
+ * "To" header).
387
+ * @param {string} address
388
+ * @param {Record<string, string>} [substitutions] More substitutions of the recipient.
389
+ * @returns {MessageObjectRecipientsItem}
390
+ */
391
+ static fromAddress(address, substitutions) {
392
+ let email = String(address).trim();
393
+ let name = "";
394
+ const match = /^(.*)<([^>]+)>$/s.exec(email);
395
+ if (match) {
396
+ email = match[2].trim();
397
+ name = match[1].trim().replace(/^"|"$/g, "");
398
+ }
399
+ const subs = name ? { to_name: name, ...substitutions } : substitutions;
400
+ return new MessageObjectRecipientsItem({ email: email, substitutions: subs });
401
+ }
402
+
403
+ /**
404
+ * Sets the metadata of the recipient (returned in its webhook events) and returns the recipient.
405
+ * @param {Record<string, string>} metadata
406
+ * @returns {this}
407
+ */
408
+ withMetadata(metadata) {
409
+ this.metadata = metadata;
410
+ return this;
411
+ }
412
+
384
413
  /**
385
414
  * JSON-ready object in the API format, empty fields are omitted.
386
415
  * @returns {Record<string, any>}
@@ -36,7 +36,7 @@ export function extraFields(data, names) {
36
36
  }
37
37
 
38
38
  /** The SDK and its version in the "platform" query parameter of every request. */
39
- export const PLATFORM = "node-sdk.1.1.3";
39
+ export const PLATFORM = "node-sdk.1.2.4";
40
40
 
41
41
  /**
42
42
  * Sets a header, replacing one of the same name in another case.
@@ -36,7 +36,7 @@ export class Configuration {
36
36
  * that uses the SDK and its version (e.g. "express.1.0.0"), sent in the "platform" query parameter before the SDK
37
37
  * one (PLATFORM); headers: extra headers of every request; fetch: a fetch-compatible function, default: the built-in http/https modules.
38
38
  */
39
- constructor(apiKey, { baseUrl = DEFAULT_BASE_URL, timeout = 30000, userAgent = "unione-node-sdk/1.1.3", platform, headers = {}, fetch } = {}) {
39
+ constructor(apiKey, { baseUrl = DEFAULT_BASE_URL, timeout = 30000, userAgent = "unione-node-sdk/1.2.4", platform, headers = {}, fetch } = {}) {
40
40
  this.apiKey = apiKey;
41
41
  this.baseUrl = baseUrl.replace(/\/+$/, "");
42
42
  this.timeout = timeout;
@@ -95,6 +95,10 @@ export declare class BodyObject {
95
95
  amp?: string;
96
96
  /** Builds the object from decoded JSON. */
97
97
  static fromJSON(data: Record<string, any>): BodyObject;
98
+ /** An HTML body, with an optional plain-text part. */
99
+ static html(html: string, plaintext?: string): BodyObject;
100
+ /** A plain-text body. */
101
+ static text(plaintext: string): BodyObject;
98
102
  /** JSON-ready object in the API format, empty fields are omitted. */
99
103
  toJSON(): BodyObjectJSON;
100
104
  }
@@ -84,6 +84,25 @@ export class BodyObject {
84
84
  });
85
85
  }
86
86
 
87
+ /**
88
+ * An HTML body, with an optional plain-text part.
89
+ * @param {string} html
90
+ * @param {string} [plaintext]
91
+ * @returns {BodyObject}
92
+ */
93
+ static html(html, plaintext) {
94
+ return new BodyObject({ html: html, plaintext: plaintext });
95
+ }
96
+
97
+ /**
98
+ * A plain-text body.
99
+ * @param {string} plaintext
100
+ * @returns {BodyObject}
101
+ */
102
+ static text(plaintext) {
103
+ return new BodyObject({ plaintext: plaintext });
104
+ }
105
+
87
106
  /**
88
107
  * JSON-ready object in the API format, empty fields are omitted.
89
108
  * @returns {Record<string, any>}