@visulima/email 1.0.0-alpha.9 → 1.0.0

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:
@@ -159,11 +199,7 @@ const smtpMail = createMail(smtp);
 const resendMail = createMail(resend);
 
 // Send via specific provider
-const message = new MailMessage()
-    .to("user@example.com")
-    .from("sender@example.com")
-    .subject("Hello")
-    .html("<h1>Hello World</h1>");
+const message = new MailMessage().to("user@example.com").from("sender@example.com").subject("Hello").html("<h1>Hello World</h1>");
 
 await resendMail.send(message);
 ```
@@ -876,6 +912,70 @@ const sendGridOptions: SendGridEmailOptions = {
 await mail.send(sendGridOptions);
 ```
 
+### SparkPost Provider
+
+SparkPost is a high-volume email delivery service. Universal runtime (Fetch API).
+
+```typescript
+import { createMail, sparkpostProvider } from "@visulima/email/providers/sparkpost";
+
+const mail = createMail(
+    sparkpostProvider({
+        apiKey: "your-sparkpost-api-key",
+        endpoint: "https://api.sparkpost.com/api/v1", // or https://api.eu.sparkpost.com/api/v1 (EU)
+    }),
+);
+
+await mail.send({
+    from: { email: "sender@example.com" },
+    to: { email: "user@example.com" },
+    subject: "Welcome",
+    html: "<h1>Welcome!</h1>",
+    // SparkPost-specific: campaignId, templateId, trackOpens, trackClicks
+});
+```
+
+### Netcore Provider
+
+Netcore (formerly Pepipost) transactional email via the Email API v5.1. Universal runtime (Fetch API).
+
+```typescript
+import { createMail, netcoreProvider } from "@visulima/email/providers/netcore";
+
+const mail = createMail(netcoreProvider({ apiKey: "your-netcore-api-key" }));
+
+await mail.send({
+    from: { email: "sender@example.com" },
+    to: { email: "user@example.com" },
+    subject: "Welcome",
+    html: "<h1>Welcome!</h1>",
+    // Netcore-specific: templateId, templateData
+});
+```
+
+### Outlook365 Provider
+
+Sends through Microsoft Graph `sendMail`. Universal runtime (Fetch API). Bring your own OAuth2 token (`Mail.Send` scope)
+via `accessToken` or `getAccessToken` — no auth SDK is bundled.
+
+```typescript
+import { createMail, outlook365Provider } from "@visulima/email/providers/outlook365";
+
+const mail = createMail(
+    outlook365Provider({
+        getAccessToken: async () => getGraphAccessToken(),
+        userId: "sender@contoso.com", // or "me" (default)
+    }),
+);
+
+await mail.send({
+    from: { email: "sender@contoso.com" },
+    to: { email: "user@example.com" },
+    subject: "Welcome",
+    html: "<h1>Welcome!</h1>",
+});
+```
+
 ### Plunk Provider
 
 Plunk is a modern email platform built on top of AWS SES, offering transactional emails, automations, and broadcasts.
@@ -1033,6 +1133,9 @@ const result = await mail.send(message);
 - **Round Robin** - Load balancing across multiple providers
 - **OpenTelemetry** - OpenTelemetry instrumentation wrapper for observability
 - **SendGrid** - Cloud-based email service for transactional and marketing emails
+- **SparkPost** - SparkPost Transmissions API
+- **Netcore** - Netcore (Pepipost) Email API
+- **Outlook365** - Microsoft Graph (Outlook365) `sendMail`
 - **SMTP** - Standard SMTP protocol
 - **Zeptomail** - Zeptomail email service
 
@@ -1063,6 +1166,9 @@ These providers work in **Node.js**, **Deno**, **Bun**, and **Cloudflare Workers
 - ✅ **Mailomat** - Uses Fetch API
 - ✅ **Sweego** - Uses Fetch API
 - ✅ **SendGrid** - Uses Fetch API
+- ✅ **SparkPost** - Uses Fetch API
+- ✅ **Netcore** - Uses Fetch API
+- ✅ **Outlook365** - Uses Fetch API (Microsoft Graph; bring your own OAuth2 token)
 - ✅ **Plunk** - Uses Fetch API
 - ✅ **Mock** - In-memory provider, works everywhere
 - ✅ **Failover** - Runtime depends on wrapped providers (works if all wrapped providers support the runtime)
@@ -1123,263 +1229,178 @@ Template engines are optional peer dependencies and work where their underlying
 
 \* Runtime support depends on the wrapped providers. Works if all wrapped providers support the runtime.
 
-## Disposable Email Detection
-
-The package includes support for detecting disposable email addresses using the `@visulima/disposable-email-domains` package, which is included as a dependency.
+## Email Verification & Enrichment
 
