unione 0.0.0-stage → 1.2.3
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 +96 -0
- package/LICENSE +21 -0
- package/README.md +427 -2
- package/docs/ConfirmedEmail.md +107 -0
- package/docs/Domain.md +257 -0
- package/docs/Email.md +124 -0
- package/docs/EmailValidation.md +53 -0
- package/docs/EventDump.md +154 -0
- package/docs/Obsolete.md +116 -0
- package/docs/Project.md +170 -0
- package/docs/Suppression.md +159 -0
- package/docs/System.md +73 -0
- package/docs/Tag.md +72 -0
- package/docs/Template.md +160 -0
- package/docs/Webhook.md +178 -0
- package/package.json +90 -4
- package/src/UniOneClient.d.ts +101 -0
- package/src/UniOneClient.js +103 -0
- package/src/api/confirmed-email/ConfirmedEmailApi.d.ts +36 -0
- package/src/api/confirmed-email/ConfirmedEmailApi.js +48 -0
- package/src/api/confirmed-email/index.d.ts +2 -0
- package/src/api/confirmed-email/index.js +2 -0
- package/src/api/confirmed-email/models.d.ts +142 -0
- package/src/api/confirmed-email/models.js +205 -0
- package/src/api/domain/DomainApi.d.ts +118 -0
- package/src/api/domain/DomainApi.js +142 -0
- package/src/api/domain/index.d.ts +2 -0
- package/src/api/domain/index.js +2 -0
- package/src/api/domain/models.d.ts +455 -0
- package/src/api/domain/models.js +643 -0
- package/src/api/email/EmailApi.d.ts +45 -0
- package/src/api/email/EmailApi.js +54 -0
- package/src/api/email/index.d.ts +2 -0
- package/src/api/email/index.js +2 -0
- package/src/api/email/models.d.ts +598 -0
- package/src/api/email/models.js +617 -0
- package/src/api/email-validation/EmailValidationApi.d.ts +26 -0
- package/src/api/email-validation/EmailValidationApi.js +31 -0
- package/src/api/email-validation/index.d.ts +2 -0
- package/src/api/email-validation/index.js +2 -0
- package/src/api/email-validation/models.d.ts +147 -0
- package/src/api/email-validation/models.js +172 -0
- package/src/api/event-dump/EventDumpApi.d.ts +55 -0
- package/src/api/event-dump/EventDumpApi.js +71 -0
- package/src/api/event-dump/index.d.ts +2 -0
- package/src/api/event-dump/index.js +2 -0
- package/src/api/event-dump/models.d.ts +540 -0
- package/src/api/event-dump/models.js +564 -0
- package/src/api/obsolete/ObsoleteApi.d.ts +45 -0
- package/src/api/obsolete/ObsoleteApi.js +58 -0
- package/src/api/obsolete/index.d.ts +2 -0
- package/src/api/obsolete/index.js +2 -0
- package/src/api/obsolete/models.d.ts +247 -0
- package/src/api/obsolete/models.js +326 -0
- package/src/api/project/ProjectApi.d.ts +58 -0
- package/src/api/project/ProjectApi.js +75 -0
- package/src/api/project/index.d.ts +2 -0
- package/src/api/project/index.js +2 -0
- package/src/api/project/models.d.ts +624 -0
- package/src/api/project/models.js +679 -0
- package/src/api/suppression/SuppressionApi.d.ts +50 -0
- package/src/api/suppression/SuppressionApi.js +67 -0
- package/src/api/suppression/index.d.ts +2 -0
- package/src/api/suppression/index.js +2 -0
- package/src/api/suppression/models.d.ts +466 -0
- package/src/api/suppression/models.js +513 -0
- package/src/api/system/SystemApi.d.ts +25 -0
- package/src/api/system/SystemApi.js +32 -0
- package/src/api/system/index.d.ts +2 -0
- package/src/api/system/index.js +2 -0
- package/src/api/system/models.d.ts +212 -0
- package/src/api/system/models.js +258 -0
- package/src/api/tag/TagApi.d.ts +32 -0
- package/src/api/tag/TagApi.js +40 -0
- package/src/api/tag/index.d.ts +2 -0
- package/src/api/tag/index.js +2 -0
- package/src/api/tag/models.d.ts +83 -0
- package/src/api/tag/models.js +127 -0
- package/src/api/template/TemplateApi.d.ts +53 -0
- package/src/api/template/TemplateApi.js +70 -0
- package/src/api/template/index.d.ts +2 -0
- package/src/api/template/index.js +2 -0
- package/src/api/template/models.d.ts +642 -0
- package/src/api/template/models.js +722 -0
- package/src/api/webhook/WebhookApi.d.ts +75 -0
- package/src/api/webhook/WebhookApi.js +95 -0
- package/src/api/webhook/index.d.ts +2 -0
- package/src/api/webhook/index.js +2 -0
- package/src/api/webhook/models.d.ts +1069 -0
- package/src/api/webhook/models.js +1094 -0
- package/src/client/ApiClient.d.ts +24 -0
- package/src/client/ApiClient.js +208 -0
- package/src/client/ApiError.d.ts +20 -0
- package/src/client/ApiError.js +21 -0
- package/src/client/Configuration.d.ts +66 -0
- package/src/client/Configuration.js +57 -0
- package/src/client/index.d.ts +5 -0
- package/src/client/index.js +3 -0
- package/src/common/index.d.ts +1 -0
- package/src/common/index.js +1 -0
- package/src/common/models.d.ts +292 -0
- package/src/common/models.js +330 -0
- package/src/index.d.ts +4 -0
- package/src/index.js +2 -0
package/AGENTS.md
ADDED
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
# AGENTS.md
|
|
2
|
+
|
|
3
|
+
UniOne Node.js SDK — client for the UniOne transactional email Web API (Web API 1.90).
|
|
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.2.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.2.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.2.3 in package.json) and the tag `v1.2.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
|
|
21
|
+
|
|
22
|
+
Full quickstart: [README.md](README.md). Install:
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
npm install unione
|
|
26
|
+
```
|
|
27
|
+
|
|
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 with the attachments in base64 (a third larger than the files); 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).
|
|
40
|
+
|
|
41
|
+
### Send an email
|
|
42
|
+
|
|
43
|
+
The client reads the API key from `UNIONE_API_KEY`:
|
|
44
|
+
|
|
45
|
+
```javascript
|
|
46
|
+
import { UniOneClient } from "unione";
|
|
47
|
+
import { EmailSendRequest, MessageObject, MessageObjectRecipientsItem } from "unione/api/email";
|
|
48
|
+
import { BodyObject } from "unione/common";
|
|
49
|
+
|
|
50
|
+
const client = new UniOneClient(process.env.UNIONE_API_KEY);
|
|
51
|
+
|
|
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);
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
### Errors
|
|
76
|
+
|
|
77
|
+
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.
|
|
78
|
+
|
|
79
|
+
```javascript
|
|
80
|
+
// client created as above
|
|
81
|
+
import { ApiError } from "unione";
|
|
82
|
+
|
|
83
|
+
try {
|
|
84
|
+
await client.system.ping();
|
|
85
|
+
} catch (error) {
|
|
86
|
+
if (!(error instanceof ApiError)) throw error;
|
|
87
|
+
// httpStatus is 0 for a network error or a timeout
|
|
88
|
+
console.error(error.httpStatus, error.errorCode, error.message);
|
|
89
|
+
}
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
### Reference
|
|
93
|
+
|
|
94
|
+
- 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
|
+
- [API reference](https://docs.unione.io/en/web-api-ref)
|
|
96
|
+
- [Full API reference for LLMs](https://docs.unione.io/llms-full.txt)
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2023 UniOne
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,428 @@
|
|
|
1
|
-
#
|
|
1
|
+
# UniOne Node.js SDK
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/unione) [](LICENSE)
|
|
4
|
+
|
|
5
|
+
Official Node.js library for the [UniOne](https://unione.io) transactional email API.
|
|
6
|
+
|
|
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.
|
|
10
|
+
|
|
11
|
+
## Install
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
npm install unione
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
Requirements: Node.js 14+. No third-party dependencies.
|
|
18
|
+
|
|
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.
|
|
20
|
+
|
|
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:
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
export UNIONE_API_KEY="your-api-key"
|
|
25
|
+
```
|
|
26
|
+
|
|
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.
|
|
48
|
+
|
|
49
|
+
## Contents
|
|
50
|
+
|
|
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)
|
|
56
|
+
|
|
57
|
+
## Recipes
|
|
58
|
+
|
|
59
|
+
Every recipe continues the example above: the client and its imports are there.
|
|
60
|
+
|
|
61
|
+
### Personalize for each recipient
|
|
62
|
+
|
|
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.
|
|
64
|
+
|
|
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
|
+
});
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
### Attach a file
|
|
82
|
+
|
|
83
|
+
```javascript
|
|
84
|
+
import { readFile } from "node:fs/promises";
|
|
85
|
+
|
|
86
|
+
const content = (await readFile("invoice.pdf")).toString("base64");
|
|
87
|
+
|
|
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
|
+
});
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
### CC and BCC
|
|
100
|
+
|
|
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).
|
|
102
|
+
|
|
103
|
+
```javascript
|
|
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
|
+
```
|
|
114
|
+
|
|
115
|
+
### Schedule
|
|
116
|
+
|
|
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
|
+
});
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
### Handle errors
|
|
151
|
+
|
|
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";
|
|
156
|
+
|
|
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);
|
|
163
|
+
}
|
|
164
|
+
```
|
|
165
|
+
|
|
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.
|
|
169
|
+
|
|
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;
|
|
187
|
+
}
|
|
188
|
+
```
|
|
189
|
+
|
|
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>
|
|
229
|
+
|
|
230
|
+
```bash
|
|
231
|
+
BASE=https://api.unione.io/en/transactional/api/v1
|
|
232
|
+
|
|
233
|
+
curl -s -X POST $BASE/domain/get-sandbox-domain.json \
|
|
234
|
+
-H "Content-Type: application/json" -H "X-API-KEY: $UNIONE_API_KEY" -d '{}'
|
|
235
|
+
|
|
236
|
+
curl -s -X POST $BASE/confirmed-email/create.json \
|
|
237
|
+
-H "Content-Type: application/json" -H "X-API-KEY: $UNIONE_API_KEY" \
|
|
238
|
+
-d '{"email": "you@example.com"}'
|
|
239
|
+
|
|
240
|
+
curl -s -X POST $BASE/email/send.json \
|
|
241
|
+
-H "Content-Type: application/json" -H "X-API-KEY: $UNIONE_API_KEY" \
|
|
242
|
+
-d '{
|
|
243
|
+
"message": {
|
|
244
|
+
"recipients": [
|
|
245
|
+
{
|
|
246
|
+
"email": "you@example.com"
|
|
247
|
+
}
|
|
248
|
+
],
|
|
249
|
+
"from_email": "noreply@<sandbox-domain>",
|
|
250
|
+
"subject": "Hello from UniOne",
|
|
251
|
+
"body": {
|
|
252
|
+
"html": "<p>It works!</p>"
|
|
253
|
+
}
|
|
254
|
+
}
|
|
255
|
+
}'
|
|
256
|
+
```
|
|
257
|
+
|
|
258
|
+
</details>
|
|
259
|
+
|
|
260
|
+
## Going to production
|
|
261
|
+
|
|
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`.
|
|
263
|
+
|
|
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 |
|
|
270
|
+
|
|
271
|
+
**2. Make sending reliable.**
|
|
272
|
+
|
|
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 |
|
|
282
|
+
|
|
283
|
+
## Reference
|
|
284
|
+
|
|
285
|
+
### Sections
|
|
286
|
+
|
|
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. |
|
|
301
|
+
|
|
302
|
+
### API host
|
|
303
|
+
|
|
304
|
+
The second argument selects the API host (datacenter) or a full base URL.
|
|
305
|
+
|
|
306
|
+
```javascript
|
|
307
|
+
import { UniOneClient, Host } from "unione";
|
|
308
|
+
|
|
309
|
+
const client = new UniOneClient("YOUR_API_KEY", "us1.unione.io");
|
|
310
|
+
const other = new UniOneClient("YOUR_API_KEY", Host.US1, { timeout: 10000 });
|
|
311
|
+
```
|
|
312
|
+
|
|
313
|
+
### Error handling
|
|
314
|
+
|
|
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.
|
|
316
|
+
|
|
317
|
+
### Custom HTTP client and headers
|
|
318
|
+
|
|
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`).
|
|
320
|
+
|
|
321
|
+
```javascript
|
|
322
|
+
import { UniOneClient, ApiError } from "unione";
|
|
323
|
+
|
|
324
|
+
// retries of network errors and HTTP 5xx, a log line per request
|
|
325
|
+
async function fetchWithRetries(url, init) {
|
|
326
|
+
for (let attempt = 1; ; attempt++) {
|
|
327
|
+
try {
|
|
328
|
+
const response = await fetch(url, init);
|
|
329
|
+
if (response.status < 500 || attempt === 3) {
|
|
330
|
+
console.log(`POST ${url} -> ${response.status}`);
|
|
331
|
+
return response;
|
|
332
|
+
}
|
|
333
|
+
} catch (error) {
|
|
334
|
+
if (attempt === 3) throw error;
|
|
335
|
+
}
|
|
336
|
+
}
|
|
337
|
+
}
|
|
338
|
+
|
|
339
|
+
const client = new UniOneClient("YOUR_API_KEY", {
|
|
340
|
+
headers: { "X-Request-Id": "42" },
|
|
341
|
+
fetch: fetchWithRetries,
|
|
342
|
+
});
|
|
343
|
+
try {
|
|
344
|
+
console.log(await client.confirmedEmail.list());
|
|
345
|
+
} catch (error) {
|
|
346
|
+
if (!(error instanceof ApiError)) throw error;
|
|
347
|
+
console.log(error.httpStatus, error.errorCode, error.message, error.cause);
|
|
348
|
+
}
|
|
349
|
+
```
|
|
350
|
+
|
|
351
|
+
### Models
|
|
352
|
+
|
|
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.
|
|
354
|
+
|
|
355
|
+
```javascript
|
|
356
|
+
import { EmailSendRequest } from "unione/api/email";
|
|
357
|
+
import { HeadersObject } from "unione/common";
|
|
358
|
+
|
|
359
|
+
const headers = new HeadersObject({
|
|
360
|
+
extra: {
|
|
361
|
+
"X-MyHeader": "some data",
|
|
362
|
+
"CC": "copy@example.com",
|
|
363
|
+
"List-Unsubscribe": "<mailto:unsubscribe@example.com?subject=unsubscribe>",
|
|
364
|
+
},
|
|
365
|
+
});
|
|
366
|
+
|
|
367
|
+
const request = new EmailSendRequest({
|
|
368
|
+
message: {
|
|
369
|
+
"body": { html: "<b>Hello, {{to_name}}</b>" },
|
|
370
|
+
"subject": "Hello",
|
|
371
|
+
"from_email": "user@example.com",
|
|
372
|
+
"recipients": [{ email: "recipient@example.com" }],
|
|
373
|
+
"headers": headers,
|
|
374
|
+
},
|
|
375
|
+
});
|
|
376
|
+
console.log(JSON.stringify(request));
|
|
377
|
+
```
|
|
378
|
+
|
|
379
|
+
### TypeScript
|
|
380
|
+
|
|
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).
|
|
382
|
+
|
|
383
|
+
```typescript
|
|
384
|
+
import { UniOneClient, type ConfigurationOptions } from "unione";
|
|
385
|
+
import { EmailSendRequest, MessageObject, MessageObjectRecipientsItem, type EmailSendResponse } from "unione/api/email";
|
|
386
|
+
import { TemplateEngine, BodyObject } from "unione/common";
|
|
387
|
+
|
|
388
|
+
const options: ConfigurationOptions = { timeout: 10000, headers: { "X-Request-Id": "42" } };
|
|
389
|
+
const client = new UniOneClient("YOUR_API_KEY", options);
|
|
390
|
+
const response: EmailSendResponse = await client.email.send(new EmailSendRequest({
|
|
391
|
+
message: new MessageObject({
|
|
392
|
+
recipients: [
|
|
393
|
+
new MessageObjectRecipientsItem({
|
|
394
|
+
email: "user@example.com",
|
|
395
|
+
substitutions: {
|
|
396
|
+
"CustomerId": "12452",
|
|
397
|
+
"to_name": "John Smith",
|
|
398
|
+
},
|
|
399
|
+
metadata: {
|
|
400
|
+
"campaign_id": "c77f4f4e-3561-49f7-9f07-c35be01b4f43",
|
|
401
|
+
"customer_hash": "b253ac7",
|
|
402
|
+
},
|
|
403
|
+
}),
|
|
404
|
+
],
|
|
405
|
+
templateId: "00000000-0000-0000-0000-000000000000",
|
|
406
|
+
globalLanguage: "en",
|
|
407
|
+
templateEngine: TemplateEngine.VELOCITY,
|
|
408
|
+
body: new BodyObject({
|
|
409
|
+
html: "<b>Hello, {{to_name}}</b>",
|
|
410
|
+
plaintext: "Hello, {{to_name}}",
|
|
411
|
+
amp: "<!doctype html><html amp4email><head> <meta charset=\"utf-8\"><script async src=\"https://cdn.ampproject.org/v0.js\"></script> <style amp4email-boilerplate>body{visibility:hidden}</style></head><body> Hello, AMP4EMAIL world.</body></html>",
|
|
412
|
+
}),
|
|
413
|
+
subject: "UniOne test email ",
|
|
414
|
+
fromEmail: "email@example.com",
|
|
415
|
+
fromName: "John Smith",
|
|
416
|
+
replyTo: "email@example.com",
|
|
417
|
+
replyToName: "John Smith",
|
|
418
|
+
idempotenceKey: "SG1VsbG68sIH2dvc5mx890kIQ",
|
|
419
|
+
}),
|
|
420
|
+
}));
|
|
421
|
+
```
|
|
422
|
+
|
|
423
|
+
## Help
|
|
424
|
+
|
|
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.
|
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
# ConfirmedEmail
|
|
2
|
+
|
|
3
|
+
[Back to the list of sections](../README.md)
|
|
4
|
+
|
|
5
|
+
Manage email addresses confirmed for sandbox-domain sending. These methods are available only with a main account API key.
|
|
6
|
+
|
|
7
|
+
`import { ConfirmedEmailApi } from "unione/api/confirmed-email"`, `client.confirmedEmail`
|
|
8
|
+
|
|
9
|
+
| Method | Endpoint | Description |
|
|
10
|
+
|---|---|---|
|
|
11
|
+
| [`create`](#create) | `POST /confirmed-email/create.json` | Adds an email address and sends a confirmation link. |
|
|
12
|
+
| [`list`](#list) | `POST /confirmed-email/list.json` | Lists confirmed and unconfirmed email addresses for the account. |
|
|
13
|
+
| [`delete`](#delete) | `POST /confirmed-email/delete.json` | Deletes an email address from the account's confirmed email list. |
|
|
14
|
+
|
|
15
|
+
## create
|
|
16
|
+
|
|
17
|
+
`POST /confirmed-email/create.json` · [Documentation](https://docs.unione.io/en/web-api-ref#confirmed-email-create)
|
|
18
|
+
|
|
19
|
+
Adds an email address and sends a confirmation link.
|
|
20
|
+
|
|
21
|
+
### Request: `ConfirmedEmailRequest`
|
|
22
|
+
|
|
23
|
+
| Field | Type | Required | Description |
|
|
24
|
+
|---|---|---|---|
|
|
25
|
+
| `email` | `string` | yes | Email address to add or delete. |
|
|
26
|
+
|
|
27
|
+
### Response: `ConfirmedEmailCreateResponse`
|
|
28
|
+
|
|
29
|
+
| Field | Type | Description |
|
|
30
|
+
|---|---|---|
|
|
31
|
+
| `status` | `string` | "success" string (`success`) |
|
|
32
|
+
| `confirmedEmail` | `ConfirmedEmail` | |
|
|
33
|
+
|
|
34
|
+
### Example
|
|
35
|
+
|
|
36
|
+
```javascript
|
|
37
|
+
import { UniOneClient } from "unione";
|
|
38
|
+
import { ConfirmedEmailRequest } from "unione/api/confirmed-email";
|
|
39
|
+
|
|
40
|
+
const client = new UniOneClient("YOUR_API_KEY");
|
|
41
|
+
|
|
42
|
+
const response = await client.confirmedEmail.create(new ConfirmedEmailRequest({
|
|
43
|
+
email: "dev@example.com",
|
|
44
|
+
}));
|
|
45
|
+
console.log(response.confirmedEmail);
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
## list
|
|
49
|
+
|
|
50
|
+
`POST /confirmed-email/list.json` · [Documentation](https://docs.unione.io/en/web-api-ref#confirmed-email-list)
|
|
51
|
+
|
|
52
|
+
Lists confirmed and unconfirmed email addresses for the account.
|
|
53
|
+
|
|
54
|
+
### Request
|
|
55
|
+
|
|
56
|
+
The method has no parameters.
|
|
57
|
+
|
|
58
|
+
### Response: `ConfirmedEmailListResponse`
|
|
59
|
+
|
|
60
|
+
| Field | Type | Description |
|
|
61
|
+
|---|---|---|
|
|
62
|
+
| `status` | `string` | "success" string (`success`) |
|
|
63
|
+
| `confirmedEmails` | `ConfirmedEmail[]` | |
|
|
64
|
+
|
|
65
|
+
### Example
|
|
66
|
+
|
|
67
|
+
```javascript
|
|
68
|
+
import { UniOneClient } from "unione";
|
|
69
|
+
|
|
70
|
+
const client = new UniOneClient("YOUR_API_KEY");
|
|
71
|
+
|
|
72
|
+
const response = await client.confirmedEmail.list();
|
|
73
|
+
console.log(response.confirmedEmails);
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
## delete
|
|
77
|
+
|
|
78
|
+
`POST /confirmed-email/delete.json` · [Documentation](https://docs.unione.io/en/web-api-ref#confirmed-email-delete)
|
|
79
|
+
|
|
80
|
+
Deletes an email address from the account's confirmed email list.
|
|
81
|
+
|
|
82
|
+
### Request: `ConfirmedEmailRequest`
|
|
83
|
+
|
|
84
|
+
| Field | Type | Required | Description |
|
|
85
|
+
|---|---|---|---|
|
|
86
|
+
| `email` | `string` | yes | Email address to add or delete. |
|
|
87
|
+
|
|
88
|
+
### Response: `ConfirmedEmailDeleteResponse`
|
|
89
|
+
|
|
90
|
+
| Field | Type | Description |
|
|
91
|
+
|---|---|---|
|
|
92
|
+
| `status` | `string` | "success" string (`success`) |
|
|
93
|
+
| `message` | `string` | |
|
|
94
|
+
|
|
95
|
+
### Example
|
|
96
|
+
|
|
97
|
+
```javascript
|
|
98
|
+
import { UniOneClient } from "unione";
|
|
99
|
+
import { ConfirmedEmailRequest } from "unione/api/confirmed-email";
|
|
100
|
+
|
|
101
|
+
const client = new UniOneClient("YOUR_API_KEY");
|
|
102
|
+
|
|
103
|
+
const response = await client.confirmedEmail.delete(new ConfirmedEmailRequest({
|
|
104
|
+
email: "dev@example.com",
|
|
105
|
+
}));
|
|
106
|
+
console.log(response.message);
|
|
107
|
+
```
|