@mailermine/node 1.0.0 → 1.1.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/CHANGELOG.md +31 -0
- package/README.md +27 -3
- package/dist/index.cjs +316 -91
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +156 -8
- package/dist/index.d.ts +156 -8
- package/dist/index.js +311 -92
- package/dist/index.js.map +1 -1
- package/package.json +3 -3
package/CHANGELOG.md
CHANGED
|
@@ -7,6 +7,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|
|
7
7
|
|
|
8
8
|
## [Unreleased]
|
|
9
9
|
|
|
10
|
+
## [1.1.0] - 2026-11-17
|
|
11
|
+
|
|
12
|
+
### Added
|
|
13
|
+
|
|
14
|
+
- Automatic retries with backoff for 429/502/503/504 and network errors,
|
|
15
|
+
honouring `Retry-After` (`maxRetries`, default 2; `maxRetryDelay`, default
|
|
16
|
+
30s). POSTs are only replayed when they carry an `Idempotency-Key`.
|
|
17
|
+
- `emails.send(input, { idempotencyKey })`; sends get a random key by default
|
|
18
|
+
so SDK retries never deliver twice.
|
|
19
|
+
- `client.rateLimit` and `error.rateLimit` (`RateLimitInfo`), `error.isRetryable`.
|
|
20
|
+
- `MissingScopeError` (subclass of `PlanError`) with `missingScopes` for 403
|
|
21
|
+
responses caused by a missing API key scope.
|
|
22
|
+
- `Scopes` / `ScopePresets`, including `webhooks.*`, `suppressions.*` and
|
|
23
|
+
`events.read`.
|
|
24
|
+
- `Webhooks.verifyHeaders()`.
|
|
25
|
+
- `held` message status: messages held for MailerMine trust & safety review
|
|
26
|
+
(the send call still succeeds). Blocked sends are `ValidationError`s with
|
|
27
|
+
an `errors.content`, `errors.sending_limit`, `errors.recipients` or
|
|
28
|
+
`errors.sending` entry.
|
|
29
|
+
|
|
30
|
+
### Fixed
|
|
31
|
+
|
|
32
|
+
- `Webhooks.verify()` could never validate a real MailerMine delivery: the
|
|
33
|
+
server signs `{timestamp}.{body}`. It now accepts the timestamp and rejects
|
|
34
|
+
stale deliveries (5 minute default); without a timestamp it keeps the old
|
|
35
|
+
body-only check.
|
|
36
|
+
|
|
37
|
+
### Changed
|
|
38
|
+
|
|
39
|
+
- Regenerated the OpenAPI client from the current API spec.
|
|
40
|
+
|
|
10
41
|
## [1.0.0] - 2026-07-18
|
|
11
42
|
|
|
12
43
|
First stable, production release. Full public-surface parity with the
|
package/README.md
CHANGED
|
@@ -52,7 +52,9 @@ const mm = new MailerMine({
|
|
|
52
52
|
apiKey: process.env.MAILERMINE_API_KEY!,
|
|
53
53
|
baseUrl: DEFAULT_BASE_URL, // https://mailermine.com/api/v1
|
|
54
54
|
timeout: 30_000,
|
|
55
|
-
userAgent: 'mailermine-node/1.
|
|
55
|
+
userAgent: 'mailermine-node/1.1.0',
|
|
56
|
+
maxRetries: 2,
|
|
57
|
+
maxRetryDelay: 30_000,
|
|
56
58
|
});
|
|
57
59
|
```
|
|
58
60
|
|
|
@@ -62,6 +64,21 @@ const mm = new MailerMine({
|
|
|
62
64
|
| `baseUrl` | `string` | `https://mailermine.com/api/v1` | API base URL |
|
|
63
65
|
| `timeout` | `number` | `30000` | Request timeout in milliseconds |
|
|
64
66
|
| `userAgent` | `string` | `mailermine-node/<version>` | User-Agent header value |
|
|
67
|
+
| `maxRetries` | `number` | `2` | Automatic retries for 429/502/503/504 and network errors (`0` disables) |
|
|
68
|
+
| `maxRetryDelay` | `number` | `30000` | Longest single wait between retries in ms; longer `Retry-After` throws `RateLimitError` |
|
|
69
|
+
|
|
70
|
+
### Retries, rate limits and idempotency
|
|
71
|
+
|
|
72
|
+
Rate-limited and temporarily unavailable requests are retried with backoff,
|
|
73
|
+
honouring `Retry-After`. Email sends always carry an `Idempotency-Key`, so a
|
|
74
|
+
retry is never delivered twice. Pass your own key to make retries from your
|
|
75
|
+
queue or another process safe too:
|
|
76
|
+
|
|
77
|
+
```ts
|
|
78
|
+
await mm.emails.send(message, { idempotencyKey: `order-${order.id}-receipt` });
|
|
79
|
+
|
|
80
|
+
mm.rateLimit?.remaining; // from the latest response's X-RateLimit-* headers
|
|
81
|
+
```
|
|
65
82
|
|
|
66
83
|
## Emails
|
|
67
84
|
|
|
@@ -304,9 +321,11 @@ const deliveries = await mm.webhooks.deliveries(webhook.data.id);
|
|
|
304
321
|
await mm.webhooks.disable(webhook.data.id);
|
|
305
322
|
await mm.webhooks.rotateSecret(webhook.data.id);
|
|
306
323
|
|
|
307
|
-
// Verify an incoming
|
|
324
|
+
// Verify an incoming delivery (HMAC-SHA256 over "{timestamp}.{rawBody}";
|
|
325
|
+
// deliveries older than 5 minutes are rejected). Use the raw, unparsed body.
|
|
308
326
|
import { Webhooks } from '@mailermine/node';
|
|
309
|
-
const valid = Webhooks.
|
|
327
|
+
const valid = Webhooks.verifyHeaders(rawBody, req.headers, signingSecret);
|
|
328
|
+
// or: Webhooks.verify(rawBody, signatureHeader, signingSecret, timestampHeader)
|
|
310
329
|
```
|
|
311
330
|
|
|
312
331
|
Also available: `get`, `list`, `update`, `delete`, `test`, `enable`, `delivery`, `logs`, `failures`, `replay`, and `retry`.
|
|
@@ -330,12 +349,17 @@ await mm.suppressions.remove(added.data.id);
|
|
|
330
349
|
| Status | Exception |
|
|
331
350
|
| --- | --- |
|
|
332
351
|
| 401 | `AuthenticationError` |
|
|
352
|
+
| 403 (missing API key scope) | `MissingScopeError` (subclass of `PlanError`, has `missingScopes`) |
|
|
333
353
|
| 403 | `PlanError` |
|
|
334
354
|
| 404 | `NotFoundError` |
|
|
335
355
|
| 422 | `ValidationError` |
|
|
336
356
|
| 429 | `RateLimitError` |
|
|
337
357
|
| 5xx / other | `ApiError` |
|
|
338
358
|
|
|
359
|
+
Every error has `status`, `body`, `rateLimit` and `isRetryable`. `Scopes` and
|
|
360
|
+
`ScopePresets` list the API key scopes, e.g.
|
|
361
|
+
`mm.apiKeys.create(projectId, { name: 'Mailer', scopes: ScopePresets.sendingOnly })`.
|
|
362
|
+
|
|
339
363
|
## Development
|
|
340
364
|
|
|
341
365
|
```bash
|