@stacksjs/email 0.70.87 → 0.70.90

package/dist/drivers/sendgrid.js

@@ -0,0 +1,136 @@
+import { Buffer } from "node:buffer";
+import { config } from "@stacksjs/config";
+import { log } from "@stacksjs/logging";
+import { template } from "../template";
+import { filterStringHeaders } from "../validation";
+import { BaseEmailDriver } from "./base";
+
+export class SendGridDriver extends BaseEmailDriver {
+  name = "sendgrid";
+  apiKey = null;
+  getApiKey() {
+    if (!this.apiKey)
+      this.apiKey = config.services.sendgrid?.apiKey ?? "";
+    return this.apiKey;
+  }
+  async send(message, options) {
+    const logContext = {
+      provider: this.name,
+      to: message.to,
+      subject: message.subject
+    };
+    log.info("Sending email via SendGrid...", logContext);
+    try {
+      this.validateMessage(message);
+      let htmlContent;
+      if (message.template) {
+        const templ = await template(message.template, options);
+        if (templ && "html" in templ)
+          htmlContent = templ.html;
+      }
+      const finalHtml = htmlContent || message.html, content = [];
+      if (finalHtml)
+        content.push({
+          type: "text/html",
+          value: finalHtml
+        });
+      if (message.text)
+        content.push({
+          type: "text/plain",
+          value: message.text
+        });
+      if (content.length === 0)
+        throw Error("Email must have either HTML or text content");
+      const replyTo = this.firstSendGridAddress(message.replyTo), customHeaders = filterStringHeaders(message.headers), sendgridPayload = {
+        personalizations: [
+          {
+            to: this.formatSendGridAddresses(message.to),
+            ...message.cc && { cc: this.formatSendGridAddresses(message.cc) },
+            ...message.bcc && { bcc: this.formatSendGridAddresses(message.bcc) },
+            subject: message.subject
+          }
+        ],
+        from: {
+          email: message.from?.address || config.email.from?.address || "",
+          name: message.from?.name || config.email.from?.name
+        },
+        ...replyTo ? { reply_to: replyTo } : {},
+        ...customHeaders ? { headers: customHeaders } : {},
+        content,
+        ...message.attachments && {
+          attachments: message.attachments.map((attachment) => ({
+            filename: attachment.filename,
+            content: typeof attachment.content === "string" ? attachment.content : this.arrayBufferToBase64(attachment.content),
+            type: attachment.contentType,
+            disposition: "attachment"
+          }))
+        }
+      }, response = await this.sendWithRetry(sendgridPayload);
+      return this.handleSuccess(message, response.headers?.get("x-message-id") ?? void 0);
+    } catch (error) {
+      return this.handleError(error, message);
+    }
+  }
+  formatSendGridAddresses(addresses) {
+    if (!addresses)
+      return [];
+    if (typeof addresses === "string")
+      return [{ email: addresses }];
+    return addresses.map((addr) => {
+      if (typeof addr === "string")
+        return { email: addr };
+      return { email: addr.address, ...addr.name && { name: addr.name } };
+    });
+  }
+  firstSendGridAddress(value) {
+    if (!value)
+      return;
+    if (typeof value === "string")
+      return { email: value };
+    if (Array.isArray(value)) {
+      const first = value[0];
+      if (first === void 0)
+        return;
+      if (typeof first === "string")
+        return { email: first };
+      return { email: first.address, ...first.name && { name: first.name } };
+    }
+    return { email: value.address, ...value.name && { name: value.name } };
+  }
+  arrayBufferToBase64(buffer) {
+    let binary = "";
+    const bytes = new Uint8Array(buffer), len = bytes.byteLength;
+    for (let i = 0;i < len; i++)
+      binary += String.fromCharCode(bytes[i] ?? 0);
+    return typeof btoa === "function" ? btoa(binary) : Buffer.from(binary).toString("base64");
+  }
+  async sendWithRetry(payload, attempt = 1) {
+    try {
+      const response = await fetch("https://api.sendgrid.com/v3/mail/send", {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${this.getApiKey()}`,
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify(payload)
+      });
+      if (!response.ok) {
+        const errorData = await response.json(), err = Error(`SendGrid API error: ${response.status} - ${JSON.stringify(errorData)}`);
+        err.status = response.status;
+        throw err;
+      }
+      log.info(`[${this.name}] Email sent successfully`, { attempt });
+      return response;
+    } catch (error) {
+      const status = error?.status;
+      if (!(typeof status === "number" && status >= 400 && status < 500 && status !== 429) && attempt < (config.services.sendgrid?.maxRetries ?? 3)) {
+        const retryTimeout = config.services.sendgrid?.retryTimeout ?? 1000;
+        log.warn(`[${this.name}] Email send failed, retrying (${attempt}/${config.services.sendgrid?.maxRetries ?? 3})`);
+        await new Promise((resolve) => setTimeout(resolve, retryTimeout));
+        return this.sendWithRetry(payload, attempt + 1);
+      }
+      throw error;
+    }
+  }
+}
+export default SendGridDriver;

package/dist/drivers/ses.js

@@ -0,0 +1,113 @@
+import { config } from "@stacksjs/config";
+import { SESClient } from "@stacksjs/ts-cloud";
+import { template } from "../template";
+import { buildMimeMessage } from "../mime";
+import { filterStringHeaders } from "../validation";
+import { BaseEmailDriver } from "./base";
+
+export class SESDriver extends BaseEmailDriver {
+  name = "ses";
+  client = null;
+  getClient() {
+    if (!this.client) {
+      const sesConfig = config?.services?.ses, explicit = sesConfig?.credentials, hasExplicit = !!(explicit?.accessKeyId && explicit?.secretAccessKey);
+      this.client = new SESClient(sesConfig?.region || "us-east-1", hasExplicit ? {
+        accessKeyId: explicit.accessKeyId,
+        secretAccessKey: explicit.secretAccessKey,
+        sessionToken: explicit.sessionToken
+      } : void 0);
+    }
+    return this.client;
+  }
+  async send(message, options) {
+    try {
+      this.validateMessage(message);
+      let htmlContent;
+      if (message.template) {
+        const templ = await template(message.template, options);
+        if (templ && "html" in templ)
+          htmlContent = templ.html;
+      }
+      const finalHtml = htmlContent || message.html;
+      if (!finalHtml && !message.text)
+        throw Error("Email must have either HTML or text content");
+      const fromAddress = this.formatSourceAddress({
+        address: message.from?.address || config.email.from?.address || "",
+        name: message.from?.name || config.email.from?.name
+      }), toAddresses = this.formatAddresses(message.to), ccAddresses = this.formatAddresses(message.cc), bccAddresses = this.formatAddresses(message.bcc), replyToAddresses = message.replyTo ? this.formatAddressList(message.replyTo) : [], customHeaders = filterStringHeaders(message.headers);
+      if (!!(message.attachments && message.attachments.length > 0) || !!customHeaders) {
+        const raw = buildMimeMessage({
+          from: fromAddress,
+          to: toAddresses.join(", "),
+          cc: ccAddresses.length > 0 ? ccAddresses.join(", ") : void 0,
+          replyTo: replyToAddresses.length > 0 ? replyToAddresses.join(", ") : void 0,
+          customHeaders,
+          subject: message.subject,
+          text: message.text,
+          html: finalHtml,
+          attachments: message.attachments,
+          messageIdDomain: config.email.domain
+        }), result = await this.getClient().sendRawEmail({
+          source: fromAddress,
+          destinations: [...toAddresses, ...ccAddresses, ...bccAddresses],
+          rawMessage: raw
+        });
+        return this.handleSuccess(message, result.MessageId);
+      }
+      const body = {};
+      if (finalHtml)
+        body.Html = { Charset: config.email.charset || "UTF-8", Data: finalHtml };
+      if (message.text)
+        body.Text = { Charset: config.email.charset || "UTF-8", Data: message.text };
+      const result = await this.getClient().sendEmail({
+        FromEmailAddress: fromAddress,
+        Destination: {
+          ToAddresses: toAddresses,
+          CcAddresses: ccAddresses,
+          BccAddresses: bccAddresses
+        },
+        ...replyToAddresses.length > 0 ? { ReplyToAddresses: replyToAddresses } : {},
+        Content: {
+          Simple: {
+            Subject: {
+              Charset: config.email.charset || "UTF-8",
+              Data: message.subject
+            },
+            Body: body
+          }
+        }
+      });
+      return this.handleSuccess(message, result.MessageId);
+    } catch (error) {
+      return this.handleError(this.enrichSesError(error), message);
+    }
+  }
+  formatSourceAddress(from) {
+    if (!from.name)
+      return from.address;
+    return `${/[",()<>[\]:;@\\]/.test(from.name) ? `"${from.name.replace(/\\/g, "\\\\").replace(/"/g, "\\\"")}"` : from.name} <${from.address}>`;
+  }
+  enrichSesError(error) {
+    const err = error instanceof Error ? error : Error(String(error)), text = `${err.message} ${err.name ?? ""}`.toLowerCase(), region = config?.services?.ses?.region || "us-east-1";
+    if (text.includes("email address is not verified") || text.includes("not authorized to send") || text.includes("messagerejected") && text.includes("verified")) {
+      err.message = `${err.message}
+
+SES sandbox restriction: the From and (in sandbox) every To address must be verified. Verify identities in the SES console under "Verified identities" (region: ${region}), or request production access to lift the recipient restriction.`;
+      return err;
+    }
+    if (text.includes("signaturedoesnotmatch") || text.includes("invalidclienttokenid") || text.includes("unable to locate credentials") || text.includes("the security token included in the request is invalid")) {
+      err.message = `${err.message}
+
+SES authentication failed. Check AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY (or services.ses.credentials), and confirm the IAM principal has \`ses:SendEmail\` permission for the From identity.`;
+      return err;
+    }
+    if (text.includes("could not be reached") || text.includes("econnrefused") || text.includes("enotfound")) {
+      err.message = `${err.message}
+
+SES endpoint unreachable. The configured region (\`${region}\`) must match the region where the From identity is verified.`;
+      return err;
+    }
+    return err;
+  }
+}
+export default SESDriver;

package/dist/drivers/smtp.js

@@ -0,0 +1,225 @@
+import { Buffer } from "node:buffer";
+import process from "node:process";
+import * as tls from "node:tls";
+import * as net from "node:net";
+import { config } from "@stacksjs/config";
+import { log } from "@stacksjs/logging";
+import { template } from "../template";
+import { buildMimeMessage } from "../mime";
+import { ENVELOPE_ADDRESS, filterStringHeaders } from "../validation";
+import { BaseEmailDriver } from "./base";
+function assertEnvelopeAddress(addr, role) {
+  if (typeof addr !== "string" || !ENVELOPE_ADDRESS.test(addr))
+    throw Error(`[smtp] Refusing to send: ${role} envelope address contains forbidden characters or is malformed: ${JSON.stringify(addr)}`);
+}
+
+export class SMTPDriver extends BaseEmailDriver {
+  static SMTP_TIMEOUT = 30000;
+  name = "smtp";
+  getConfig() {
+    const smtp = config.services?.smtp, env = process.env, host = smtp?.host || env.MAIL_HOST || "127.0.0.1", port = smtp?.port || (env.MAIL_PORT ? Number(env.MAIL_PORT) : void 0) || 587, fromAddress = typeof config.email?.from?.address === "string" ? config.email.from.address : "", username = smtp?.username || env.MAIL_USERNAME || fromAddress || "", localPart = (username.includes("@") ? username.split("@")[0] : username).toUpperCase().replace(/[^A-Z0-9]/g, "_"), password = smtp?.password || env.MAIL_PASSWORD || (localPart ? env[`MAIL_PASSWORD_${localPart}`] : void 0) || "", rawEncryption = smtp?.encryption ?? env.MAIL_ENCRYPTION ?? null;
+    return {
+      host,
+      port,
+      username,
+      password,
+      encryption: rawEncryption === "tls" ? "starttls" : rawEncryption || null
+    };
+  }
+  async send(message, options) {
+    const smtpConfig = this.getConfig();
+    if (!smtpConfig.host || smtpConfig.host === "")
+      throw Error("[SMTP] Host is not configured. Set MAIL_HOST in your .env file.");
+    const logContext = {
+      provider: this.name,
+      to: message.to,
+      subject: message.subject,
+      host: smtpConfig.host,
+      port: smtpConfig.port
+    };
+    log.info("Sending email via SMTP...", logContext);
+    try {
+      this.validateMessage(message);
+      let htmlContent;
+      if (message.template) {
+        const templ = await template(message.template, options);
+        if (templ && "html" in templ)
+          htmlContent = templ.html;
+      }
+      const finalHtml = htmlContent || message.html, fromAddress = message.from?.address || config.email.from?.address || "", fromName = message.from?.name || config.email.from?.name || "", toAddresses = this.formatAddresses(message.to), replyToAddresses = this.formatAddressList(message.replyTo), emailContent = buildMimeMessage({
+        from: fromName ? `${fromName} <${fromAddress}>` : fromAddress,
+        to: toAddresses.join(", "),
+        cc: message.cc ? this.formatAddresses(message.cc).join(", ") : void 0,
+        replyTo: replyToAddresses.length > 0 ? replyToAddresses.join(", ") : void 0,
+        customHeaders: filterStringHeaders(message.headers),
+        subject: message.subject,
+        text: message.text,
+        html: finalHtml,
+        attachments: message.attachments,
+        messageIdDomain: config.email.domain
+      }), messageId = await this.sendViaSMTP(smtpConfig, fromAddress, toAddresses, emailContent);
+      return this.handleSuccess(message, messageId);
+    } catch (error) {
+      return this.handleError(error, message);
+    }
+  }
+  async sendViaSMTP(smtpConfig, from, to, content) {
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        reject(Error(`SMTP connection timed out after ${SMTPDriver.SMTP_TIMEOUT}ms`));
+      }, SMTPDriver.SMTP_TIMEOUT), originalResolve = resolve, originalReject = reject;
+      resolve = (value) => {
+        clearTimeout(timeout);
+        originalResolve(value);
+      };
+      reject = (reason) => {
+        clearTimeout(timeout);
+        originalReject(reason);
+      };
+      let socket, buffer = "";
+      const _currentCommand = "", commandQueue = [], _isProcessing = !1;
+      let completed = !1;
+      const processResponse = (response) => {
+        log.debug(`[SMTP] Server: ${response.trim()}`);
+        if (parseInt(response.substring(0, 3), 10) >= 400) {
+          const error = Error(`SMTP Error: ${response.trim()}`);
+          if (commandQueue.length > 0)
+            commandQueue.shift()?.reject(error);
+          return;
+        }
+        if (commandQueue.length > 0)
+          commandQueue.shift()?.resolve(response);
+      }, sendCommand = (cmd) => {
+        return new Promise((res, rej) => {
+          commandQueue.push({ cmd, resolve: res, reject: rej });
+          log.debug(`[SMTP] Client: ${cmd}`);
+          socket.write(`${cmd}\r
+`);
+        });
+      }, handleData = (data) => {
+        buffer += data.toString();
+        const lines = buffer.split(`\r
+`);
+        buffer = lines.pop() || "";
+        for (const line of lines)
+          if (line.length >= 3) {
+            if (line.length === 3 || line[3] === " ")
+              processResponse(line);
+          }
+      }, runSmtpSession = async () => {
+        try {
+          await new Promise((res, rej) => {
+            commandQueue.push({ cmd: "GREETING", resolve: res, reject: rej });
+          });
+          const _ehloResponse = await sendCommand(`EHLO ${config.email.domain || "localhost"}`);
+          if (smtpConfig.encryption === "starttls" && !(socket instanceof tls.TLSSocket)) {
+            await sendCommand("STARTTLS");
+            const plainSocket = socket;
+            plainSocket.removeAllListeners("data");
+            socket = await new Promise((res, rej) => {
+              const tlsSocket = tls.connect({
+                socket: plainSocket,
+                host: smtpConfig.host,
+                servername: smtpConfig.host
+              }, () => {
+                log.debug("[SMTP] TLS connection established");
+                res(tlsSocket);
+              });
+              tlsSocket.on("error", (err) => {
+                log.error("[SMTP] TLS socket error:", err);
+                rej(err);
+              });
+              tlsSocket.on("data", handleData);
+              tlsSocket.on("close", (hadError) => {
+                log.debug(`[SMTP] TLS socket closed (hadError: ${hadError})`);
+                while (commandQueue.length > 0)
+                  commandQueue.shift()?.reject(Error("TLS connection closed unexpectedly"));
+              });
+            });
+            await sendCommand(`EHLO ${config.email.domain || "localhost"}`);
+          }
+          if (smtpConfig.username && smtpConfig.password) {
+            await sendCommand("AUTH LOGIN");
+            await sendCommand(Buffer.from(smtpConfig.username).toString("base64"));
+            await sendCommand(Buffer.from(smtpConfig.password).toString("base64"));
+          }
+          assertEnvelopeAddress(from, "MAIL FROM");
+          for (const recipient of to)
+            assertEnvelopeAddress(recipient, "RCPT TO");
+          await sendCommand(`MAIL FROM:<${from}>`);
+          for (const recipient of to)
+            await sendCommand(`RCPT TO:<${recipient}>`);
+          await sendCommand("DATA");
+          socket.write(`${content}\r
+.\r
+`);
+          await new Promise((res, rej) => {
+            commandQueue.push({ cmd: "DATA_END", resolve: res, reject: rej });
+          });
+          completed = !0;
+          const messageId = `${Date.now()}.${Math.random().toString(36).substring(2)}@${smtpConfig.host}`;
+          try {
+            socket.write(`QUIT\r
+`);
+          } catch {}
+          socket.end();
+          resolve(messageId);
+        } catch (error) {
+          if (completed) {
+            socket.end();
+            return;
+          }
+          socket.end();
+          reject(error);
+        }
+      };
+      if (smtpConfig.encryption === "ssl")
+        socket = tls.connect({
+          host: smtpConfig.host,
+          port: smtpConfig.port,
+          servername: smtpConfig.host
+        }, () => {
+          log.debug(`[SMTP] TLS connected to ${smtpConfig.host}:${smtpConfig.port}`);
+          runSmtpSession();
+        });
+      else
+        socket = net.connect({
+          host: smtpConfig.host,
+          port: smtpConfig.port
+        }, () => {
+          log.debug(`[SMTP] Connected to ${smtpConfig.host}:${smtpConfig.port}`);
+          runSmtpSession();
+        });
+      socket.on("data", handleData);
+      socket.setTimeout(SMTPDriver.SMTP_TIMEOUT);
+      socket.on("timeout", () => {
+        socket.destroy(Error(`SMTP socket timed out after ${SMTPDriver.SMTP_TIMEOUT}ms`));
+      });
+      socket.on("error", (error) => {
+        if (completed)
+          return;
+        log.error(`[SMTP] Connection error to ${smtpConfig.host}:${smtpConfig.port}:`, error);
+        reject(error);
+      });
+      socket.on("close", (hadError) => {
+        log.debug(`[SMTP] Connection closed (hadError: ${hadError})`);
+        if (completed)
+          return;
+        while (commandQueue.length > 0)
+          commandQueue.shift()?.reject(Error("Connection closed unexpectedly"));
+      });
+    });
+  }
+  formatAddresses(addresses) {
+    if (!addresses)
+      return [];
+    if (typeof addresses === "string")
+      return [addresses];
+    return addresses.map((addr) => {
+      if (typeof addr === "string")
+        return addr;
+      return addr.address;
+    });
+  }
+}
+export default SMTPDriver;

package/dist/email.js

@@ -0,0 +1,198 @@
+import { config } from "@stacksjs/config";
+import { log } from "@stacksjs/logging";
+import { CaptureEmailDriver } from "./drivers/capture";
+import { LogEmailDriver } from "./drivers/log";
+import { MailgunDriver } from "./drivers/mailgun";
+import { MailtrapDriver } from "./drivers/mailtrap";
+import { SendGridDriver } from "./drivers/sendgrid";
+import { SESDriver } from "./drivers/ses";
+import { SMTPDriver } from "./drivers/smtp";
+import { findEmailByIdempotencyKey, recordEmailIdempotency } from "./idempotency";
+import { checkSuppressionFor } from "./suppression";
+
+export class Email {
+  name;
+  subject;
+  to;
+  from;
+  template;
+  handle;
+  onError;
+  onSuccess;
+  constructor(options) {
+    this.name = options.name;
+    this.subject = options.subject;
+    this.to = options.to;
+    this.from = options.from;
+    this.template = options.template;
+    this.handle = options.handle;
+    this.onError = options.onError;
+    this.onSuccess = options.onSuccess;
+  }
+  async renderTemplate() {
+    if (!this.template)
+      return "";
+    try {
+      const { path: p } = await import("@stacksjs/path"), templatePath = p.resourcesPath(`views/emails/${this.template}.html`), file = Bun.file(templatePath);
+      if (await file.exists())
+        return await file.text();
+    } catch {}
+    if (this.template.includes("<"))
+      return this.template;
+    return `<p>${this.template}</p>`;
+  }
+  async send(to) {
+    const target = to ?? this.to, recipients = Array.isArray(target) ? target : target ? [target] : [];
+    if (recipients.length === 0)
+      throw Error("No recipient specified for email");
+    try {
+      await mail.send({
+        to: recipients,
+        from: this.from || {
+          name: config.email.from?.name || "Stacks",
+          address: config.email.from?.address || "no-reply@stacksjs.com"
+        },
+        subject: this.subject,
+        html: await this.renderTemplate()
+      });
+      if (this.onSuccess)
+        this.onSuccess();
+      if (this.handle)
+        return this.handle();
+      return { message: "Email sent" };
+    } catch (error) {
+      if (this.onError)
+        return this.onError(error instanceof Error ? error : Error(String(error)));
+      throw error;
+    }
+  }
+}
+
+export class Mail {
+  drivers = new Map;
+  defaultDriver;
+  constructor(options = {}) {
+    this.defaultDriver = options.defaultDriver || config.email.default || "ses";
+    this.registerDefaultDrivers();
+  }
+  registerDefaultDrivers() {
+    this.drivers.set("log", new LogEmailDriver);
+    this.drivers.set("ses", new SESDriver);
+    this.drivers.set("sendgrid", new SendGridDriver);
+    this.drivers.set("mailgun", new MailgunDriver);
+    this.drivers.set("mailtrap", new MailtrapDriver);
+    this.drivers.set("smtp", new SMTPDriver);
+    this.drivers.set("capture", new CaptureEmailDriver);
+  }
+  async send(message) {
+    const driver = this.drivers.get(this.defaultDriver);
+    if (!driver) {
+      const available = [...this.drivers.keys()].sort().join(", ");
+      throw Error(`Email driver '${this.defaultDriver}' is not registered. Available drivers: [${available}]. Check config.email.default or the MAIL_MAILER environment variable.`);
+    }
+    if (message.idempotencyKey) {
+      const cached = await findEmailByIdempotencyKey(message.idempotencyKey);
+      if (cached)
+        return cached;
+    }
+    const suppressionType = await checkSuppressionForFirstRecipient(message);
+    if (suppressionType)
+      return {
+        success: !1,
+        message: `suppressed:${suppressionType}`,
+        provider: "suppression"
+      };
+    const defaultFrom = {
+      name: config.email.from?.name || "Stacks",
+      address: config.email.from?.address || "no-reply@stacksjs.com"
+    }, result = await driver.send({
+      ...message,
+      from: message.from || defaultFrom
+    });
+    if (message.idempotencyKey)
+      await recordEmailIdempotency(message.idempotencyKey, message, result);
+    return result;
+  }
+  use(driver) {
+    if (!this.drivers.has(driver))
+      throw Error(`Email driver '${driver}' is not available`);
+    return new Mail({ defaultDriver: driver });
+  }
+  async queue(message) {
+    await this.dispatchOrFallback(message, async () => {
+      const { job } = await import("@stacksjs/queue");
+      await job("SendEmail", { message, driver: this.defaultDriver }).onQueue("emails").dispatch();
+    }, { context: "queue" });
+  }
+  async later(delaySeconds, message) {
+    await this.dispatchOrFallback(message, async () => {
+      const { job } = await import("@stacksjs/queue");
+      await job("SendEmail", { message, driver: this.defaultDriver }).onQueue("emails").delay(delaySeconds).dispatch();
+    }, { context: "later", delaySeconds });
+  }
+  async queueOn(queueName, message) {
+    await this.dispatchOrFallback(message, async () => {
+      const { job } = await import("@stacksjs/queue");
+      await job("SendEmail", { message, driver: this.defaultDriver }).onQueue(queueName).dispatch();
+    }, { context: "queueOn", queueName });
+  }
+  async dispatchOrFallback(message, dispatch, logExtra) {
+    try {
+      await dispatch();
+      return;
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+      log.warn("[email] Queue dispatch failed; falling back to synchronous send. " + "Background email pipeline is degraded \u2014 check the queue worker / broker.", { ...logExtra, reason });
+    }
+    await this.send(message);
+  }
+}
+async function checkSuppressionForFirstRecipient(message) {
+  const recipients = collectRecipientAddresses(message);
+  if (recipients.length === 0)
+    return null;
+  for (const addr of recipients) {
+    const matched = await checkSuppressionFor(addr, message.tag);
+    if (matched)
+      return matched;
+  }
+  return null;
+}
+function collectRecipientAddresses(message) {
+  const out = [], pushOne = (v) => {
+    if (typeof v === "string") {
+      out.push(v);
+      return;
+    }
+    if (v && typeof v === "object" && "address" in v && typeof v.address === "string")
+      out.push(v.address);
+  };
+  for (const field of ["to", "cc", "bcc"]) {
+    const v = message[field];
+    if (!v)
+      continue;
+    if (Array.isArray(v))
+      for (const item of v)
+        pushOne(item);
+    else
+      pushOne(v);
+  }
+  return out;
+}
+let _mail;
+function getMail() {
+  if (!_mail) {
+    const driver = config?.email?.default || process.env.MAIL_MAILER || "ses";
+    _mail = new Mail({ defaultDriver: driver });
+  }
+  return _mail;
+}
+export const mail = new Proxy({}, {
+  get(_t, prop) {
+    return getMail()[prop];
+  },
+  set(_t, prop, value) {
+    getMail()[prop] = value;
+    return !0;
+  }
+});