-### Usage
+Address verification and enrichment — MX/SMTP probing, disposable/free/role detection, catch-all & mailbox-full detection, SMTP-provider and secure-email-gateway classification, misspelled-domain suggestions, and a 0–100 quality score — now live in the standalone, mailer-free [`@visulima/email-verifier`](https://visulima.com/packages/email-verifier) package, so a validation-only consumer doesn't pull in the provider adapters.
 
 ```typescript
-import { isDisposableEmail } from "@visulima/email/validation/disposable-email-domains";
+import { verifyEmail } from "@visulima/email-verifier";
 
-// Check if an email is disposable
-if (isDisposableEmail("user@mailinator.com")) {
-    console.log("Disposable email detected!");
-}
-
-// With custom domains
-const customDomains = new Set(["my-disposable.com"]);
-if (isDisposableEmail("user@my-disposable.com", customDomains)) {
-    console.log("Custom disposable email detected!");
-}
+const report = await verifyEmail("user@example.com");
+// { state: "deliverable" | "risky" | "undeliverable" | "unknown", score, disposable, free, role, acceptAll, provider, ... }
 ```
 
-**Note:** The `@visulima/disposable-email-domains` package is included as a dependency, so no additional installation is required.
-
-## Email Verification
-
-The package provides comprehensive email verification utilities including MX record checking, SMTP verification, and role account detection.
+## Email Utilities
 
-### MX Record Checking
+The package also exports standalone utility functions that can be used independently:
 
-Check if a domain has valid MX (Mail Exchange) records:
+### Email Validation
 
 ```typescript
-import { checkMxRecords } from "@visulima/email/validation/check-mx-records";
-
-const result = await checkMxRecords("example.com");
+import { validateEmail } from "@visulima/email/validation/validate-email";
 
-if (result.valid) {
-    console.log("MX records:", result.records);
-    // Records are sorted by priority (lowest first)
-} else {
-    console.error("No MX records found:", result.error);
+if (validateEmail("user@example.com")) {
+    console.log("Valid email!");
 }
 ```
 
-#### Caching MX Records
-
-Use caching to improve performance and reduce DNS lookups:
+### Parse Email Address
 
 ```typescript
-import { checkMxRecords } from "@visulima/email/validation/check-mx-records";
-import { InMemoryCache } from "@visulima/email/utils/cache";
+import { parseAddress } from "@visulima/email/utils/parse-address";
+
+// Parse email with name
+const address = parseAddress("John Doe <john@example.com>");
+// { name: "John Doe", email: "john@example.com" }
+
+// Parse email without name
+const simple = parseAddress("jane@example.com");
+// { email: "jane@example.com" }
+```
 
-// Create a cache instance
-const cache = new InMemoryCache();
+### Format Email Address
 
-// Use cache with default TTL (1 hour)
-const result1 = await checkMxRecords("example.com", { cache });
+```typescript
+import { formatEmailAddress } from "@visulima/email/utils/format-email-address";
 
-// Use cache with custom TTL (5 minutes)
-const result2 = await checkMxRecords("example.com", {
-    cache,
-    ttl: 5 * 60 * 1000, // 5 minutes in milliseconds
+const formatted = formatEmailAddress({
+    email: "user@example.com",
+    name: "John Doe",
 });
+// "John Doe <user@example.com>"
 
-// Clear cache when needed
-await cache.clear();
+const simple = formatEmailAddress({ email: "user@example.com" });
+// "user@example.com"
 ```
 
-#### Custom Cache Implementation
+### Normalize Email Aliases
 
-You can implement your own cache using the `Cache` interface (e.g., for Redis, LRU cache, etc.):
+Normalize email aliases for supported providers (Gmail, Yahoo, Outlook, etc.):
 
 ```typescript
-import type { Cache, MxCheckResult } from "@visulima/email/utils/cache";
-import { checkMxRecords } from "@visulima/email/validation/check-mx-records";
-
-// Example: Custom Redis cache implementation
-const redisCache: Cache<MxCheckResult> = {
-    get: async (key: string) => {
-        const cached = await redis.get(`mx:${key}`);
-        return cached ? JSON.parse(cached) : undefined;
-    },
-    set: async (key: string, value: MxCheckResult, ttl: number) => {
-        await redis.setex(`mx:${key}`, Math.floor(ttl / 1000), JSON.stringify(value));
-    },
-    delete: async (key: string) => {
-        await redis.del(`mx:${key}`);
-    },
-    clear: async () => {
-        // Clear all MX cache keys
-        const keys = await redis.keys("mx:*");
-        if (keys.length > 0) {
-            await redis.del(...keys);
-        }
-    },
-};
+import { normalizeEmailAliases } from "@visulima/email/utils/normalize-email-aliases";
 
-// Use custom cache
-const result = await checkMxRecords("example.com", {
-    cache: redisCache,
-    ttl: 10 * 60 * 1000, // 10 minutes
-});
+// Gmail: removes dots and plus aliases
+normalizeEmailAliases("example+test@gmail.com"); // "example@gmail.com"
+normalizeEmailAliases("ex.ample@gmail.com"); // "example@gmail.com"
+
+// Yahoo, Outlook, FastMail, Mail.com, GMX, etc.: removes plus aliases only
+normalizeEmailAliases("user+tag@yahoo.com"); // "user@yahoo.com"
+normalizeEmailAliases("user.name@yahoo.com"); // "user.name@yahoo.com" (dots preserved)
+normalizeEmailAliases("user+tag@fastmail.com"); // "user@fastmail.com"
+normalizeEmailAliases("user+tag@mail.com"); // "user@mail.com"
+normalizeEmailAliases("user+tag@gmx.com"); // "user@gmx.com"
+
+// Unsupported domains return unchanged
+normalizeEmailAliases("user@example.com"); // "user@example.com"
 ```
 
-### Role Account Detection
+## Batch Sending & Result Helpers
 
-Detect if an email address is a role account (non-personal email like `noreply@`, `support@`, etc.):
+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 { isRoleAccount } from "@visulima/email/validation/role-accounts";
+import { createMail, isOk, unwrapOr } from "@visulima/email";
 
-if (isRoleAccount("noreply@example.com")) {
-    console.log("This is a role account");
-}
+const mail = createMail(provider);
 
-// With custom role prefixes
-const customPrefixes = new Set(["custom-role", "my-role"]);
-if (isRoleAccount("custom-role@example.com", customPrefixes)) {
-    console.log("Custom role account detected");
+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);
 }
 ```
 
-### SMTP Verification
+See [Sending Mail](https://visulima.com/docs/package/email/getting-started/sending-mail).
+
+## Middleware
 
-Verify if an email address exists by connecting to the mail server:
+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 { verifySmtp } from "@visulima/email/validation/verify-smtp";
-import { InMemoryCache } from "@visulima/email/utils/cache";
-import type { MxCheckResult, SmtpVerificationResult } from "@visulima/email/validation/check-mx-records";
-
-// Create separate caches for MX records and SMTP results
-const mxCache = new InMemoryCache<MxCheckResult>();
-const smtpCache = new InMemoryCache<SmtpVerificationResult>();
-
-const result = await verifySmtp("user@example.com", {
-    timeout: 5000,
-    fromEmail: "test@example.com",
-    port: 25,
-    cache: mxCache, // Optional: cache MX records
-    smtpCache, // Optional: cache SMTP verification results
-    ttl: 5 * 60 * 1000, // Cache for 5 minutes
-});
+import { createMail } from "@visulima/email";
+import { circuitBreakerMiddleware, RATE_LIMIT_PRESETS, rateLimitMiddleware, retryMiddleware } from "@visulima/email/middleware";
 
-if (result.valid) {
-    console.log("Email address exists");
-} else {
-    console.error("Verification failed:", result.error);
-}
+const mail = createMail(provider)
+    .use(rateLimitMiddleware({ rate: RATE_LIMIT_PRESETS.resend }))
+    .use(circuitBreakerMiddleware())
+    .use(retryMiddleware({ retries: 3 }));
 ```
 
