@xenterprises/fastify-xemail 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -4,6 +4,32 @@ All notable changes to `@xenterprises/fastify-xemail` are documented here.
 
 ## Unreleased
 
+## [1.3.0] - 2026-09-07
+
+### Added
+
+- **Postmark provider** (`provider: 'postmark'`): `send`, `sendTemplate`,
+  `sendWithAttachments`, `sendBulk`, and `sendPersonalizedBulk` are backed by the
+  Postmark API (via the `postmark` package). Postmark is the migration target;
+  SendGrid is now legacy. The default remains `'sendgrid'`, so existing
+  registrations are unchanged.
+- New `provider` registration option (`'sendgrid' | 'postmark'`), validated
+  fail-fast at registration.
+- `messageStream` extra option for Postmark message streams.
+- `test/xEmail.postmark.test.js` — Postmark tests mocking
+  `postmark.ServerClient.prototype` with `mock.method()`, fully offline.
+
+### Changed
+
+- The plugin internals are split into provider modules:
+  `src/providers/sendgrid.js` (existing implementation, unchanged behavior) and
+  `src/providers/postmark.js` (new). `src/xEmail.js` now only validates options
+  and selects the provider.
+- Under `provider: 'postmark'`, the SendGrid-only methods (`validate`,
+  `addContact`, `searchContact`, `deleteContact`, `createList`, `getLists`,
+  `deleteList`) are still present on the decorator but throw
+  `[xEmail] '<method>()' is not supported by provider 'postmark'.`
+
 ## [1.2.0] - 2026-07-27
 
 ### Breaking changes

package/README.md

@@ -1,6 +1,9 @@
 # @xenterprises/fastify-xemail
 
-Fastify 5 plugin for SendGrid — send transactional, template, attachment, and bulk emails, validate addresses, and manage SendGrid Marketing contacts and lists, all through one `fastify.xEmail` decorator. For Fastify apps that need email with the least possible wiring.
+Fastify 5 plugin for email via **Postmark** or **SendGrid** (legacy) — send transactional, template, attachment, and bulk emails through one `fastify.xEmail` decorator. SendGrid additionally supports address validation and Marketing contacts/lists. For Fastify apps that need email with the least possible wiring.
+
+> **Migration note:** SendGrid support is legacy. New integrations should use
+> `provider: 'postmark'`; existing SendGrid registrations keep working unchanged.
 
 ## Install
 
@@ -22,7 +25,8 @@ import xEmail from '@xenterprises/fastify-xemail';
 const fastify = Fastify();
 
 await fastify.register(xEmail, {
-  apiKey: 'SG.your-api-key',
+  provider: 'postmark', // or 'sendgrid' (legacy default)
+  apiKey: 'your-postmark-server-token',
   fromEmail: 'noreply@example.com',
 });
 
