unitpost 0.0.0 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +170 -7
- package/dist/index.cjs +680 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +2456 -0
- package/dist/index.d.ts +2456 -0
- package/dist/index.js +674 -0
- package/dist/index.js.map +1 -0
- package/package.json +37 -12
package/README.md
CHANGED
|
@@ -1,14 +1,177 @@
|
|
|
1
1
|
# unitpost
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Official [Unitpost](https://www.unitpost.com) SDK for Node.js. Send email and manage
|
|
4
|
+
contacts, segments, campaigns, templates, domains, suppressions, and webhooks.
|
|
4
5
|
|
|
5
|
-
|
|
6
|
+
## Install
|
|
6
7
|
|
|
7
|
-
|
|
8
|
+
```bash
|
|
9
|
+
npm install unitpost
|
|
10
|
+
```
|
|
8
11
|
|
|
9
|
-
|
|
10
|
-
nothing. Install the scoped package you need instead:
|
|
12
|
+
Requires Node.js 18+ (uses the built-in `fetch`).
|
|
11
13
|
|
|
12
|
-
|
|
13
|
-
|
|
14
|
+
## Quick start
|
|
15
|
+
|
|
16
|
+
```ts
|
|
17
|
+
import { Unitpost } from "unitpost";
|
|
18
|
+
|
|
19
|
+
const unitpost = new Unitpost(process.env.UNITPOST_API_KEY);
|
|
20
|
+
|
|
21
|
+
const { data, error } = await unitpost.email.send({
|
|
22
|
+
from: "Acme <you@yourdomain.com>", // bare address works too
|
|
23
|
+
to: "customer@example.com",
|
|
24
|
+
subject: "Hello",
|
|
25
|
+
html: "<p>It works!</p>",
|
|
26
|
+
});
|
|
27
|
+
|
|
28
|
+
if (error) {
|
|
29
|
+
console.error(error.code, error.message);
|
|
30
|
+
} else {
|
|
31
|
+
console.log("sent", data.id);
|
|
32
|
+
}
|
|
14
33
|
```
|
|
34
|
+
|
|
35
|
+
Every method returns `{ data, error }` — an API-level failure populates `error`
|
|
36
|
+
(a typed `UnitpostError`) instead of throwing, so you never need a `try/catch`
|
|
37
|
+
around a normal request.
|
|
38
|
+
|
|
39
|
+
## Authentication
|
|
40
|
+
|
|
41
|
+
Pass the key directly, or set `UNITPOST_API_KEY` and construct with no argument:
|
|
42
|
+
|
|
43
|
+
```ts
|
|
44
|
+
const unitpost = new Unitpost(); // reads process.env.UNITPOST_API_KEY
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
Create a key at [unitpost.com → Settings → API keys](https://www.unitpost.com).
|
|
48
|
+
Options: `new Unitpost({ apiKey, baseUrl, timeout, fetch, headers, maxRetries, retryBaseDelay, maxRetryDelay })`.
|
|
49
|
+
|
|
50
|
+
## Client surface
|
|
51
|
+
|
|
52
|
+
| Accessor | Covers |
|
|
53
|
+
| --- | --- |
|
|
54
|
+
| `emails` | Send, batch, list, get, update, stats, inbound (`received*`) |
|
|
55
|
+
| `contacts` | CRUD, import jobs |
|
|
56
|
+
| `contactFields` | Custom field definitions |
|
|
57
|
+
| `segments` | Segments + membership |
|
|
58
|
+
| `topics` | Topics + contact topic prefs |
|
|
59
|
+
| `campaigns` | Draft, schedule, send, pause/resume |
|
|
60
|
+
| `templates` | Template CRUD |
|
|
61
|
+
| `brandKits` | Brand kit |
|
|
62
|
+
| `domains` | Domains + verify |
|
|
63
|
+
| `webhooks` | Endpoints + `verify()` |
|
|
64
|
+
| `apiKeys` | API key management |
|
|
65
|
+
| `suppressions` | Suppression list |
|
|
66
|
+
| `usage` | Billing-period usage snapshot |
|
|
67
|
+
|
|
68
|
+
## Pagination
|
|
69
|
+
|
|
70
|
+
List endpoints are cursor-paginated. Use `list()` for one page or `listAll()`
|
|
71
|
+
to async-iterate every row:
|
|
72
|
+
|
|
73
|
+
```ts
|
|
74
|
+
for await (const contact of unitpost.contacts.listAll()) {
|
|
75
|
+
console.log(contact.email);
|
|
76
|
+
}
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
## Suppressions
|
|
80
|
+
|
|
81
|
+
The suppression list holds addresses that are excluded from every send — single,
|
|
82
|
+
batch, and campaign, including cc/bcc — case-insensitively. Hard bounces and spam
|
|
83
|
+
complaints are added automatically; you can also add your own:
|
|
84
|
+
|
|
85
|
+
```ts
|
|
86
|
+
// Suppress one address, or many in a single call (idempotent — re-adding is a no-op).
|
|
87
|
+
await unitpost.suppressions.create({ email: "bounced@example.com", reason: "manual" });
|
|
88
|
+
await unitpost.suppressions.create({ emails: ["a@example.com", "b@example.com"] });
|
|
89
|
+
|
|
90
|
+
// Look one up by id or email; list (optionally filter scope); un-suppress.
|
|
91
|
+
const { data } = await unitpost.suppressions.get("bounced@example.com");
|
|
92
|
+
for await (const s of unitpost.suppressions.listAll()) console.log(s.email, s.reason);
|
|
93
|
+
await unitpost.suppressions.delete("bounced@example.com");
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
`reason` accepts `manual`, `import`, or `api` — the engine-written `bounce` and
|
|
97
|
+
`complaint` reasons are read-only. Unitpost-wide (`platform`) entries are visible
|
|
98
|
+
but can't be removed via the API.
|
|
99
|
+
|
|
100
|
+
## Verifying webhooks
|
|
101
|
+
|
|
102
|
+
Deliveries are svix-compatible. Verify the raw request body against your
|
|
103
|
+
endpoint's signing secret:
|
|
104
|
+
|
|
105
|
+
```ts
|
|
106
|
+
import { verifyWebhook } from "unitpost";
|
|
107
|
+
|
|
108
|
+
const event = verifyWebhook({
|
|
109
|
+
payload: rawBody, // the raw request body string
|
|
110
|
+
secret: process.env.UNITPOST_WEBHOOK_SECRET,
|
|
111
|
+
headers: req.headers,
|
|
112
|
+
});
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
You can also call it from the client (Resend-style alias):
|
|
116
|
+
|
|
117
|
+
```ts
|
|
118
|
+
const event = unitpost.webhooks.verify({ payload: rawBody, secret, headers: req.headers });
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
## Idempotency
|
|
122
|
+
|
|
123
|
+
`emails.send` and `emails.batch` are safe to retry by default: if you don't pass
|
|
124
|
+
an idempotency key, the SDK generates one for you so an automatic retry can never
|
|
125
|
+
send twice. Pass your own to dedupe across separate calls (e.g. a user
|
|
126
|
+
double-clicks "send"):
|
|
127
|
+
|
|
128
|
+
```ts
|
|
129
|
+
await unitpost.email.send({ ... }, { idempotencyKey: crypto.randomUUID() });
|
|
130
|
+
await unitpost.email.batch([ ... ], { idempotencyKey: crypto.randomUUID() });
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
> The server dedupes on `(workspace, idempotency key)` for 24h and replays the
|
|
134
|
+
> original result instead of re-sending — for a single send that's the email id,
|
|
135
|
+
> for a batch the full list envelope.
|
|
136
|
+
|
|
137
|
+
## Retries
|
|
138
|
+
|
|
139
|
+
Transient failures are retried automatically: `429`, `5xx`, and transport errors
|
|
140
|
+
(timeouts / network) retry up to `maxRetries` times (default `2`). A `429`/`503`
|
|
141
|
+
`Retry-After` is honored; otherwise the client uses exponential backoff with full
|
|
142
|
+
jitter. Client errors (`401`/`403`/`404`/`409`/`422`) are never retried.
|
|
143
|
+
|
|
144
|
+
Only requests that are **safe to replay** are retried: `GET`s and writes that
|
|
145
|
+
carry an idempotency key (which `emails.send` and `emails.batch` always do — see
|
|
146
|
+
above). Any other keyless write is never auto-retried.
|
|
147
|
+
|
|
148
|
+
```ts
|
|
149
|
+
// Defaults shown; set maxRetries: 0 to disable.
|
|
150
|
+
const unitpost = new Unitpost({ maxRetries: 2, retryBaseDelay: 500, maxRetryDelay: 20_000 });
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
## Type-safety and the API contract
|
|
154
|
+
|
|
155
|
+
Request/response types are generated 1:1 from the public OpenAPI spec and
|
|
156
|
+
exported under `Models`. The SDK plumbing is regenerated from that spec and
|
|
157
|
+
CI-gated, so the SDK never silently drifts from the API.
|
|
158
|
+
|
|
159
|
+
## Resources
|
|
160
|
+
|
|
161
|
+
| | |
|
|
162
|
+
| --- | --- |
|
|
163
|
+
| Docs + API reference | https://www.unitpost.com/docs |
|
|
164
|
+
| Product / SMTP / MCP guides | https://www.unitpost.com/guides |
|
|
165
|
+
| OpenAPI JSON | https://www.unitpost.com/api/v1/openapi.json |
|
|
166
|
+
| LLM index | https://www.unitpost.com/llms.txt |
|
|
167
|
+
| Dashboard / API keys | https://www.unitpost.com |
|
|
168
|
+
| Email components (`@unitpost/email`) | https://www.unitpost.com/components |
|
|
169
|
+
| Template gallery | https://www.unitpost.com/templates/gallery |
|
|
170
|
+
| Playground | https://www.unitpost.com/playground |
|
|
171
|
+
| Migration Assistant | https://www.unitpost.com/migration |
|
|
172
|
+
| MCP + Agent Skills | https://www.unitpost.com/guides#ai-mcp · https://www.unitpost.com/guides#ai-skills |
|
|
173
|
+
| Support | support@unitpost.com |
|
|
174
|
+
|
|
175
|
+
## License
|
|
176
|
+
|
|
177
|
+
MIT
|