@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 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.0.0',
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 signature locally (HMAC-SHA256).
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.verify(rawBody, signatureHeader, signingSecret);
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