@visulima/email 1.0.0-alpha.33 → 1.0.0-alpha.35

package/CHANGELOG.md

@@ -1,3 +1,134 @@
+## @visulima/email [1.0.0-alpha.35](https://github.com/visulima/visulima/compare/@visulima/email@1.0.0-alpha.34...@visulima/email@1.0.0-alpha.35) (2026-06-04)
+
+### Features
+
+* **email:** inbound, webhooks, deliverability, middleware, queue, events, testing + ARC/i18n/batch ([#671](https://github.com/visulima/visulima/issues/671)) ([2ca23f2](https://github.com/visulima/visulima/commit/2ca23f27ecc5064d693c16bd3f44ccaeaf050888))
+
+### Bug Fixes
+
+* **email:** 5 bug fixes ([4e87c42](https://github.com/visulima/visulima/commit/4e87c429a56d68d7a0a09325484ed299ffe6493c))
+* **lint:** clear pre-existing eslint rot across packages ([#674](https://github.com/visulima/visulima/issues/674)) ([5354253](https://github.com/visulima/visulima/commit/5354253b163bd50bcefaf8a3fddf831bdb5df32b))
+
+
+### Dependencies
+
+* **@visulima/disposable-email-domains:** upgraded to 1.0.0-alpha.16
+* **@visulima/error:** upgraded to 6.0.0-alpha.32
+* **@visulima/fs:** upgraded to 5.0.0-alpha.30
+* **@visulima/path:** upgraded to 3.0.0-alpha.12
+
+## @visulima/email [1.0.0-alpha.34](https://github.com/visulima/visulima/compare/@visulima/email@1.0.0-alpha.33...@visulima/email@1.0.0-alpha.34) (2026-06-02)
+
+### Features
+
+* **email:** add fail-fast capability guard ([#657](https://github.com/visulima/visulima/issues/657)) ([81f24ab](https://github.com/visulima/visulima/commit/81f24abcde5cb8b6bbbd989a5ad397eefb3292ab))
+
+### Bug Fixes
+
+* **tests:** revert unsafe vitest autofixes from the lint sweep ([378f27c](https://github.com/visulima/visulima/commit/378f27caa370f1d3188aef2ed36d46839abc88c4))
+
+### Miscellaneous Chores
+
+* apply eslint + prettier autofixes across packages ([c1bb784](https://github.com/visulima/visulima/commit/c1bb7848a0d93d0dfe2960c77e3cda22239c79a0))
+
+### Tests
+
+* **email:** cover address normalization branches ([128f9d4](https://github.com/visulima/visulima/commit/128f9d485b0007636cf369f0c9a435c50d445794))
+* **email:** cover ahasend request, attachment and availability branches ([747ba3c](https://github.com/visulima/visulima/commit/747ba3cef6b84cd79d82b8441cb250032e9247eb))
+* **email:** cover ahasend send and messageId branches ([b9c5085](https://github.com/visulima/visulima/commit/b9c5085546f2abad3515d9d899a7f40f2b12cb58))
+* **email:** cover angle-bracket first-bracket fallback ([3f6f8b9](https://github.com/visulima/visulima/commit/3f6f8b9c6d44d370140d59146d8446be3a5b035a))
+* **email:** cover attach/embed empty basename fallback ([b5be774](https://github.com/visulima/visulima/commit/b5be7745cfeed21ec92911f1673c712744f2f311))
+* **email:** cover attachment content-type fallbacks ([94bf172](https://github.com/visulima/visulima/commit/94bf172278f65af5c3e4260ae2aeaf7ed35ca67a))
+* **email:** cover attachment default content type ([ac83c50](https://github.com/visulima/visulima/commit/ac83c501a40a874e721d9a58e5e5b0fd6125795e))
+* **email:** cover aws-ses branch paths ([c299c28](https://github.com/visulima/visulima/commit/c299c2873fcc309ce2c6695fb148dfab36bf795d))
+* **email:** cover aws-ses initialize, isAvailable, request errors and SES params ([b0c90c7](https://github.com/visulima/visulima/commit/b0c90c7245d3a68d891e1673e7acf8d6a9f129d7))
+* **email:** cover azure availability non-error branch ([1fea2cb](https://github.com/visulima/visulima/commit/1fea2cb1bd6908ef87b2de109b7e7159015f30ad))
+* **email:** cover azure connection-string auth and send/getEmail branches ([462d4f9](https://github.com/visulima/visulima/commit/462d4f95bb8d59fd459b1cd812640028abf60237))
+* **email:** cover azure getEmail auth, isAvailable status codes and send failure ([d03fe62](https://github.com/visulima/visulima/commit/d03fe62ceffce0598af844453e40daa64817bb0a))
+* **email:** cover brevo getEmail, replyTo array branches, batch and attachments ([e967213](https://github.com/visulima/visulima/commit/e967213b93e24075d62bd6e12e43015fed045dda))
+* **email:** cover brevo send and getEmail branches ([78389b9](https://github.com/visulima/visulima/commit/78389b90d0bf19e89e6e58ecdb07887a1e8618c4))
+* **email:** cover build-mime-message attachment headers and encodings ([1095d47](https://github.com/visulima/visulima/commit/1095d471f8ed38755b3a847f3b39fdb3e7621722))
+* **email:** cover dkim empty-body canonicalization ([b5a7f4c](https://github.com/visulima/visulima/commit/b5a7f4c24ca211d0ae76d8df9a9f667e890cfcc0))
+* **email:** cover dkim-signer canonicalization branches ([d6c0bec](https://github.com/visulima/visulima/commit/d6c0bece326173678650f5a4f30078e35e17cffb))
+* **email:** cover failover init failures and fallbacks ([2cbead7](https://github.com/visulima/visulima/commit/2cbead75a564c25d3f921e80f49b099595927628))
+* **email:** cover failover unnamed-provider init failure ([38e0060](https://github.com/visulima/visulima/commit/38e0060f3cdfc963b6a85d725b7519b0fa188fb6))
+* **email:** cover handlebars register error rethrow ([b740f8f](https://github.com/visulima/visulima/commit/b740f8f2ed121a953cb5e02f81eebef4f172b598))
+* **email:** cover http initialize, availability, and cc/bcc branches ([b2f6509](https://github.com/visulima/visulima/commit/b2f6509c67fd3ba5e4b4e20be8c48965fa0e1928))
+* **email:** cover http send, init, and message-id branches ([62719bd](https://github.com/visulima/visulima/commit/62719bd9e9e9dece8de1e26b44854c73923b4cf8))
+* **email:** cover in-memory cache delete, clear and eviction ([e4b0333](https://github.com/visulima/visulima/commit/e4b03330889d2f5e822fa61b201411991c19d498))
+* **email:** cover infobip request, attachment and availability branches ([2dac360](https://github.com/visulima/visulima/commit/2dac3608200f75f7f795accadf226f242937831b))
+* **email:** cover infobip send and getEmail branches ([4d8719d](https://github.com/visulima/visulima/commit/4d8719db845882f0c52d580b47f040e5533fbae8))
+* **email:** cover Mail logger, sendMany, and global-config merge paths ([bd5c50b](https://github.com/visulima/visulima/commit/bd5c50be8b6aa110086f0c9975440decf1189ab6))
+* **email:** cover mail message replyTo setter ([afe8dae](https://github.com/visulima/visulima/commit/afe8daed7363d7fdd7354b8e3190602fdc635347))
+* **email:** cover mail send and batch branch paths ([b45b1b0](https://github.com/visulima/visulima/commit/b45b1b0e0066a276bee5a6bfddde13a63f7f415b))
+* **email:** cover mail-message auto-text generation ([2c44d7f](https://github.com/visulima/visulima/commit/2c44d7fa6636ca4c88e38504aa988855f6387436))
+* **email:** cover mail-message logger branches ([23b4496](https://github.com/visulima/visulima/commit/23b44963ed8edf4e794544bdcde94f2d3798994a))
+* **email:** cover mailersend request, attachment and availability branches ([999e22c](https://github.com/visulima/visulima/commit/999e22c94828e382f962d3bb695f2a63bc3e985b))
+* **email:** cover mailersend send and getEmail branches ([e20e805](https://github.com/visulima/visulima/commit/e20e8055fc8058a471fd45fb1526a6e35504865e))
+* **email:** cover mailgun getEmail events, tracking flags, form encoding and attachments ([cf63a01](https://github.com/visulima/visulima/commit/cf63a013cdcfc546fb731ad7c9b381b637490bd5))
+* **email:** cover mailgun send and getEmail branches ([3f63011](https://github.com/visulima/visulima/commit/3f63011a43752e8ba4f19e11857843b1f4830557))
+* **email:** cover mailjet getEmail, send failure, campaign fields and attachments ([2f4147f](https://github.com/visulima/visulima/commit/2f4147ff105386ac13700154a2fb5e081fa6d70b))
+* **email:** cover mailjet send and getEmail branches ([d692d34](https://github.com/visulima/visulima/commit/d692d346dc179f9778857d502824b3f68cd0f769))
+* **email:** cover mailomat and mailpace getEmail and edge paths ([519d057](https://github.com/visulima/visulima/commit/519d057b19f23f2157c379595fa041fb17fff189))
+* **email:** cover mailomat getEmail and branch paths ([8b52328](https://github.com/visulima/visulima/commit/8b52328146ccb0f6f2a10ce4652679e13debdb1a))
+* **email:** cover mailomat send/getEmail branch paths ([df5b5a4](https://github.com/visulima/visulima/commit/df5b5a446c8f373d09f5cab3d98280b35d495657))
+* **email:** cover mailpace availability and send branches ([b89b4ad](https://github.com/visulima/visulima/commit/b89b4ad51cde34d58656944a171434d6b2d361d7))
+* **email:** cover mailpace logger branch ([8e4fe77](https://github.com/visulima/visulima/commit/8e4fe779599f5ad43a63c24f7e7e9fa4d5b631ce))
+* **email:** cover mailtrap request, attachment and availability branches ([ee23353](https://github.com/visulima/visulima/commit/ee2335365cf6aac08578e7010b20752768bc3c8d))
+* **email:** cover mailtrap send and getEmail branches ([be3e1a3](https://github.com/visulima/visulima/commit/be3e1a3b85fc49c7f9848d3d5f12b1aa2df18ab8))
+* **email:** cover make-request non-error rejection ([9626626](https://github.com/visulima/visulima/commit/9626626f57afca5b8dcbb1653d9796575a17d666))
+* **email:** cover make-request timeout cleanup, json fallback and body coercion ([3d76d4e](https://github.com/visulima/visulima/commit/3d76d4ee92da4159ea9a5c6d247ee22f680ed3a4))
+* **email:** cover mandrill request, analytics and availability branches ([1233ff3](https://github.com/visulima/visulima/commit/1233ff327f34246ea2363a0b914e88d7c8471d78))
+* **email:** cover mandrill send and template branches ([297754f](https://github.com/visulima/visulima/commit/297754f8aa984269da98a082e8252b4cca9f1fc2))
+* **email:** cover mock init, recipient, and response branches ([5b301f5](https://github.com/visulima/visulima/commit/5b301f5d8de4bc0778379d9b2da8024913f2bcc2))
+* **email:** cover mock provider send/retrieve catch paths ([bb47683](https://github.com/visulima/visulima/commit/bb47683295e249f37cea1ea6bfb6bdda9f29a8d5))
+* **email:** cover mx lookup non-error rejection ([e52a2b6](https://github.com/visulima/visulima/commit/e52a2b663fe795a1c6f8727dc6ea655425c140b0))
+* **email:** cover nodemailer branch paths and fix lint ([6b5b72b](https://github.com/visulima/visulima/commit/6b5b72b0d8404a25d386d9d6cd0b79199550a1ed))
+* **email:** cover opentelemetry branches and fix lint ([6ac926b](https://github.com/visulima/visulima/commit/6ac926b484a229a66ac38c98dbe8e0c47e431ee8))
+* **email:** cover parse-address domain-literal and quoted-local edge cases ([fa909c7](https://github.com/visulima/visulima/commit/fa909c735d849997f99254f5dcfd0a3bf62b4804))
+* **email:** cover parse-address quote after at-sign ([49143f6](https://github.com/visulima/visulima/commit/49143f65e65b317d1da6e42cab7d2c03f1e63fca))
+* **email:** cover payload builder recipient/template branches ([e629d81](https://github.com/visulima/visulima/commit/e629d814c02576c4b24035235b4fdadf4021a61e))
+* **email:** cover plunk getEmail throw and attachment branches ([c24c2bf](https://github.com/visulima/visulima/commit/c24c2bf0e14247a8bd8538b679ba0f869276107a))
+* **email:** cover plunk send/getEmail branch paths ([96c2097](https://github.com/visulima/visulima/commit/96c2097ae3cb3bec00a57a04d768c83cd816c1db))
+* **email:** cover postal request, attachment and availability branches ([8617ce2](https://github.com/visulima/visulima/commit/8617ce2e43a5244a94434a0995367f5bbb4669b3))
+* **email:** cover postal send and getEmail branches ([9e78f76](https://github.com/visulima/visulima/commit/9e78f769faf6dcb38311995d1f26dee11f2727c8))
+* **email:** cover postmark getEmail, template alias, metadata and attachments ([58236b4](https://github.com/visulima/visulima/commit/58236b47e751a893cca3762e11600fd29fecf4a8))
+* **email:** cover postmark send and template branches ([5c298da](https://github.com/visulima/visulima/commit/5c298da4a20d1125d82cb36cb3c324948ab7c228))
+* **email:** cover provider address formatters ([dd4da80](https://github.com/visulima/visulima/commit/dd4da80afd21074fb145b65d75ad44da5bfaac2f))
+* **email:** cover reply-to validation and mx cache-on-error ([16cc9c2](https://github.com/visulima/visulima/commit/16cc9c2f96368d364271a11a72ec679af5d3df0a))
+* **email:** cover resend getEmail, isAvailable, and full send payload ([e0c4981](https://github.com/visulima/visulima/commit/e0c4981ece5a148c941b3239d53e87dd1b38cb48))
+* **email:** cover resend send, getEmail, availability branches ([bfca30d](https://github.com/visulima/visulima/commit/bfca30d7387d9c351f4b201f21e287fc8a7b2eb6))
+* **email:** cover roundrobin init, wait and failover branches ([8b42738](https://github.com/visulima/visulima/commit/8b427389ff13d9b5cf7d79e318522d54be103ac7))
+* **email:** cover roundrobin name fallbacks and retry paths ([57d56c8](https://github.com/visulima/visulima/commit/57d56c8f8fca3ec17088b09000deac6d0c0707c2))
+* **email:** cover scaleway branch and init failure paths ([5ca4c8f](https://github.com/visulima/visulima/commit/5ca4c8fa479b94d675bc5b6982d6dbe8564a4f0c))
+* **email:** cover scaleway getEmail failure and attachment branches ([1fdbb2f](https://github.com/visulima/visulima/commit/1fdbb2f9404e988129ef485c3ec86a10f870b431))
+* **email:** cover sendgrid getEmail, settings, send failure and attachments ([db99fc8](https://github.com/visulima/visulima/commit/db99fc82e925c5c1187c00185d11872ffc5b5247))
+* **email:** cover sendgrid send and availability branches ([5bca44a](https://github.com/visulima/visulima/commit/5bca44a7fdde5cca30d4079b6ab222271eefb8ad))
+* **email:** cover smime aes128/aes192 algorithm aliases ([715482a](https://github.com/visulima/visulima/commit/715482aeabd6b90949e4a0f70cc9c6b11f0e9170))
+* **email:** cover smime build-message and algorithm paths ([49319c1](https://github.com/visulima/visulima/commit/49319c1c540dc5dd2a1b568791e40e246358c91b))
+* **email:** cover smime empty-body and empty recipient ([bc8ab8c](https://github.com/visulima/visulima/commit/bc8ab8cae1f15c466dfb08eef07312081e358484))
+* **email:** cover smtp 551/553 recipient rejections ([7c4630c](https://github.com/visulima/visulima/commit/7c4630c87496d62c371443412ecb22aabab44be7))
+* **email:** cover smtp branch paths ([d0c135e](https://github.com/visulima/visulima/commit/d0c135eaf7739d1f3025060eaf0bf953c7d41d13))
+* **email:** cover smtp provider via mock-socket harness ([08d98f9](https://github.com/visulima/visulima/commit/08d98f95bb677df4212928a9019cfd7cdf9de898))
+* **email:** cover smtp verify cache write error ([eceaf97](https://github.com/visulima/visulima/commit/eceaf9785081ec4418db0e279009a0c2238a87e8))
+* **email:** cover sweego branch and init failure paths ([99abf7a](https://github.com/visulima/visulima/commit/99abf7a3cd42fba2f4808539f4177368f7186de8))
+* **email:** cover sweego getEmail throw and attachment branches ([139d0ca](https://github.com/visulima/visulima/commit/139d0ca18be97d91a92dbbf9dd6da81693375e0c))
+* **email:** cover to-base64 buffer-less fallback and is-port-available ([c8c7454](https://github.com/visulima/visulima/commit/c8c7454bf0bcf9d734384bac21f24739eeb8de84))
+* **email:** cover validate-email hyphen domain rejection paths ([125eab0](https://github.com/visulima/visulima/commit/125eab0d9a543196496aea6de7d8adf3b3441aae))
+* **email:** cover verify-email mx and smtp branches ([70905d1](https://github.com/visulima/visulima/commit/70905d1430e00efea031116ac675ef30919cee51))
+* **email:** cover verify-smtp socket state machine and caching ([2b84cc1](https://github.com/visulima/visulima/commit/2b84cc1e36c01ef067ec571acdcfe614d9b2d1dc))
+* **email:** cover vue-email default data branch ([c51b812](https://github.com/visulima/visulima/commit/c51b812079f98eca77615c0c08fd206dfb67ad39))
+* **email:** cover zeptomail send error detail and exception branches ([ea74549](https://github.com/visulima/visulima/commit/ea745494f693360cc48d12bfb2bd8af66be0395e))
+* **email:** cover zeptomail send error/header/attachment branches ([5b78e15](https://github.com/visulima/visulima/commit/5b78e15a97a8f0070fe172e5dc92b0a3926bb01b))
+* **email:** fix lint in smtp harness test ([87811af](https://github.com/visulima/visulima/commit/87811af4dc6dea41a5a6ea2f96e3af19b168a0b3))
+* improve coverage across packages ([91bd6d3](https://github.com/visulima/visulima/commit/91bd6d3b61736e3c8bd1fc59b0b5955f76a5d323))
+
+
+### Dependencies
+
+* **@visulima/error:** upgraded to 6.0.0-alpha.31
+* **@visulima/fs:** upgraded to 5.0.0-alpha.29
+
 ## @visulima/email [1.0.0-alpha.33](https://github.com/visulima/visulima/compare/@visulima/email@1.0.0-alpha.32...@visulima/email@1.0.0-alpha.33) (2026-05-27)
 
 ### Bug Fixes

package/README.md

@@ -114,6 +114,46 @@ const message = new MailMessage().to("user@example.com").subject("Hello").html("
 await mail.send(message);
 ```
 
+### Capability Guard (fail-fast field support)
+
+Every provider declares which capabilities it supports through its `features` flags (attachments, tagging, scheduling, HTML, custom headers, reply-to, templates, ...). Before a message is handed to the provider, `Mail` runs a fail-fast check: if the message uses a capability the provider has **explicitly** declared unsupported (`features[x] === false`), the send is rejected locally — no wasted network round-trip and no silent data loss.
+
+```typescript
+import { createMail } from "@visulima/email";
+import { awsSesProvider } from "@visulima/email/providers/aws-ses";
+
+// AWS SES declares `tagging: false`
+const mail = createMail(awsSesProvider({ accessKeyId, secretAccessKey, region }));
+
+const result = await mail.send({
+    from: { email: "noreply@example.com" },
+    subject: "Hi",
+    tags: ["promo"], // not representable by AWS SES
+    text: "Body",
+    to: { email: "user@example.com" },
+});
+
+result.success; // false
+(result.error as { code?: string }).code; // "UNSUPPORTED_FEATURES"
+```
+
+Capabilities left `undefined` are treated as "unknown" and never rejected, so providers that publish a partial (or no) `features` map are never falsely blocked. The behaviour is configurable per `Mail` instance:
+
+```typescript
+createMail(provider, { featureCheck: "error" }); // default — reject unsupported fields
+createMail(provider, { featureCheck: "warn" }); // log a warning and send anyway
+createMail(provider, { featureCheck: "off" }); // skip the check entirely
+```
+
+You can also run the check standalone (e.g. inside a custom provider):
+
+```typescript
+import { checkFeatureSupport } from "@visulima/email";
+// or the focused entry point: "@visulima/email/validation/check-feature-support"
+
+const { supported, violations } = checkFeatureSupport(message, provider.features);
+```
+
 ### Creating Draft Emails
 
 You can create draft emails in EML (RFC 822) format without sending them. The `draft()` method returns the email as an EML string with an `X-Unsent: 1` header automatically added:
@@ -1376,6 +1416,83 @@ normalizeEmailAliases("user+tag@gmx.com"); // "user@gmx.com"
 normalizeEmailAliases("user@example.com"); // "user@example.com"
 ```
 
+## Batch Sending & Result Helpers
+
+Send one message per recipient from a shared base, with optional per-recipient template rendering, via `mail.sendBatch(base, personalizations, options?)`. Every `send` returns a `Result<EmailResult>`; the `isOk`/`isErr`/`unwrap`/`unwrapOr`/`mapOk`/`tryAsync` helpers (exported from the root and `@visulima/email/utils/result`) make handling it ergonomic.
+
+```typescript
+import { createMail, isOk, unwrapOr } from "@visulima/email";
+
+const mail = createMail(provider);
+
+for await (const receipt of mail.sendBatch(
+    { from: { email: "news@example.com" }, subject: "Hi {{name}}", html: "<p>Hello {{name}}</p>" },
+    [{ to: { email: "a@example.com" }, data: { name: "Ada" } }],
+    { render: (template, data) => renderHandlebars(template, data) },
+)) {
+    if (receipt.successful) console.log("sent", receipt.messageId);
+}
+```
+
+See [Sending Mail](https://visulima.com/docs/package/email/getting-started/sending-mail).
+
+## Middleware
+
+Attach resilience middleware with `mail.use(...)`: retry (full-jitter backoff + dead-letter), rate limiting (with per-provider presets), circuit breaker, deduplication, OAuth2 token refresh, and PII-redacting logging.
+
+```typescript
+import { createMail } from "@visulima/email";
+import { circuitBreakerMiddleware, RATE_LIMIT_PRESETS, rateLimitMiddleware, retryMiddleware } from "@visulima/email/middleware";
+
+const mail = createMail(provider)
+    .use(rateLimitMiddleware({ rate: RATE_LIMIT_PRESETS.resend }))
+    .use(circuitBreakerMiddleware())
+    .use(retryMiddleware({ retries: 3 }));
+```
+
+See [Middleware](https://visulima.com/docs/package/email/middleware/introduction).
+
+## Queue & Worker
+
+Durable background sending via the `EmailQueue` interface: an in-memory `MemoryQueue`, an `UnstorageQueue` (`@visulima/email/queue/unstorage`) backed by any [unstorage](https://unstorage.unjs.io/) store (Redis/FS/KV/Postgres), and a `createWorker(...)` with bounded concurrency, retry/backoff and dead-lettering.
+
+```typescript
+import { createMail } from "@visulima/email";
+import { createWorker, MemoryQueue } from "@visulima/email/queue";
+
+const queue = new MemoryQueue();
+const mail = createMail(provider);
+
+await queue.enqueue({ from: { email: "a@x.com" }, to: { email: "b@x.com" }, subject: "Hi", text: "yo" });
+createWorker({ queue, send: mail.send.bind(mail), concurrency: 5 }).start();
+```
+
+See [Queue](https://visulima.com/docs/package/email/queue/introduction).
+
+## Webhook Verification
+
+Verify provider webhook signatures with `@visulima/email/webhooks`: `verifyStandardWebhook`/`verifyResendWebhook` (Svix/Standard Webhooks), `verifyMailgunWebhook`, `verifySendGridWebhook` (ECDSA + replay window), `verifyPostmarkWebhook` (Basic Auth), and `verifySnsMessage` (AWS SES via SNS, with a tight `sns.<region>.amazonaws.com` cert allowlist). All return `{ valid, reason? }` — always pass the **raw** request body.
+
+See [Webhooks](https://visulima.com/docs/package/email/webhooks/introduction).
+
+## Inbound Parsing
+
+Normalize inbound webhooks from Postmark, SendGrid, Mailgun, Cloudflare Email and SES into one `InboundEmail` shape, then strip quoted history with `extractReply()` (EN/DE/FR/ES/TR) and group conversations with `stitchThreads()`.
+
+See [Inbound](https://visulima.com/docs/package/email/inbound/introduction).
+
+## Deliverability
+
+2024 bulk-sender tooling in `@visulima/email/deliverability`: RFC 8058 one-click `buildListUnsubscribe`, suppression stores (`MemorySuppressionStore` + `filterSuppressed`), and parsers for DMARC records, MTA-STS policies, TLS-RPT records/reports, and ARF feedback-loop complaints. ARC sealing (`signArc`) lives in `@visulima/email/crypto`.
+
+See [Deliverability](https://visulima.com/docs/package/email/deliverability/introduction).
+
+## Events & Testing
+
+A unified `EmailEvent` stream (`EventBus` + `MemoryEventStore` in `@visulima/email/events`), and a test harness (`@visulima/email/test`): `createTestEmail()` plus Vitest matchers `toHaveSentTo` / `toHaveSentWithSubject` / `toHaveSentWithAttachment` / `toHaveSentMatching`.
+
+See [Events](https://visulima.com/docs/package/email/events/introduction) and [Testing](https://visulima.com/docs/package/email/testing/introduction).
+
 ## Related
 
 ## Supported Node.js Versions

package/dist/crypto/index.d.ts

@@ -1,7 +1,164 @@
-import { E as EmailOptions } from "../packem_shared/types.d-wwpgA3to.js";
-import { D as DkimOptions, E as EmailSigner, S as SmimeEncryptOptions, a as EmailEncrypter, b as SmimeSignOptions } from "../packem_shared/types.d-CNnnk-Ya.js";
+import { KeyObject } from 'node:crypto';
+import { E as EmailOptions } from "../packem_shared/types.d-ejzh-xBP.js";
+import { D as DkimOptions, E as EmailSigner, S as SmimeEncryptOptions, a as EmailEncrypter, b as SmimeSignOptions } from "../packem_shared/types.d-BId55FW2.js";
 import 'node:buffer';
 /**
+* The signature algorithm for the ARC headers. RSA per RFC 8617, Ed25519 per RFC 8463.
+*/
+type ArcAlgorithm = "ed25519-sha256" | "rsa-sha256";
+/**
+* Options for {@link signArc}.
+*/
+interface ArcSealOptions {
+  /**
+  * Signature algorithm (`a=`). `rsa-sha256` (default) or `ed25519-sha256` (RFC 8463).
+  * @default "rsa-sha256"
+  */
+  algorithm?: ArcAlgorithm;
+  /**
+  * The `Authentication-Results` value to chain (authserv-id plus method results),
+  * e.g. `example.com; spf=pass smtp.mailfrom=...; dkim=pass header.d=...`.
+  */
+  authenticationResults: string;
+  /**
+  * Chain validation status for the seal (`cv`). For an originating sealer (instance 1) this is
+  * always `none`.
+  * @default "none"
+  */
+  cv?: "fail" | "none" | "pass";
+  /**
+  * The signing domain (`d`).
+  */
+  domainName: string;
+  /**
+  * Lower-cased header names covered by the ARC-Message-Signature (`h`).
+  * @default from, to, cc, subject, date, message-id, mime-version
+  */
+  headersToSign?: string[];
+  /**
+  * The ARC instance number (`i`). Only `1` (originating sealer) is supported.
+  * @default 1
+  */
+  instance?: number;
+  /**
+  * The DKIM/ARC key selector (`s`).
+  */
+  keySelector: string;
+  /**
+  * Passphrase for an encrypted private key.
+  */
+  passphrase?: string;
+  /**
+  * Private key (PEM string, or a `file://` path). RSA or Ed25519 to match `algorithm`.
+  */
+  privateKey: string;
+  /**
+  * Signature timestamp (`t`) in unix seconds. Defaults to now.
+  */
+  timestamp?: number;
+}
+/**
+* The three ARC header fields produced for one instance.
+*/
+interface ArcHeaderSet {
+  "ARC-Authentication-Results": string;
+  "ARC-Message-Signature": string;
+  "ARC-Seal": string;
+}
+/**
+* Options for {@link verifyArc}.
+*/
+interface ArcVerifyOptions {
+  /**
+  * The ARC/DKIM public key for the signing domain+selector — a PEM string or a `KeyObject`. Look it
+  * up at `<selector>._domainkey.<d>` (the `p=` tag), decoded to SPKI.
+  */
+  publicKey: KeyObject | string;
+}
+/**
+* The outcome of {@link verifyArc}.
+*/
+interface ArcVerifyResult {
+  /**
+  * Per-component verification: the ARC-Message-Signature, the ARC-Seal, and the body hash.
+  */
+  components: {
+    ams: boolean;
+    bodyHash: boolean;
+    seal: boolean;
+  };
+  /**
+  * The chain-validation status (`cv`) from the ARC-Seal.
+  */
+  cv?: string;
+  /**
+  * A machine-readable reason when `valid` is `false`.
+  */
+  reason?: string;
+  /**
+  * Whether the whole instance verified (signature + seal + body hash).
+  */
+  valid: boolean;
+}
+/**
+* Computes the exact byte string that the ARC-Message-Signature `b=` value signs.
+*
+* Exposed so ARC verifiers (and tests) can re-derive the signing input.
+* @param email The email being sealed.
+* @param options The seal options.
+* @returns The AMS header (without the `b=` value) and the data signed.
+*/
+declare const arcMessageSignatureBase: (email: EmailOptions, options: ArcSealOptions) => {
+  header: string;
+  signBase: string;
+};
+/**
+* Computes the exact byte string that the ARC-Seal `b=` value signs (for an originating, i=1 seal).
+*
+* Exposed so ARC verifiers (and tests) can re-derive the signing input.
+* @param aarValue The ARC-Authentication-Results value.
+* @param amsValue The full ARC-Message-Signature value (including its `b=` signature).
+* @param options The signing domain, selector, instance, timestamp and chain-validation status.
+* @returns The ARC-Seal header (without the `b=` value) and the data signed.
+*/
+declare const arcSealBase: (aarValue: string, amsValue: string, options: ArcSealOptions) => {
+  header: string;
+  signBase: string;
+};
+/**
+* Seals a message with an ARC (Authenticated Received Chain, RFC 8617) header set for an originating
+* sealer (instance `i=1`).
+*
+* Adds `ARC-Authentication-Results`, `ARC-Message-Signature`, and `ARC-Seal` headers. Use this when
+* your service forwards mail and wants downstream receivers to trust the authentication results you
+* observed. Supports RSA (default) and Ed25519 (`algorithm: "ed25519-sha256"`, RFC 8463) keys.
+*
+* IMPORTANT: the body hash (`bh=`) is computed over `text` + "\n\n" + `html` with relaxed
+* canonicalization — the same simplification as the DKIM signer. For a third-party ARC verifier to
+* accept the seal, the body actually transmitted on the wire must canonicalize to this same value, so
+* apply ARC at the point where the MIME body is finalized (or feed in the exact rendered body).
+* @param email The email to seal.
+* @param options The seal options. See {@link ArcSealOptions}.
+* @returns The email with the ARC header set added, and the raw {@link ArcHeaderSet}.
+* @throws {Error} When the private key cannot be loaded or signing fails.
+*/
+declare const signArc: (email: EmailOptions, options: ArcSealOptions) => Promise<{
+  email: EmailOptions;
+  headers: ArcHeaderSet;
+}>;
+/**
+* Verifies an originating (i=1) ARC header set against the signing domain's public key.
+*
+* Re-derives the AMS and ARC-Seal signing inputs from `email` + the supplied ARC headers, recomputes
+* the body hash, and checks all three. The public key must be the one published for the seal's
+* `s=`/`d=` (the DKIM-style `&lt;selector>._domainkey.&lt;domain>` TXT `p=` value).
+* @param email The message that was sealed (same fields used when signing).
+* @param headers The ARC header set (or any record containing the three `ARC-*` headers).
+* @param options Verification options. See {@link ArcVerifyOptions}.
+* @returns The verification result. See {@link ArcVerifyResult}.
+*/
+declare const verifyArc: (email: EmailOptions, headers: ArcHeaderSet | Record<string, string>, options: ArcVerifyOptions) => ArcVerifyResult;
+/**
 * DKIM signer implementation
 */
 declare class DkimSigner implements EmailSigner {
@@ -144,4 +301,4 @@ declare class SmimeSigner implements EmailSigner {
 * @returns A new SmimeSigner instance ready to sign emails.
 */
 declare const createSmimeSigner: (options: SmimeSignOptions) => SmimeSigner;
-export { type DkimOptions, DkimSigner, type EmailEncrypter, type EmailSigner, type SmimeEncryptOptions, SmimeEncrypter, type SmimeSignOptions, SmimeSigner, createDkimSigner, createSmimeEncrypter, createSmimeSigner };
+export { type ArcAlgorithm, type ArcHeaderSet, type ArcSealOptions, type ArcVerifyOptions, type ArcVerifyResult, type DkimOptions, DkimSigner, type EmailEncrypter, type EmailSigner, type SmimeEncryptOptions, SmimeEncrypter, type SmimeSignOptions, SmimeSigner, arcMessageSignatureBase, arcSealBase, createDkimSigner, createSmimeEncrypter, createSmimeSigner, signArc, verifyArc };

package/dist/crypto/index.js

@@ -1 +1 @@
-import{DkimSigner as m,createDkimSigner as i}from"../packem_shared/DkimSigner-CX2yGILn.js";import{SmimeEncrypter as S,createSmimeEncrypter as n}from"../packem_shared/SmimeEncrypter-DInfo-l0.js";import{SmimeSigner as c,createSmimeSigner as p}from"../packem_shared/SmimeSigner-CSWbZ41O.js";export{m as DkimSigner,S as SmimeEncrypter,c as SmimeSigner,i as createDkimSigner,n as createSmimeEncrypter,p as createSmimeSigner};
+import{arcMessageSignatureBase as m,arcSealBase as i,signArc as a,verifyArc as t}from"../packem_shared/arcMessageSignatureBase-Cpdnv-H8.js";import{DkimSigner as c,createDkimSigner as n}from"../packem_shared/DkimSigner-dKZ45Csc.js";import{SmimeEncrypter as g,createSmimeEncrypter as p}from"../packem_shared/SmimeEncrypter-BirIsrip.js";import{SmimeSigner as s,createSmimeSigner as x}from"../packem_shared/SmimeSigner-CkyaShTs.js";export{c as DkimSigner,g as SmimeEncrypter,s as SmimeSigner,m as arcMessageSignatureBase,i as arcSealBase,n as createDkimSigner,p as createSmimeEncrypter,x as createSmimeSigner,a as signArc,t as verifyArc};

package/dist/deliverability/dmarc-report.d.ts

@@ -0,0 +1,95 @@
+/**
+* A DKIM/SPF auth result inside a DMARC aggregate record.
+*/
+interface DmarcAuthResult {
+  domain?: string;
+  result?: string;
+}
+/**
+* One `<record>` row of a DMARC aggregate report.
+*/
+interface DmarcRecordRow {
+  /**
+  * The per-mechanism auth results.
+  */
+  authResults: {
+    dkim: DmarcAuthResult[];
+    spf: DmarcAuthResult[];
+  };
+  /**
+  * Number of messages this row represents.
+  */
+  count: number;
+  /**
+  * The policy disposition applied (`none` / `quarantine` / `reject`).
+  */
+  disposition?: string;
+  /**
+  * The DKIM alignment result (`pass` / `fail`).
+  */
+  dkim?: string;
+  /**
+  * The `From:` header domain.
+  */
+  headerFrom?: string;
+  /**
+  * The source IP that sent the messages.
+  */
+  sourceIp?: string;
+  /**
+  * The SPF alignment result (`pass` / `fail`).
+  */
+  spf?: string;
+}
+/**
+* A parsed DMARC aggregate (RUA) report.
+*/
+interface DmarcAggregateReport {
+  /**
+  * Report window start (`date_range.begin`, unix seconds as a string).
+  */
+  dateRangeBegin?: string;
+  /**
+  * Report window end (`date_range.end`, unix seconds as a string).
+  */
+  dateRangeEnd?: string;
+  /**
+  * The reporter's contact email.
+  */
+  email?: string;
+  /**
+  * The reporting organization.
+  */
+  organizationName?: string;
+  /**
+  * The published policy the report was evaluated against.
+  */
+  policyPublished?: {
+    adkim?: string;
+    aspf?: string;
+    domain?: string;
+    p?: string;
+    pct?: number;
+    sp?: string;
+  };
+  /**
+  * The per-source rows.
+  */
+  records: DmarcRecordRow[];
+  /**
+  * The unique report id.
+  */
+  reportId?: string;
+}
+/**
+* Parses a DMARC aggregate (RUA) report XML document into a structured object.
+*
+* Reports arrive gzipped/zipped — decompress to the XML string first. `fast-xml-parser` is an optional
+* peer dependency (`pnpm add fast-xml-parser`), loaded only via this `./deliverability/dmarc-report`
+* entry point so the rest of the deliverability tooling stays dependency-free.
+* @param xml The DMARC aggregate report XML.
+* @returns The parsed report. See {@link DmarcAggregateReport}.
+* @throws {EmailError} When `fast-xml-parser` is not installed or the XML cannot be parsed.
+*/
+declare const parseDmarcReport: (xml: string) => Promise<DmarcAggregateReport>;
+export { type DmarcAggregateReport, type DmarcAuthResult, type DmarcRecordRow, parseDmarcReport };

package/dist/deliverability/dmarc-report.js

@@ -0,0 +1 @@
+var R=Object.defineProperty;var f=(e,t)=>R(e,"name",{value:t,configurable:!0});import m from"../packem_shared/EmailError-zm2ffVav.js";var v=Object.defineProperty,o=f((e,t)=>v(e,"name",{value:t,configurable:!0}),"a");const b=o(e=>e==null?[]:Array.isArray(e)?e:[e],"toArray"),r=o(e=>{if(typeof e=="string")return e;if(typeof e=="number"||typeof e=="boolean")return String(e)},"asString"),g=o(e=>{const t=r(e);if(t===void 0)return;const i=Number(t);return Number.isNaN(i)?void 0:i},"asNumber"),y=o(e=>b(e).map(t=>({domain:r(t.domain),result:r(t.result)})),"toAuthResults"),k=o(async e=>{let t;try{({XMLParser:t}=await import("fast-xml-parser"))}catch(a){throw a instanceof Error&&(a.code==="ERR_MODULE_NOT_FOUND"||a.message.includes("Cannot find module")||a.message.includes("Cannot find package"))?new m("deliverability","fast-xml-parser is not installed. Please install it: pnpm add fast-xml-parser",{cause:a}):new m("deliverability",`Failed to load fast-xml-parser: ${a.message}`,{cause:a})}let i;try{i=new t({ignoreAttributes:!0,parseTagValue:!1}).parse(e)}catch(a){throw new m("deliverability",`Failed to parse DMARC report: ${a.message}`,{cause:a})}const d=i.feedback??{},n=d.report_metadata??{},u=n.date_range??{},s=d.policy_published??{},h=b(d.record).map(a=>{const p=a.row??{},l=p.policy_evaluated??{},_=a.identifiers??{},c=a.auth_results??{};return{authResults:{dkim:y(c.dkim),spf:y(c.spf)},count:g(p.count)??0,disposition:r(l.disposition),dkim:r(l.dkim),headerFrom:r(_.header_from),sourceIp:r(p.source_ip),spf:r(l.spf)}});return{dateRangeBegin:r(u.begin),dateRangeEnd:r(u.end),email:r(n.email),organizationName:r(n.org_name),policyPublished:{adkim:r(s.adkim),aspf:r(s.aspf),domain:r(s.domain),p:r(s.p),pct:g(s.pct),sp:r(s.sp)},records:h,reportId:r(n.report_id)}},"parseDmarcReport");export{k as parseDmarcReport};