@@ -34,16 +38,28 @@ await fastify.xEmail.send(
 ```
 
 The plugin reads **no environment variables**. All configuration arrives via the
-register options object; reading `process.env.SENDGRID_API_KEY` and passing it in
-is the consumer's job.
+register options object; reading `process.env.POSTMARK_SERVER_TOKEN` and passing
+it in is the consumer's job.
+
+## Providers
+
+| Provider | Status | Sending methods | `validate`, contacts, lists |
+|----------|--------|-----------------|------------------------------|
+| `postmark` | Migration target | `send`, `sendTemplate`, `sendWithAttachments`, `sendBulk`, `sendPersonalizedBulk` | Throw "not supported by provider 'postmark'" |
+| `sendgrid` | Legacy (default) | All sending methods | Fully supported |
+
+Postmark's API has no equivalents for email validation or contact/list
+management, so those methods exist in the decorator under Postmark but throw
+`[xEmail] '<method>()' is not supported by provider 'postmark'.`
 
 ## Options
 
 | Name | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
-| `apiKey` | `string` | — | Yes | SendGrid API key (needs Mail Send; Marketing APIs for contact/list methods) |
+| `provider` | `'sendgrid' \| 'postmark'` | `'sendgrid'` | No | Email provider. `sendgrid` is legacy; `postmark` is the migration target |
+| `apiKey` | `string` | — | Yes | SendGrid API key (needs Mail Send; Marketing APIs for contact/list methods) or Postmark server API token |
 | `fromEmail` | `string` | — | Yes | Verified sender email address |
-| `fromName` | `string` | — | No | Sender display name; when set, `from` becomes `{ email, name }` |
+| `fromName` | `string` | — | No | Sender display name |
 | `active` | `boolean` | `true` | No | Set `false` to disable the plugin entirely (no decorator is added) |
 
 Invalid options fail fast at registration with errors like:
@@ -59,14 +75,19 @@ The plugin adds one decorator: `fastify.xEmail`. No request decorators.
 ### `send(to, subject, html, text?, extraOptions?)`
 
 Send an email. Plain text is auto-generated from the HTML if `text` is omitted.
-`extraOptions` is merged into the SendGrid message (e.g. `replyTo`, `cc`, `categories`).
-Returns `{ success, statusCode, messageId }`.
+Under SendGrid, `extraOptions` is merged into the message (e.g. `replyTo`, `cc`,
+`categories`). Under Postmark, `extraOptions` accepts `replyTo`, `cc`, `bcc`,
+`headers`, and `messageStream` (mapped to Postmark's PascalCase fields).
+Returns `{ success, statusCode, messageId }` (Postmark reports a fixed
+`statusCode: 200` on success and throws on failure).
 
 ### `sendTemplate(to, subject, templateId, dynamicData?, extraOptions?)`
 
-Send using a SendGrid dynamic template (`templateId` is the `d-xxx` ID). `dynamicData`
-is sent as `dynamicTemplateData` (the subject is always included). Returns
-`{ success, statusCode, messageId }`.
+Send using a provider template. SendGrid: `templateId` is the dynamic template
+ID (`d-xxx`) and `dynamicData` is sent as `dynamicTemplateData`. Postmark:
+`templateId` is a template alias (string) or numeric template ID and
+`dynamicData` becomes the `TemplateModel`. The subject is always included in the
+template data. Returns `{ success, statusCode, messageId }`.
 
 ### `sendWithAttachments(to, subject, html, attachments)`
 
@@ -76,45 +97,49 @@ and `type` (MIME type); `disposition` defaults to `'attachment'`. Returns
 
 ### `sendBulk(to, subject, html)`
 
-Send the same email to an array of recipients in one call (`sgMail.sendMultiple`).
-Returns `{ success, count, statusCode }`.
+Send the same email to an array of recipients. SendGrid uses one
+`sgMail.sendMultiple` call; Postmark sends one email per recipient in chunks of
+500 concurrent requests. Returns `{ success, count, statusCode }`.
 
 ### `sendPersonalizedBulk(messages)`
 
 Send different content per recipient. `messages` is an array of
-`{ to, subject, html, text? }`. Uses `Promise.allSettled`, so it never throws on
-individual failures — returns one result per recipient:
-`{ success: true, to, statusCode }` or `{ success: false, to, error }`.
+`{ to, subject, html, text? }`. Never throws on individual failures — returns
+one result per recipient: `{ success: true, to, statusCode }` or
+`{ success: false, to, error }`. Postmark uses the batch endpoint (chunked at
+500 messages); a failure of the whole batch call marks that chunk's recipients
+as failed instead of throwing.
 
-### `validate(email)`
+### `validate(email)` — SendGrid only
 
 Validate an address via the SendGrid Email Validation API. Returns
 `{ email, valid, verdict, score, result }`. On API failure it returns a soft result
 `{ email, valid: false, verdict: 'Unknown', error }` instead of throwing.
+Throws under `provider: 'postmark'`.
 
-### `addContact(email, data?, listIds?)`
+### `addContact(email, data?, listIds?)` — SendGrid only
 
 Add or update a SendGrid Marketing contact. `data` accepts `firstName`/`lastName`
 (or `first_name`/`last_name`) and `customFields` (spread into the contact);
 `listIds` is an array of list IDs. Returns `{ success, jobId, email }`.
 
-### `searchContact(email)`
+### `searchContact(email)` — SendGrid only
 
 Search for a contact by email. Returns `{ found: true, contact }` or `{ found: false }`.
 
-### `deleteContact(contactId)`
+### `deleteContact(contactId)` — SendGrid only
 
 Delete a contact by ID. Returns `true` on success (HTTP 200/202), `false` otherwise.
 
-### `createList(name)`
+### `createList(name)` — SendGrid only
 
 Create a marketing contact list. Returns `{ success, list }`.
 
-### `getLists()`
+### `getLists()` — SendGrid only
 
 Get all contact lists. Returns an array (empty when none exist).
 
-### `deleteList(listId)`
+### `deleteList(listId)` — SendGrid only
 
 Delete a list by ID. Returns `true` on success (HTTP 200/202/204), `false` otherwise.
 
@@ -131,7 +156,10 @@ None. This plugin adds no routes.
 - **SendGrid API failures** are logged via `fastify.log.error` (structured error, never
   the API key) and re-thrown wrapped: `[xEmail] Failed to send email: <reason>`.
   `validate()` is the exception — it returns a soft result instead of throwing, since
-  validation failures are expected in normal operation.
+  validation failures are expected in normal operation. Postmark failures are wrapped
+  the same way.
+- **SendGrid-only methods under Postmark** throw
+  `[xEmail] '<method>()' is not supported by provider 'postmark'.`
 - With `active: false` the plugin returns before registering anything, so
   `fastify.xEmail` is `undefined`.
 

package/index.d.ts

@@ -1,17 +1,19 @@
 /**
- * xEmail - Fastify Plugin for SendGrid Email
+ * xEmail - Fastify Plugin for Email (Postmark + SendGrid legacy)
  * @module @xenterprises/fastify-xemail
  */
 
 import { FastifyPluginAsync } from 'fastify';
 
-/** Additional SendGrid mail options passed through to the API. */
+/** Additional mail options passed through to the provider API. */
 export interface EmailExtraOptions {
   replyTo?: string;
   bcc?: string | string[];
   cc?: string | string[];
   categories?: string[];
   headers?: Record<string, string>;
+  /** Postmark message stream (e.g. 'outbound'); Postmark provider only */
+  messageStream?: string;
   [key: string]: unknown;
 }
 
@@ -98,22 +100,34 @@ export interface PersonalizedMessage {
 /** All methods decorated onto fastify.xEmail. */
 export interface XEmailService {
   send(to: string | string[], subject: string, html: string, text?: string | null, extraOptions?: EmailExtraOptions): Promise<EmailSendResult>;
-  sendTemplate(to: string | string[], subject: string, templateId: string, dynamicData?: Record<string, unknown>, extraOptions?: EmailExtraOptions): Promise<EmailSendResult>;
+  sendTemplate(to: string | string[], subject: string, templateId: string | number, dynamicData?: Record<string, unknown>, extraOptions?: EmailExtraOptions): Promise<EmailSendResult>;
   sendWithAttachments(to: string | string[], subject: string, html: string, attachments: EmailAttachment[]): Promise<EmailSendResult>;
   sendBulk(to: string[], subject: string, html: string): Promise<EmailBulkResult>;
   sendPersonalizedBulk(messages: PersonalizedMessage[]): Promise<EmailPersonalizedResult[]>;
+  /** SendGrid only — throws under provider 'postmark'. */
   validate(email: string): Promise<EmailValidationResult>;
+  /** SendGrid only — throws under provider 'postmark'. */
   addContact(email: string, data?: ContactData, listIds?: string[]): Promise<EmailAddContactResult>;
+  /** SendGrid only — throws under provider 'postmark'. */
   searchContact(email: string): Promise<EmailSearchContactResult>;
+  /** SendGrid only — throws under provider 'postmark'. */
   deleteContact(contactId: string): Promise<boolean>;
+  /** SendGrid only — throws under provider 'postmark'. */
   createList(name: string): Promise<EmailCreateListResult>;
+  /** SendGrid only — throws under provider 'postmark'. */
   getLists(): Promise<Record<string, unknown>[]>;
+  /** SendGrid only — throws under provider 'postmark'. */
   deleteList(listId: string): Promise<boolean>;
 }
 
 /** Plugin configuration options. */
 export interface XEmailPluginOptions {
-  /** SendGrid API key (required) */
+  /**
+   * Email provider: 'sendgrid' (legacy, default) or 'postmark' (migration target).
+   * @default 'sendgrid'
+   */
+  provider?: 'sendgrid' | 'postmark';
+  /** Provider API key: SendGrid API key or Postmark server token (required) */
   apiKey: string;
   /** Verified sender email address (required) */
   fromEmail: string;

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@xenterprises/fastify-xemail",
   "type": "module",
-  "version": "1.2.0",
-  "description": "Fastify plugin for SendGrid email integration — transactional emails, templates, bulk sending, validation, and contact management.",
+  "version": "1.3.0",
+  "description": "Fastify plugin for email via Postmark or SendGrid (legacy) — transactional emails, templates, bulk sending, validation, and contact management.",
   "main": "src/xEmail.js",
   "types": "./index.d.ts",
   "exports": {
@@ -22,6 +22,7 @@
   },
   "keywords": [
     "fastify",
+    "postmark",
     "sendgrid",
     "email",
     "plugin"
@@ -36,7 +37,8 @@
   "dependencies": {
     "@sendgrid/client": "^8.1.3",
     "@sendgrid/mail": "^8.1.3",
-    "fastify-plugin": "^5.0.0"
+    "fastify-plugin": "^5.0.0",
+    "postmark": "^4.0.7"
   },
   "peerDependencies": {
     "fastify": "^5.0.0"

package/src/providers/postmark.js

@@ -0,0 +1,223 @@
+import postmark from "postmark";
+
+const BATCH_LIMIT = 500;
+
+function mapExtraOptions(extraOptions) {
+  const { replyTo, cc, bcc, headers, messageStream, ...rest } = extraOptions;
+  return {
+    ...(replyTo && { ReplyTo: replyTo }),
+    ...(cc && { Cc: Array.isArray(cc) ? cc.join(", ") : cc }),
+    ...(bcc && { Bcc: Array.isArray(bcc) ? bcc.join(", ") : bcc }),
+    ...(headers && {
+      Headers: Object.entries(headers).map(([Name, Value]) => ({ Name, Value })),
+    }),
+    ...(messageStream && { MessageStream: messageStream }),
+    ...rest,
+  };
+}
+
+function unsupported(method) {
+  return async () => {
+    throw new Error(`[xEmail] '${method}()' is not supported by provider 'postmark'.`);
+  };
+}
+
+/**
+ * Create the Postmark-backed xEmail service.
+ * @param {object} config
+ * @param {string} config.apiKey - Postmark server API token
+ * @param {string} config.fromEmail - Verified sender email address
+ * @param {string} [config.fromName] - Sender display name
+ * @param {import('fastify').FastifyBaseLogger} config.log
+ */
+export function createService({ apiKey, fromEmail, fromName, log }) {
+  const client = new postmark.ServerClient(apiKey);
+
+  const from = fromName ? `${fromName} <${fromEmail}>` : fromEmail;
+  const toAddresses = (to) => (Array.isArray(to) ? to.join(", ") : to);
+
+  return {
+    /**
+     * Send an email.
+     * @param {string|string[]} to - Recipient email(s)
+     * @param {string} subject - Email subject
+     * @param {string} html - HTML content
+     * @param {string} [text] - Plain text fallback (auto-generated from HTML if omitted)
+     * @param {object} [extraOptions] - Additional options (replyTo, cc, bcc, headers, messageStream)
+     * @returns {Promise<{success: boolean, statusCode: number, messageId: string}>}
+     */
+    send: async (to, subject, html, text = null, extraOptions = {}) => {
+      if (!to) throw new Error("[xEmail] 'to' is required for send().");
+      if (!subject) throw new Error("[xEmail] 'subject' is required for send().");
+      if (!html) throw new Error("[xEmail] 'html' is required for send().");
+
+      try {
+        const response = await client.sendEmail({
+          From: from,
+          To: toAddresses(to),
+          Subject: subject,
+          HtmlBody: html,
+          TextBody: text || html.replace(/<[^>]*>/g, ""),
+          ...mapExtraOptions(extraOptions),
+        });
+        return { success: true, statusCode: 200, messageId: response.MessageID };
+      } catch (error) {
+        log.error({ err: error }, "xEmail send failed");
+        throw new Error(`[xEmail] Failed to send email: ${error.message}`);
+      }
+    },
+
+    /**
+     * Send an email using a Postmark template.
+     * @param {string|string[]} to - Recipient email(s)
+     * @param {string} subject - Email subject (passed to the template model)
+     * @param {string|number} templateId - Postmark template alias (string) or ID (number)
+     * @param {object} [dynamicData] - Template variables
+     * @param {object} [extraOptions] - Additional options (replyTo, cc, bcc, headers, messageStream)
+     * @returns {Promise<{success: boolean, statusCode: number, messageId: string}>}
+     */
+    sendTemplate: async (to, subject, templateId, dynamicData = {}, extraOptions = {}) => {
+      if (!to) throw new Error("[xEmail] 'to' is required for sendTemplate().");
+      if (!subject) throw new Error("[xEmail] 'subject' is required for sendTemplate().");
+      if (!templateId) throw new Error("[xEmail] 'templateId' is required for sendTemplate().");
+
+      const templateKey =
+        typeof templateId === "number" ? { TemplateId: templateId } : { TemplateAlias: templateId };
+
+      try {
+        const response = await client.sendEmailWithTemplate({
+          From: from,
+          To: toAddresses(to),
+          ...templateKey,
+          TemplateModel: { ...dynamicData, subject },
+          ...mapExtraOptions(extraOptions),
+        });
+        return { success: true, statusCode: 200, messageId: response.MessageID };
+      } catch (error) {
+        log.error({ err: error }, "xEmail sendTemplate failed");
+        throw new Error(`[xEmail] Failed to send template email: ${error.message}`);
+      }
+    },
+
+    /**
+     * Send an email with file attachments.
+     * @param {string|string[]} to - Recipient email(s)
+     * @param {string} subject - Email subject
+     * @param {string} html - HTML content
+     * @param {Array<{content: string, filename: string, type: string, disposition?: string}>} attachments
+     * @returns {Promise<{success: boolean, statusCode: number, messageId: string}>}
+     */
+    sendWithAttachments: async (to, subject, html, attachments) => {
+      if (!to) throw new Error("[xEmail] 'to' is required for sendWithAttachments().");
+      if (!subject) throw new Error("[xEmail] 'subject' is required for sendWithAttachments().");
+      if (!html) throw new Error("[xEmail] 'html' is required for sendWithAttachments().");
+      if (!Array.isArray(attachments) || attachments.length === 0) {
+        throw new Error("[xEmail] 'attachments' must be a non-empty array.");
+      }
+
+      try {
+        const response = await client.sendEmail({
+          From: from,
+          To: toAddresses(to),
+          Subject: subject,
+          HtmlBody: html,
+          Attachments: attachments.map((att) => ({
+            Name: att.filename,
+            Content: att.content,
+            ContentType: att.type,
+            ...(att.disposition === "inline" && { ContentID: `cid:${att.filename}` }),
+          })),
+        });
+        return { success: true, statusCode: 200, messageId: response.MessageID };
+      } catch (error) {
+        log.error({ err: error }, "xEmail sendWithAttachments failed");
+        throw new Error(`[xEmail] Failed to send email with attachments: ${error.message}`);
+      }
+    },
+
+    /**
+     * Send bulk emails (same content to multiple recipients).
+     * Postmark has no shared-body multi-recipient endpoint, so one email is
+     * sent per recipient, in chunks of 500 concurrent requests.
+     * @param {string[]} to - Array of recipient emails
+     * @param {string} subject - Email subject
+     * @param {string} html - HTML content
+     * @returns {Promise<{success: boolean, count: number, statusCode: number}>}
+     */
+    sendBulk: async (to, subject, html) => {
+      if (!Array.isArray(to) || to.length === 0) {
+        throw new Error("[xEmail] 'to' must be a non-empty array for sendBulk().");
+      }
+      if (!subject) throw new Error("[xEmail] 'subject' is required for sendBulk().");
+      if (!html) throw new Error("[xEmail] 'html' is required for sendBulk().");
+
+      try {
+        for (let i = 0; i < to.length; i += BATCH_LIMIT) {
+          const chunk = to.slice(i, i + BATCH_LIMIT);
+          await Promise.all(
+            chunk.map((To) =>
+              client.sendEmail({ From: from, To, Subject: subject, HtmlBody: html })
+            )
+          );
+        }
+        return { success: true, count: to.length, statusCode: 200 };
+      } catch (error) {
+        log.error({ err: error }, "xEmail sendBulk failed");
+        throw new Error(`[xEmail] Failed to send bulk emails: ${error.message}`);
+      }
+    },
+
+    /**
+     * Send personalized emails (different content per recipient) via the
+     * Postmark batch endpoint. Never throws for per-recipient failures.
+     * @param {Array<{to: string, subject: string, html: string, text?: string}>} messages
+     * @returns {Promise<Array<{success: boolean, to: string, statusCode?: number, error?: string}>>}
+     */
+    sendPersonalizedBulk: async (messages) => {
+      if (!Array.isArray(messages) || messages.length === 0) {
+        throw new Error(
+          "[xEmail] 'messages' must be a non-empty array for sendPersonalizedBulk()."
+        );
+      }
+
+      const results = [];
+      for (let i = 0; i < messages.length; i += BATCH_LIMIT) {
+        const chunk = messages.slice(i, i + BATCH_LIMIT);
+        let batchResults;
+        try {
+          batchResults = await client.sendEmailBatch(
+            chunk.map((msg) => ({
+              From: from,
+              To: msg.to,
+              Subject: msg.subject,
+              HtmlBody: msg.html,
+              TextBody: msg.text,
+            }))
+          );
+        } catch (error) {
+          log.error({ err: error }, "xEmail sendPersonalizedBulk batch failed");
+          batchResults = chunk.map(() => ({ ErrorCode: -1, Message: error.message }));
+        }
+
+        for (let j = 0; j < chunk.length; j++) {
+          const result = batchResults[j];
+          if (result.ErrorCode === 0) {
+            results.push({ success: true, to: chunk[j].to, statusCode: 200 });
+          } else {
+            results.push({ success: false, to: chunk[j].to, error: result.Message });
+          }
+        }
+      }
+      return results;
+    },
+
+    // The following features are SendGrid-only; Postmark has no equivalent APIs.
+    validate: unsupported("validate"),
+    addContact: unsupported("addContact"),
+    searchContact: unsupported("searchContact"),
+    deleteContact: unsupported("deleteContact"),
+    createList: unsupported("createList"),
+    getLists: unsupported("getLists"),
+    deleteList: unsupported("deleteList"),
+  };
+}

package/src/providers/sendgrid.js

@@ -0,0 +1,389 @@
+import sgClient from "@sendgrid/client";
+import sgMail from "@sendgrid/mail";
+
+/**
+ * Create the SendGrid-backed xEmail service.
+ * @param {object} config
+ * @param {string} config.apiKey - SendGrid API key
+ * @param {string} config.fromEmail - Verified sender email address
+ * @param {string} [config.fromName] - Sender display name
+ * @param {import('fastify').FastifyBaseLogger} config.log
+ */
+export function createService({ apiKey, fromEmail, fromName, log }) {
+  sgMail.setApiKey(apiKey);
+  sgClient.setApiKey(apiKey);
+
+  const from = fromName ? { email: fromEmail, name: fromName } : fromEmail;
+
+  return {
+    /**
+     * Send an email.
+     * @param {string|string[]} to - Recipient email(s)
+     * @param {string} subject - Email subject
+     * @param {string} html - HTML content
+     * @param {string} [text] - Plain text fallback (auto-generated from HTML if omitted)
+     * @param {object} [extraOptions] - Additional SendGrid mail options
+     * @returns {Promise<{success: boolean, statusCode: number, messageId: string}>}
+     */
+    send: async (to, subject, html, text = null, extraOptions = {}) => {
+      if (!to) throw new Error("[xEmail] 'to' is required for send().");
+      if (!subject) throw new Error("[xEmail] 'subject' is required for send().");
+      if (!html) throw new Error("[xEmail] 'html' is required for send().");
+
+      try {
+        const msg = {
+          to,
+          from,
+          subject,
+          html,
+          text: text || html.replace(/<[^>]*>/g, ""),
+          ...extraOptions,
+        };
+
+        const response = await sgMail.send(msg);
+        return {
+          success: true,
+          statusCode: response[0].statusCode,
+          messageId: response[0].headers["x-message-id"],
+        };
+      } catch (error) {
+        log.error({ err: error }, "xEmail send failed");
+        throw new Error(`[xEmail] Failed to send email: ${error.message}`);
+      }
+    },
+
+    /**
+     * Send an email using a SendGrid dynamic template.
+     * @param {string|string[]} to - Recipient email(s)
+     * @param {string} subject - Email subject
+     * @param {string} templateId - SendGrid dynamic template ID (d-xxx)
+     * @param {object} [dynamicData] - Template variables
+     * @param {object} [extraOptions] - Additional SendGrid mail options
+     * @returns {Promise<{success: boolean, statusCode: number, messageId: string}>}
+     */
+    sendTemplate: async (to, subject, templateId, dynamicData = {}, extraOptions = {}) => {
+      if (!to) throw new Error("[xEmail] 'to' is required for sendTemplate().");
+      if (!subject) throw new Error("[xEmail] 'subject' is required for sendTemplate().");
+      if (!templateId) throw new Error("[xEmail] 'templateId' is required for sendTemplate().");
+
+      try {
+        const msg = {
+          to,
+          from,
+          subject,
+          templateId,
+          dynamicTemplateData: { ...dynamicData, subject },
+          ...extraOptions,
+        };
+
+        const response = await sgMail.send(msg);
+        return {
+          success: true,
+          statusCode: response[0].statusCode,
+          messageId: response[0].headers["x-message-id"],
+        };
+      } catch (error) {
+        log.error({ err: error }, "xEmail sendTemplate failed");
+        throw new Error(`[xEmail] Failed to send template email: ${error.message}`);
+      }
+    },
+
+    /**
+     * Send an email with file attachments.
+     * @param {string|string[]} to - Recipient email(s)
+     * @param {string} subject - Email subject
+     * @param {string} html - HTML content
+     * @param {Array<{content: string, filename: string, type: string, disposition?: string}>} attachments
+     * @returns {Promise<{success: boolean, statusCode: number, messageId: string}>}
+     */
+    sendWithAttachments: async (to, subject, html, attachments) => {
+      if (!to) throw new Error("[xEmail] 'to' is required for sendWithAttachments().");
+      if (!subject) throw new Error("[xEmail] 'subject' is required for sendWithAttachments().");
+      if (!html) throw new Error("[xEmail] 'html' is required for sendWithAttachments().");
+      if (!Array.isArray(attachments) || attachments.length === 0) {
+        throw new Error("[xEmail] 'attachments' must be a non-empty array.");
+      }
+
+      try {
+        const msg = {
+          to,
+          from,
+          subject,
+          html,
+          attachments: attachments.map((att) => ({
+            content: att.content,
+            filename: att.filename,
+            type: att.type,
+            disposition: att.disposition || "attachment",
+          })),
+        };
+
+        const response = await sgMail.send(msg);
+        return {
+          success: true,
+          statusCode: response[0].statusCode,
+          messageId: response[0].headers["x-message-id"],
+        };
+      } catch (error) {
+        log.error({ err: error }, "xEmail sendWithAttachments failed");
+        throw new Error(`[xEmail] Failed to send email with attachments: ${error.message}`);
+      }
+    },
+
+    /**
+     * Send bulk emails (same content to multiple recipients).
+     * @param {string[]} to - Array of recipient emails
+     * @param {string} subject - Email subject
+     * @param {string} html - HTML content
+     * @returns {Promise<{success: boolean, count: number, statusCode: number}>}
+     */
+    sendBulk: async (to, subject, html) => {
+      if (!Array.isArray(to) || to.length === 0) {
+        throw new Error("[xEmail] 'to' must be a non-empty array for sendBulk().");
+      }
+      if (!subject) throw new Error("[xEmail] 'subject' is required for sendBulk().");
+      if (!html) throw new Error("[xEmail] 'html' is required for sendBulk().");
+
+      try {
+        const msg = { to, from, subject, html };
+        const response = await sgMail.sendMultiple(msg);
+        return { success: true, count: to.length, statusCode: response[0].statusCode };
+      } catch (error) {
+        log.error({ err: error }, "xEmail sendBulk failed");
+        throw new Error(`[xEmail] Failed to send bulk emails: ${error.message}`);
+      }
+    },
+
+    /**
+     * Send personalized emails (different content per recipient).
+     * @param {Array<{to: string, subject: string, html: string, text?: string}>} messages
+     * @returns {Promise<Array<{success: boolean, to: string, statusCode?: number, error?: string}>>}
+     */
+    sendPersonalizedBulk: async (messages) => {
+      if (!Array.isArray(messages) || messages.length === 0) {
+        throw new Error(
+          "[xEmail] 'messages' must be a non-empty array for sendPersonalizedBulk()."
+        );
+      }
+
+      const mailMessages = messages.map((msg) => ({
+        to: msg.to,
+        from,
+        subject: msg.subject,
+        html: msg.html,
+        text: msg.text,
+      }));
+
+      const responses = await Promise.allSettled(mailMessages.map((msg) => sgMail.send(msg)));
+
+      return responses.map((result, index) => {
+        if (result.status === "fulfilled") {
+          return {
+            success: true,
+            to: messages[index].to,
+            statusCode: result.value[0].statusCode,
+          };
+        }
+        return {
+          success: false,
+          to: messages[index].to,
+          error: result.reason.message,
+        };
+      });
+    },
+
+    /**
+     * Validate an email address using SendGrid Email Validation API.
+     * @param {string} email - Email to validate
+     * @returns {Promise<{email: string, valid: boolean, verdict: string, score?: number, result?: object, error?: string}>}
+     */
+    validate: async (email) => {
+      if (!email || typeof email !== "string") {
+        throw new Error("[xEmail] 'email' (string) is required for validate().");
+      }
+
+      try {
+        const [response, body] = await sgClient.request({
+          url: `/v3/validations/email`,
+          method: "POST",
+          body: { email },
+        });
+
+        if (response.statusCode === 200) {
+          return {
+            email,
+            valid: body.result?.verdict === "Valid",
+            verdict: body.result?.verdict,
+            score: body.result?.score,
+            result: body.result,
+          };
+        }
+
+        throw new Error(
+          body.errors ? body.errors.map((e) => e.message).join(", ") : "Validation failed"
+        );
+      } catch (error) {
+        log.error({ err: error }, "xEmail validate failed");
+        return {
+          email,
+          valid: false,
+          verdict: "Unknown",
+          error: error.message,
+        };
+      }
+    },
+
+    /**
+     * Add or update a contact in SendGrid Marketing.
+     * @param {string} email - Contact email
+     * @param {object} [data] - Contact data (firstName, lastName, customFields)
+     * @param {string[]} [listIds] - List IDs to add the contact to
+     * @returns {Promise<{success: boolean, jobId: string, email: string}>}
+     */
+    addContact: async (email, data = {}, listIds = []) => {
+      if (!email || typeof email !== "string") {
+        throw new Error("[xEmail] 'email' (string) is required for addContact().");
+      }
+
+      try {
+        const [response, body] = await sgClient.request({
+          url: `/v3/marketing/contacts`,
+          method: "PUT",
+          body: {
+            list_ids: listIds,
+            contacts: [
+              {
+                email,
+                first_name: data.firstName || data.first_name,
+                last_name: data.lastName || data.last_name,
+                ...data.customFields,
+              },
+            ],
+          },
+        });
+
+        if (response.statusCode === 200 || response.statusCode === 202) {
+          return { success: true, jobId: body.job_id, email };
+        }
+
+        throw new Error(`Unexpected status code: ${response.statusCode}`);
+      } catch (error) {
+        log.error({ err: error }, "xEmail addContact failed");
+        throw new Error(`[xEmail] Failed to add contact: ${error.message}`);
+      }
+    },
+
+    /**
+     * Search for a contact by email.
+     * @param {string} email - Contact email
+     * @returns {Promise<{found: boolean, contact?: object}>}
+     */
+    searchContact: async (email) => {
+      if (!email || typeof email !== "string") {
+        throw new Error("[xEmail] 'email' (string) is required for searchContact().");
+      }
+
+      try {
+        const [response, body] = await sgClient.request({
+          url: `/v3/marketing/contacts/search/emails`,
+          method: "POST",
+          body: { emails: [email] },
+        });
+
+        if (response.statusCode === 200 && body.result?.[email]) {
+          return { found: true, contact: body.result[email].contact };
+        }
+
+        return { found: false };
+      } catch (error) {
+        log.error({ err: error }, "xEmail searchContact failed");
+        throw new Error(`[xEmail] Failed to search contact: ${error.message}`);
+      }
+    },
+
+    /**
+     * Delete a contact by ID.
+     * @param {string} contactId - Contact ID
+     * @returns {Promise<boolean>}
+     */
+    deleteContact: async (contactId) => {
+      if (!contactId || typeof contactId !== "string") {
+        throw new Error("[xEmail] 'contactId' (string) is required for deleteContact().");
+      }
+
+      try {
+        const [response] = await sgClient.request({
+          url: `/v3/marketing/contacts`,
+          method: "DELETE",
+          qs: { ids: contactId },
+        });
+        return response.statusCode === 202 || response.statusCode === 200;
+      } catch (error) {
+        log.error({ err: error }, "xEmail deleteContact failed");
+        throw new Error(`[xEmail] Failed to delete contact: ${error.message}`);
+      }
+    },
+
+    /**
+     * Create a new contact list.
+     * @param {string} name - List name
+     * @returns {Promise<{success: boolean, list: object}>}
+     */
+    createList: async (name) => {
+      if (!name || typeof name !== "string") {
+        throw new Error("[xEmail] 'name' (string) is required for createList().");
+      }
+
+      try {
+        const [, body] = await sgClient.request({
+          url: `/v3/marketing/lists`,
+          method: "POST",
+          body: { name },
+        });
+        return { success: true, list: body };
+      } catch (error) {
+        log.error({ err: error }, "xEmail createList failed");
+        throw new Error(`[xEmail] Failed to create list: ${error.message}`);
+      }
+    },
+
+    /**
+     * Get all contact lists.
+     * @returns {Promise<object[]>}
+     */
+    getLists: async () => {
+      try {
+        const [, body] = await sgClient.request({
+          url: `/v3/marketing/lists`,
+          method: "GET",
+        });
+        return body.result || [];
+      } catch (error) {
+        log.error({ err: error }, "xEmail getLists failed");
+        throw new Error(`[xEmail] Failed to get lists: ${error.message}`);
+      }
+    },
+
+    /**
+     * Delete a contact list.
+     * @param {string} listId - List ID
+     * @returns {Promise<boolean>}
+     */
+    deleteList: async (listId) => {
+      if (!listId || typeof listId !== "string") {
+        throw new Error("[xEmail] 'listId' (string) is required for deleteList().");
+      }
+
+      try {
+        const [response] = await sgClient.request({
+          url: `/v3/marketing/lists/${listId}`,
+          method: "DELETE",
+        });
+        return [200, 202, 204].includes(response.statusCode);
+      } catch (error) {
+        log.error({ err: error }, "xEmail deleteList failed");
+        throw new Error(`[xEmail] Failed to delete list: ${error.message}`);
+      }
+    },
+  };
+}

package/src/xEmail.js

@@ -1,420 +1,63 @@
-import sgClient from "@sendgrid/client";
-import sgMail from "@sendgrid/mail";
 import fp from "fastify-plugin";
+import { createService as createPostmarkService } from "./providers/postmark.js";
+import { createService as createSendGridService } from "./providers/sendgrid.js";
+
+const PROVIDERS = {
+  sendgrid: createSendGridService,
+  postmark: createPostmarkService,
+};
+
+const API_KEY_EXAMPLES = {
+  sendgrid: "SG.your-api-key",
+  postmark: "your-postmark-server-token",
+};
 
 /**
  * @param {import('fastify').FastifyInstance} fastify
  * @param {object} options
- * @param {string} options.apiKey - SendGrid API key
+ * @param {'sendgrid'|'postmark'} [options.provider='sendgrid'] - Email provider ('sendgrid' is legacy; 'postmark' is the migration target)
+ * @param {string} options.apiKey - Provider API key (SendGrid API key or Postmark server token)
  * @param {string} options.fromEmail - Verified sender email address
  * @param {string} [options.fromName] - Sender display name
  * @param {boolean} [options.active=true] - Enable/disable the plugin
  */
 async function xEmail(fastify, options) {
-  const { active = true, apiKey, fromEmail, fromName } = options;
-
-  if (active === false) return;
+  const { active = true, provider = "sendgrid", apiKey, fromEmail, fromName } = options;
 
   if (typeof active !== "boolean") {
     throw new Error("xemail: option `active` must be a boolean");
   }
 
+  if (active === false) return;
+
+  if (!PROVIDERS[provider]) {
+    throw new Error("xemail: option `provider` must be 'sendgrid' or 'postmark'");
+  }
+
   if (!apiKey || typeof apiKey !== "string") {
     throw new Error(
-      "xemail: option `apiKey` must be a string, e.g. `app.register(xEmail, { apiKey: 'SG.your-api-key' })`"
+      `xemail: option \`apiKey\` must be a string, e.g. \`app.register(xEmail, { apiKey: '${API_KEY_EXAMPLES[provider]}' })\``
     );
   }
 
   if (!fromEmail || typeof fromEmail !== "string") {
     throw new Error(
-      "xemail: option `fromEmail` must be a string, e.g. `app.register(xEmail, { apiKey: 'SG.your-api-key', fromEmail: 'noreply@example.com' })`"
+      `xemail: option \`fromEmail\` must be a string, e.g. \`app.register(xEmail, { apiKey: '${API_KEY_EXAMPLES[provider]}', fromEmail: 'noreply@example.com' })\``
     );
   }
 
   if (fromName !== undefined && typeof fromName !== "string") {
     throw new Error(
-      "xemail: option `fromName` must be a string, e.g. `app.register(xEmail, { apiKey: 'SG.your-api-key', fromEmail: 'noreply@example.com', fromName: 'My App' })`"
+      `xemail: option \`fromName\` must be a string, e.g. \`app.register(xEmail, { apiKey: '${API_KEY_EXAMPLES[provider]}', fromEmail: 'noreply@example.com', fromName: 'My App' })\``
     );
   }
 