-**Note:** Many mail servers block SMTP verification to prevent email harvesting. This method may not work for all domains.
+See [Middleware](https://visulima.com/docs/package/email/middleware/introduction).
 
-### Comprehensive Email Verification
+## Queue & Worker
 
-Combine all verification checks in a single function:
+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 { verifyEmail } from "@visulima/email/validation/verify-email";
-import { InMemoryCache } from "@visulima/email/utils/cache";
-import type { MxCheckResult, SmtpVerificationResult } from "@visulima/email/validation/check-mx-records";
-
-// Create separate caches for MX records and SMTP results
-const mxCache = new InMemoryCache<MxCheckResult>();
-const smtpCache = new InMemoryCache<SmtpVerificationResult>();
-
-const result = await verifyEmail("user@example.com", {
-    checkDisposable: true,
-    checkRoleAccount: true,
-    checkMx: true,
-    checkSmtp: false, // Optional, many servers block this
-    cache: mxCache, // Optional: cache MX records
-    smtpCache, // Optional: cache SMTP verification results
-    customDisposableDomains: new Set(["custom-disposable.com"]),
-    customRolePrefixes: new Set(["custom-role"]),
-});
+import { createMail } from "@visulima/email";
+import { createWorker, MemoryQueue } from "@visulima/email/queue";
 
-if (result.valid) {
-    console.log("Email is valid!");
-} else {
-    console.error("Errors:", result.errors);
-    console.warn("Warnings:", result.warnings);
-}
+const queue = new MemoryQueue();
+const mail = createMail(provider);
 
-// Access individual check results
-console.log("Format valid:", result.formatValid);
-console.log("Is disposable:", result.disposable);
-console.log("Is role account:", result.roleAccount);
-console.log("MX valid:", result.mxValid);
-console.log("SMTP valid:", result.smtpValid);
+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();
 ```
 
-### Email Utilities
+See [Queue](https://visulima.com/docs/package/email/queue/introduction).
 
-The package also exports standalone utility functions that can be used independently:
+## Webhook Verification
 
-#### Email Validation
+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.
 
-```typescript
-import { validateEmail } from "@visulima/email/validation/validate-email";
+See [Webhooks](https://visulima.com/docs/package/email/webhooks/introduction).
 
-if (validateEmail("user@example.com")) {
-    console.log("Valid email!");
-}
-```
+## Inbound Parsing
 
-#### Parse Email Address
+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()`.
 
-```typescript
-import { parseAddress } from "@visulima/email/utils/parse-address";
+See [Inbound](https://visulima.com/docs/package/email/inbound/introduction).
 
-// Parse email with name
-const address = parseAddress("John Doe <john@example.com>");
-// { name: "John Doe", email: "john@example.com" }
+## Deliverability
 
-// Parse email without name
-const simple = parseAddress("jane@example.com");
-// { email: "jane@example.com" }
-```
+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`.
 
-#### Format Email Address
+See [Deliverability](https://visulima.com/docs/package/email/deliverability/introduction).
 
-```typescript
-import { formatEmailAddress } from "@visulima/email/utils/format-email-address";
+## Events & Testing
 
-const formatted = formatEmailAddress({
-    email: "user@example.com",
-    name: "John Doe",
-});
-// "John Doe <user@example.com>"
+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`.
 
-const simple = formatEmailAddress({ email: "user@example.com" });
-// "user@example.com"
-```
+See [Events](https://visulima.com/docs/package/email/events/introduction) and [Testing](https://visulima.com/docs/package/email/testing/introduction).
 
-#### Normalize Email Aliases
+## Crypto (DKIM / S/MIME / ARC)
 
-Normalize email aliases for supported providers (Gmail, Yahoo, Outlook, etc.):
+Sign and encrypt messages with `@visulima/email/crypto`: `createDkimSigner` (DKIM-Signature header), `createSmimeSigner` / `createSmimeEncrypter` (S/MIME sign and encrypt, via the optional `pkijs` + `asn1js` peers), and `signArc` / `verifyArc` for ARC sealing on forwarded mail. Attach signers/encrypters to a `MailMessage` with `.sign(...)` / `.encrypt(...)`.
 
 ```typescript
-import { normalizeEmailAliases } from "@visulima/email/utils/normalize-email-aliases";
+import { MailMessage } from "@visulima/email";
+import { createDkimSigner } from "@visulima/email/crypto";
 
-// Gmail: removes dots and plus aliases
-normalizeEmailAliases("example+test@gmail.com"); // "example@gmail.com"
-normalizeEmailAliases("ex.ample@gmail.com"); // "example@gmail.com"
-
-// Yahoo, Outlook, FastMail, Mail.com, GMX, etc.: removes plus aliases only
-normalizeEmailAliases("user+tag@yahoo.com"); // "user@yahoo.com"
-normalizeEmailAliases("user.name@yahoo.com"); // "user.name@yahoo.com" (dots preserved)
-normalizeEmailAliases("user+tag@fastmail.com"); // "user@fastmail.com"
-normalizeEmailAliases("user+tag@mail.com"); // "user@mail.com"
-normalizeEmailAliases("user+tag@gmx.com"); // "user@gmx.com"
+const signer = createDkimSigner({
+    domainName: "example.com",
+    keySelector: "default",
+    privateKey: "file:///path/to/dkim.private.key", // or an inline PEM string
+});
 
-// Unsupported domains return unchanged
-normalizeEmailAliases("user@example.com"); // "user@example.com"
+const message = new MailMessage().from({ email: "a@example.com" }).to({ email: "b@example.com" }).subject("Signed").html("<p>Hello</p>").sign(signer); // DKIM-Signature is added during build()
 ```
 
+See [Crypto](https://visulima.com/docs/package/email/crypto/introduction).
+
 ## Related
 
 ## Supported Node.js Versions