-  sgMail.setApiKey(apiKey);
-  sgClient.setApiKey(apiKey);
-
-  const from = fromName ? { email: fromEmail, name: fromName } : fromEmail;
-
-  fastify.log.info("xEmail (SendGrid) initialized");
-
-  fastify.decorate("xEmail", {
-    /**
-     * Send an email.
-     * @param {string|string[]} to - Recipient email(s)
-     * @param {string} subject - Email subject
-     * @param {string} html - HTML content
-     * @param {string} [text] - Plain text fallback (auto-generated from HTML if omitted)
-     * @param {object} [extraOptions] - Additional SendGrid mail options
-     * @returns {Promise<{success: boolean, statusCode: number, messageId: string}>}
-     */
-    send: async (to, subject, html, text = null, extraOptions = {}) => {
-      if (!to) throw new Error("[xEmail] 'to' is required for send().");
-      if (!subject) throw new Error("[xEmail] 'subject' is required for send().");
-      if (!html) throw new Error("[xEmail] 'html' is required for send().");
-
-      try {
-        const msg = {
-          to,
-          from,
-          subject,
-          html,
-          text: text || html.replace(/<[^>]*>/g, ""),
-          ...extraOptions,
-        };
-
-        const response = await sgMail.send(msg);
-        return {
-          success: true,
-          statusCode: response[0].statusCode,
-          messageId: response[0].headers["x-message-id"],
-        };
-      } catch (error) {
-        fastify.log.error({ err: error }, "xEmail send failed");
-        throw new Error(`[xEmail] Failed to send email: ${error.message}`);
-      }
-    },
-
-    /**
-     * Send an email using a SendGrid dynamic template.
-     * @param {string|string[]} to - Recipient email(s)
-     * @param {string} subject - Email subject
-     * @param {string} templateId - SendGrid dynamic template ID (d-xxx)
-     * @param {object} [dynamicData] - Template variables
-     * @param {object} [extraOptions] - Additional SendGrid mail options
-     * @returns {Promise<{success: boolean, statusCode: number, messageId: string}>}
-     */
-    sendTemplate: async (to, subject, templateId, dynamicData = {}, extraOptions = {}) => {
-      if (!to) throw new Error("[xEmail] 'to' is required for sendTemplate().");
-      if (!subject) throw new Error("[xEmail] 'subject' is required for sendTemplate().");
-      if (!templateId) throw new Error("[xEmail] 'templateId' is required for sendTemplate().");
-
-      try {
-        const msg = {
-          to,
-          from,
-          subject,
-          templateId,
-          dynamicTemplateData: { ...dynamicData, subject },
-          ...extraOptions,
-        };
-
-        const response = await sgMail.send(msg);
-        return {
-          success: true,
-          statusCode: response[0].statusCode,
-          messageId: response[0].headers["x-message-id"],
-        };
-      } catch (error) {
-        fastify.log.error({ err: error }, "xEmail sendTemplate failed");
-        throw new Error(`[xEmail] Failed to send template email: ${error.message}`);
-      }
-    },
-
-    /**
-     * Send an email with file attachments.
-     * @param {string|string[]} to - Recipient email(s)
-     * @param {string} subject - Email subject
-     * @param {string} html - HTML content
-     * @param {Array<{content: string, filename: string, type: string, disposition?: string}>} attachments
-     * @returns {Promise<{success: boolean, statusCode: number, messageId: string}>}
-     */
-    sendWithAttachments: async (to, subject, html, attachments) => {
-      if (!to) throw new Error("[xEmail] 'to' is required for sendWithAttachments().");
-      if (!subject) throw new Error("[xEmail] 'subject' is required for sendWithAttachments().");
-      if (!html) throw new Error("[xEmail] 'html' is required for sendWithAttachments().");
-      if (!Array.isArray(attachments) || attachments.length === 0) {
-        throw new Error("[xEmail] 'attachments' must be a non-empty array.");
-      }
-
-      try {
-        const msg = {
-          to,
-          from,
-          subject,
-          html,
-          attachments: attachments.map((att) => ({
-            content: att.content,
-            filename: att.filename,
-            type: att.type,
-            disposition: att.disposition || "attachment",
-          })),
-        };
-
-        const response = await sgMail.send(msg);
-        return {
-          success: true,
-          statusCode: response[0].statusCode,
-          messageId: response[0].headers["x-message-id"],
-        };
-      } catch (error) {
-        fastify.log.error({ err: error }, "xEmail sendWithAttachments failed");
-        throw new Error(`[xEmail] Failed to send email with attachments: ${error.message}`);
-      }
-    },
-
-    /**
-     * Send bulk emails (same content to multiple recipients).
-     * @param {string[]} to - Array of recipient emails
-     * @param {string} subject - Email subject
-     * @param {string} html - HTML content
-     * @returns {Promise<{success: boolean, count: number, statusCode: number}>}
-     */
-    sendBulk: async (to, subject, html) => {
-      if (!Array.isArray(to) || to.length === 0) {
-        throw new Error("[xEmail] 'to' must be a non-empty array for sendBulk().");
-      }
-      if (!subject) throw new Error("[xEmail] 'subject' is required for sendBulk().");
-      if (!html) throw new Error("[xEmail] 'html' is required for sendBulk().");
-
-      try {
-        const msg = { to, from, subject, html };
-        const response = await sgMail.sendMultiple(msg);
-        return { success: true, count: to.length, statusCode: response[0].statusCode };
-      } catch (error) {
-        fastify.log.error({ err: error }, "xEmail sendBulk failed");
-        throw new Error(`[xEmail] Failed to send bulk emails: ${error.message}`);
-      }
-    },
-
-    /**
-     * Send personalized emails (different content per recipient).
-     * @param {Array<{to: string, subject: string, html: string, text?: string}>} messages
-     * @returns {Promise<Array<{success: boolean, to: string, statusCode?: number, error?: string}>>}
-     */
-    sendPersonalizedBulk: async (messages) => {
-      if (!Array.isArray(messages) || messages.length === 0) {
-        throw new Error(
-          "[xEmail] 'messages' must be a non-empty array for sendPersonalizedBulk()."
-        );
-      }
-
-      const mailMessages = messages.map((msg) => ({
-        to: msg.to,
-        from,
-        subject: msg.subject,
-        html: msg.html,
-        text: msg.text,
-      }));
-
-      const responses = await Promise.allSettled(mailMessages.map((msg) => sgMail.send(msg)));
-
-      return responses.map((result, index) => {
-        if (result.status === "fulfilled") {
-          return {
-            success: true,
-            to: messages[index].to,
-            statusCode: result.value[0].statusCode,
-          };
-        }
-        return {
-          success: false,
-          to: messages[index].to,
-          error: result.reason.message,
-        };
-      });
-    },
-
-    /**
-     * Validate an email address using SendGrid Email Validation API.
-     * @param {string} email - Email to validate
-     * @returns {Promise<{email: string, valid: boolean, verdict: string, score?: number, result?: object, error?: string}>}
-     */
-    validate: async (email) => {
-      if (!email || typeof email !== "string") {
-        throw new Error("[xEmail] 'email' (string) is required for validate().");
-      }
-
-      try {
-        const [response, body] = await sgClient.request({
-          url: `/v3/validations/email`,
-          method: "POST",
-          body: { email },
-        });
-
-        if (response.statusCode === 200) {
-          return {
-            email,
-            valid: body.result?.verdict === "Valid",
-            verdict: body.result?.verdict,
-            score: body.result?.score,
-            result: body.result,
-          };
-        }
-
-        throw new Error(
-          body.errors ? body.errors.map((e) => e.message).join(", ") : "Validation failed"
-        );
-      } catch (error) {
-        fastify.log.error({ err: error }, "xEmail validate failed");
-        return {
-          email,
-          valid: false,
-          verdict: "Unknown",
-          error: error.message,
-        };
-      }
-    },
-
-    /**
-     * Add or update a contact in SendGrid Marketing.
-     * @param {string} email - Contact email
-     * @param {object} [data] - Contact data (firstName, lastName, customFields)
-     * @param {string[]} [listIds] - List IDs to add the contact to
-     * @returns {Promise<{success: boolean, jobId: string, email: string}>}
-     */
-    addContact: async (email, data = {}, listIds = []) => {
-      if (!email || typeof email !== "string") {
-        throw new Error("[xEmail] 'email' (string) is required for addContact().");
-      }
-
-      try {
-        const [response, body] = await sgClient.request({
-          url: `/v3/marketing/contacts`,
-          method: "PUT",
-          body: {
-            list_ids: listIds,
-            contacts: [
-              {
-                email,
-                first_name: data.firstName || data.first_name,
-                last_name: data.lastName || data.last_name,
-                ...data.customFields,
-              },
-            ],
-          },
-        });
-
-        if (response.statusCode === 200 || response.statusCode === 202) {
-          return { success: true, jobId: body.job_id, email };
-        }
-
-        throw new Error(`Unexpected status code: ${response.statusCode}`);
-      } catch (error) {
-        fastify.log.error({ err: error }, "xEmail addContact failed");
-        throw new Error(`[xEmail] Failed to add contact: ${error.message}`);
-      }
-    },
-
-    /**
-     * Search for a contact by email.
-     * @param {string} email - Contact email
-     * @returns {Promise<{found: boolean, contact?: object}>}
-     */
-    searchContact: async (email) => {
-      if (!email || typeof email !== "string") {
-        throw new Error("[xEmail] 'email' (string) is required for searchContact().");
-      }
-
-      try {
-        const [response, body] = await sgClient.request({
-          url: `/v3/marketing/contacts/search/emails`,
-          method: "POST",
-          body: { emails: [email] },
-        });
-
-        if (response.statusCode === 200 && body.result?.[email]) {
-          return { found: true, contact: body.result[email].contact };
-        }
-
-        return { found: false };
-      } catch (error) {
-        fastify.log.error({ err: error }, "xEmail searchContact failed");
-        throw new Error(`[xEmail] Failed to search contact: ${error.message}`);
-      }
-    },
-
-    /**
-     * Delete a contact by ID.
-     * @param {string} contactId - Contact ID
-     * @returns {Promise<boolean>}
-     */
-    deleteContact: async (contactId) => {
-      if (!contactId || typeof contactId !== "string") {
-        throw new Error("[xEmail] 'contactId' (string) is required for deleteContact().");
-      }
-
-      try {
-        const [response] = await sgClient.request({
-          url: `/v3/marketing/contacts`,
-          method: "DELETE",
-          qs: { ids: contactId },
-        });
-        return response.statusCode === 202 || response.statusCode === 200;
-      } catch (error) {
-        fastify.log.error({ err: error }, "xEmail deleteContact failed");
-        throw new Error(`[xEmail] Failed to delete contact: ${error.message}`);
-      }
-    },
-
-    /**
-     * Create a new contact list.
-     * @param {string} name - List name
-     * @returns {Promise<{success: boolean, list: object}>}
-     */
-    createList: async (name) => {
-      if (!name || typeof name !== "string") {
-        throw new Error("[xEmail] 'name' (string) is required for createList().");
-      }
-
-      try {
-        const [, body] = await sgClient.request({
-          url: `/v3/marketing/lists`,
-          method: "POST",
-          body: { name },
-        });
-        return { success: true, list: body };
-      } catch (error) {
-        fastify.log.error({ err: error }, "xEmail createList failed");
-        throw new Error(`[xEmail] Failed to create list: ${error.message}`);
-      }
-    },
-
-    /**
-     * Get all contact lists.
-     * @returns {Promise<object[]>}
-     */
-    getLists: async () => {
-      try {
-        const [, body] = await sgClient.request({
-          url: `/v3/marketing/lists`,
-          method: "GET",
-        });
-        return body.result || [];
-      } catch (error) {
-        fastify.log.error({ err: error }, "xEmail getLists failed");
-        throw new Error(`[xEmail] Failed to get lists: ${error.message}`);
-      }
-    },
-
-    /**
-     * Delete a contact list.
-     * @param {string} listId - List ID
-     * @returns {Promise<boolean>}
-     */
-    deleteList: async (listId) => {
-      if (!listId || typeof listId !== "string") {
-        throw new Error("[xEmail] 'listId' (string) is required for deleteList().");
-      }
+  fastify.log.info(`xEmail (${provider}) initialized`);
 
-      try {
-        const [response] = await sgClient.request({
-          url: `/v3/marketing/lists/${listId}`,
-          method: "DELETE",
-        });
-        return [200, 202, 204].includes(response.statusCode);
-      } catch (error) {
-        fastify.log.error({ err: error }, "xEmail deleteList failed");
-        throw new Error(`[xEmail] Failed to delete list: ${error.message}`);
-      }
-    },
-  });
+  fastify.decorate(
+    "xEmail",
+    PROVIDERS[provider]({ apiKey, fromEmail, fromName, log: fastify.log })
+  );
 }
 
 export default fp(xEmail, {