@stacksjs/email 0.70.87 → 0.70.90

package/dist/css-inliner.js

@@ -0,0 +1,172 @@
+export function inlineCss(html, options = {}) {
+  const { inline = !0, important = !0 } = options;
+  if (!inline)
+    return html;
+  let working = html;
+  const passthroughBlocks = [];
+  working = working.replace(/<style\b[^>]*\bdata-inline=["']false["'][^>]*>[\s\S]*?<\/style>/gi, (match) => {
+    passthroughBlocks.push(match);
+    return `\x00STX_PASSTHROUGH_${passthroughBlocks.length - 1}\x00`;
+  });
+  const styleBlocks = [];
+  working = working.replace(/<style\b[^>]*>([\s\S]*?)<\/style>/gi, (_match, body) => {
+    styleBlocks.push(body);
+    return "";
+  });
+  if (styleBlocks.length === 0)
+    return restorePassthroughs(working, passthroughBlocks);
+  const inlinableRules = [], leftover = [];
+  for (const body of styleBlocks)
+    for (const rule of splitRules(body)) {
+      const { selector, declarations } = rule;
+      if (!selector || !declarations)
+        continue;
+      if (isInlinable(selector))
+        inlinableRules.push({ selector, decls: declarations });
+      else
+        leftover.push(`${selector} { ${declarations.map((d) => `${d.prop}: ${d.value};`).join(" ")} }`);
+    }
+  for (const { selector, decls } of inlinableRules)
+    working = applyRule(working, selector, decls, important);
+  if (leftover.length > 0) {
+    const styleTag = `<style>
+${leftover.join(`
+`)}
+</style>`;
+    working = /<\/head>/i.test(working) ? working.replace(/<\/head>/i, `${styleTag}
+</head>`) : `${styleTag}
+${working}`;
+  }
+  return restorePassthroughs(working, passthroughBlocks);
+}
+function restorePassthroughs(html, blocks) {
+  if (blocks.length === 0)
+    return html;
+  return html.replace(/\u0000STX_PASSTHROUGH_(\d+)\u0000/g, (_match, idx) => {
+    return blocks[Number.parseInt(idx, 10)] ?? "";
+  });
+}
+function splitRules(body) {
+  const cleaned = body.replace(/\/\*[\s\S]*?\*\//g, ""), rules = [];
+  let i = 0;
+  while (i < cleaned.length) {
+    const open = cleaned.indexOf("{", i);
+    if (open === -1)
+      break;
+    const selector = cleaned.slice(i, open).trim();
+    let depth = 1, j = open + 1;
+    while (j < cleaned.length && depth > 0) {
+      const ch = cleaned[j];
+      if (ch === "{")
+        depth++;
+      else if (ch === "}")
+        depth--;
+      j++;
+    }
+    const inner = cleaned.slice(open + 1, j - 1);
+    if (selector.startsWith("@") || inner.includes("{"))
+      rules.push({
+        selector: selector || "@unknown",
+        declarations: parseDeclarationsLoose(inner)
+      });
+    else
+      rules.push({ selector, declarations: parseDeclarations(inner) });
+    i = j;
+  }
+  return rules;
+}
+function parseDeclarations(body) {
+  return body.split(";").map((decl) => decl.trim()).filter(Boolean).map((decl) => {
+    const colon = decl.indexOf(":");
+    if (colon === -1)
+      return null;
+    return {
+      prop: decl.slice(0, colon).trim(),
+      value: decl.slice(colon + 1).trim()
+    };
+  }).filter((d) => d !== null);
+}
+function parseDeclarationsLoose(body) {
+  return [{ prop: "", value: body.trim() }];
+}
+function isInlinable(selector) {
+  if (!selector)
+    return !1;
+  if (selector.includes(","))
+    return selector.split(",").every((s) => isInlinable(s.trim()));
+  if (selector.startsWith("@"))
+    return !1;
+  if (/[\s>+~:[]/.test(selector))
+    return !1;
+  return /^[a-z][a-z0-9-]*?$|^([a-z][a-z0-9-]*)?([.#][a-z][\w-]*)+$/i.test(selector);
+}
+function applyRule(html, selector, decls, important) {
+  if (selector.includes(",")) {
+    let acc = html;
+    for (const branch of selector.split(","))
+      acc = applyRule(acc, branch.trim(), decls, important);
+    return acc;
+  }
+  const { tag, classes, ids } = parseSimpleSelector(selector), tagRe = new RegExp(`<(${tag ?? "[a-z][a-z0-9-]*"})\\b([^>]*?)(/?)>`, "gi"), newDeclString = decls.map((d) => `${d.prop}:${d.value}${important && !/!important\b/i.test(d.value) ? " !important" : ""};`).join("");
+  return html.replace(tagRe, (match, _tagName, attrs) => {
+    if (!elementMatches(attrs, classes, ids))
+      return match;
+    return mergeStyleAttr(match, attrs, newDeclString);
+  });
+}
+function parseSimpleSelector(selector) {
+  let tag = null;
+  const classes = [], ids = [];
+  let i = 0;
+  while (i < selector.length && /[a-z0-9-]/i.test(selector[i])) {
+    tag = (tag ?? "") + selector[i];
+    i++;
+  }
+  if (tag === "")
+    tag = null;
+  while (i < selector.length) {
+    const ch = selector[i];
+    if (ch !== "." && ch !== "#")
+      break;
+    let j = i + 1;
+    while (j < selector.length && /[\w-]/.test(selector[j]))
+      j++;
+    const name = selector.slice(i + 1, j);
+    if (ch === ".")
+      classes.push(name);
+    else
+      ids.push(name);
+    i = j;
+  }
+  return { tag, classes, ids };
+}
+function elementMatches(attrs, classes, ids) {
+  if (classes.length > 0) {
+    const classMatch = attrs.match(/\bclass\s*=\s*["']([^"']*)["']/i);
+    if (!classMatch)
+      return !1;
+    const present = classMatch[1].split(/\s+/).filter(Boolean);
+    if (!classes.every((c) => present.includes(c)))
+      return !1;
+  }
+  if (ids.length > 0) {
+    const idMatch = attrs.match(/\bid\s*=\s*["']([^"']+)["']/i);
+    if (!idMatch)
+      return !1;
+    if (!ids.every((id) => idMatch[1] === id))
+      return !1;
+  }
+  return !0;
+}
+function mergeStyleAttr(originalTag, attrs, newDeclString) {
+  const styleMatch = attrs.match(/\bstyle\s*=\s*["']([^"']*)["']/i);
+  if (styleMatch) {
+    const existing = styleMatch[1].trim(), merged = `${newDeclString}${existing}${existing.endsWith(";") || existing === "" ? "" : ";"}`, replaced = attrs.replace(styleMatch[0], `style="${merged}"`);
+    return originalTag.replace(attrs, replaced);
+  }
+  const extra = ` style="${newDeclString}"`;
+  return originalTag.replace(/(\s*\/?)>$/, `${extra}$1>`);
+}
+export function shouldInlineByDefault() {
+  return (globalThis.process?.env?.APP_ENV ?? globalThis.process?.env?.NODE_ENV ?? "").toLowerCase() === "production";
+}

package/dist/drivers/base.js

@@ -0,0 +1,128 @@
+import { config as appConfig } from "@stacksjs/config";
+import { log } from "@stacksjs/logging";
+import { assertEnvelopeAddress, assertHeaderSafeSubject } from "../validation";
+
+export class BaseEmailDriver {
+  config;
+  constructor(config) {
+    this.config = {
+      maxRetries: config?.maxRetries || 3,
+      retryTimeout: config?.retryTimeout || 1000,
+      ...config
+    };
+  }
+  configure(config) {
+    this.config = { ...this.config, ...config };
+  }
+  validateMessage(message) {
+    if (!message.from?.address && !appConfig.email.from?.address)
+      throw Error("Email sender address is required either in message or config");
+    if (!message.to || Array.isArray(message.to) && message.to.length === 0)
+      throw Error("At least one recipient is required");
+    if (!message.subject)
+      throw Error("Email subject is required");
+    assertHeaderSafeSubject(message.subject);
+    const checkAddress = (raw, role) => {
+      if (!raw)
+        return;
+      assertEnvelopeAddress(raw, role);
+    }, flatten = (v) => {
+      if (!v)
+        return [];
+      if (typeof v === "string")
+        return [v];
+      if (Array.isArray(v))
+        return v.flatMap((item) => typeof item === "string" ? [item] : item?.address ? [item.address] : []);
+      const obj = v;
+      return obj.address ? [obj.address] : [];
+    };
+    if (message.from)
+      checkAddress(message.from.address, "from");
+    for (const addr of flatten(message.to))
+      checkAddress(addr, "to");
+    for (const addr of flatten(message.cc))
+      checkAddress(addr, "cc");
+    for (const addr of flatten(message.bcc))
+      checkAddress(addr, "bcc");
+    return !0;
+  }
+  formatAddresses(addresses) {
+    if (!addresses)
+      return [];
+    if (typeof addresses === "string")
+      return [addresses];
+    return addresses.map((_addr) => {
+      if (typeof _addr === "string")
+        return _addr;
+      if (!_addr.name)
+        return _addr.address;
+      return `${/[",()<>[\]:;@\\]/.test(_addr.name) ? `"${_addr.name.replace(/\\/g, "\\\\").replace(/"/g, "\\\"")}"` : _addr.name} <${_addr.address}>`;
+    });
+  }
+  formatAddressList(value) {
+    if (!value)
+      return [];
+    if (Array.isArray(value))
+      return this.formatAddresses(value);
+    if (typeof value === "string")
+      return this.formatAddresses(value);
+    return this.formatAddresses([value]);
+  }
+  async handleError(error, message) {
+    const err = error instanceof Error ? error : Error(String(error));
+    log.error(`[${this.name}] Email sending failed`, {
+      error: err.message,
+      stack: err.stack,
+      to: message.to,
+      subject: message.subject
+    });
+    let result = {
+      message: `Email sending failed: ${err.message}`,
+      success: !1,
+      provider: this.name
+    };
+    if (message.onError) {
+      const customResult = message.onError(err), handlerResult = customResult instanceof Promise ? await customResult : customResult;
+      result = {
+        ...result,
+        ...handlerResult,
+        success: !1,
+        provider: this.name
+      };
+    }
+    return result;
+  }
+  async handleSuccess(message, messageId) {
+    let result = {
+      message: "Email sent successfully",
+      success: !0,
+      provider: this.name,
+      messageId
+    };
+    try {
+      if (message.handle) {
+        const customResult = message.handle(), handlerResult = customResult instanceof Promise ? await customResult : customResult;
+        result = {
+          ...result,
+          ...handlerResult,
+          success: !0,
+          provider: this.name,
+          messageId
+        };
+      }
+      if (message.onSuccess) {
+        const successResult = message.onSuccess(), handlerResult = successResult instanceof Promise ? await successResult : successResult;
+        result = {
+          ...result,
+          ...handlerResult,
+          success: !0,
+          provider: this.name,
+          messageId
+        };
+      }
+    } catch (error) {
+      return this.handleError(error, message);
+    }
+    return result;
+  }
+}

package/dist/drivers/capture.js

@@ -0,0 +1,30 @@
+import { BaseEmailDriver } from "./base";
+const captured = [];
+let nextId = 1;
+
+export class CaptureEmailDriver extends BaseEmailDriver {
+  name = "capture";
+  async send(message, _options) {
+    try {
+      this.validateMessage(message);
+      const sentAt = new Date, messageId = `capture-${sentAt.getTime()}-${nextId++}`;
+      captured.push({ ...message, sentAt, messageId });
+      return this.handleSuccess(message, messageId);
+    } catch (error) {
+      return this.handleError(error, message);
+    }
+  }
+  static all() {
+    return captured;
+  }
+  static last() {
+    return captured[captured.length - 1];
+  }
+  static count() {
+    return captured.length;
+  }
+  static clear() {
+    captured.length = 0;
+    nextId = 1;
+  }
+}

package/dist/drivers/index.js

@@ -0,0 +1,6 @@
+export * as capture from "./capture";
+export * as log from "./log";
+export * as mailgun from "./mailgun";
+export * as mailtrap from "./mailtrap";
+export * as sendgrid from "./sendgrid";
+export * as ses from "./ses";

package/dist/drivers/log.js

@@ -0,0 +1,81 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { log } from "@stacksjs/logging";
+import { template } from "../template";
+import { BaseEmailDriver } from "./base";
+const STORE_LIMIT = 100, captured = [];
+
+export class LogEmailDriver extends BaseEmailDriver {
+  name = "log";
+  resolveDir() {
+    const fromEnv = process.env.LOG_MAIL_DIR;
+    if (fromEnv)
+      return resolve(fromEnv);
+    return resolve(join(import.meta.dir, "..", "..", "..", "..", "..", "logs", "mail"));
+  }
+  async send(message, options) {
+    try {
+      this.validateMessage(message);
+      let rendered;
+      if (message.template) {
+        const t = await template(message.template, options);
+        if (t)
+          rendered = { html: t.html, text: t.text };
+      }
+      const html = rendered?.html ?? message.html, text = rendered?.text ?? message.text, stamp = new Date, safeSubject = (message.subject || "no-subject").replace(/[^\w.-]+/g, "-").slice(0, 60), filename = `${stamp.toISOString().replace(/[:.]/g, "-")}-${safeSubject}.html`, dir = this.resolveDir();
+      try {
+        await mkdir(dir, { recursive: !0 });
+        const filePath = join(dir, filename), body = html ? html : text ? `<pre>${escapeHtml(text)}</pre>` : "<em>(empty body)</em>", headerBlock = renderHeader({ stamp, message });
+        await writeFile(filePath, `${headerBlock}
+${body}
+`);
+      } catch (err) {
+        log.warn(`[email:log] could not write inspection file: ${err.message}`);
+      }
+      const flatTo = Array.isArray(message.to) ? message.to.map((t) => typeof t === "string" ? t : t.address).join(", ") : typeof message.to === "string" ? message.to : message.to.address;
+      log.info(`[email:log] would send \u2192 ${flatTo} :: ${message.subject}`);
+      captured.push({ ...message, sentAt: stamp, rendered });
+      if (captured.length > STORE_LIMIT)
+        captured.splice(0, captured.length - STORE_LIMIT);
+      return this.handleSuccess(message, `log-${stamp.getTime()}`);
+    } catch (error) {
+      return this.handleError(error, message);
+    }
+  }
+  static captured() {
+    return captured;
+  }
+  static reset() {
+    captured.length = 0;
+  }
+}
+function renderHeader({ stamp, message }) {
+  return [
+    "<!--",
+    `  Captured by @stacksjs/email log driver at ${stamp.toISOString()}`,
+    `  From:    ${formatAddr(message.from)}`,
+    `  To:      ${formatList(message.to)}`,
+    message.cc ? `  Cc:      ${formatList(message.cc)}` : null,
+    message.bcc ? `  Bcc:     ${formatList(message.bcc)}` : null,
+    `  Subject: ${message.subject}`,
+    "-->"
+  ].filter(Boolean).join(`
+`);
+}
+function formatAddr(v) {
+  if (!v)
+    return "";
+  if (typeof v === "string")
+    return v;
+  const o = v;
+  return o.name ? `${o.name} <${o.address ?? ""}>` : o.address ?? "";
+}
+function formatList(v) {
+  if (Array.isArray(v))
+    return v.map(formatAddr).join(", ");
+  return formatAddr(v);
+}
+function escapeHtml(s) {
+  return s.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+}
+export default LogEmailDriver;

package/dist/drivers/mailgun.js

@@ -0,0 +1,127 @@
+import { Buffer } from "node:buffer";
+import { config } from "@stacksjs/config";
+import { log } from "@stacksjs/logging";
+import { template } from "../template";
+import { BaseEmailDriver } from "./base";
+
+export class MailgunDriver extends BaseEmailDriver {
+  name = "mailgun";
+  apiKey = null;
+  domain = null;
+  endpoint = null;
+  getConfig() {
+    if (!this.apiKey || !this.domain || !this.endpoint) {
+      this.apiKey = config.services.mailgun?.apiKey ?? "";
+      this.domain = config.services.mailgun?.domain ?? "";
+      this.endpoint = config.services.mailgun?.endpoint ?? "api.mailgun.net";
+    }
+    return {
+      apiKey: this.apiKey,
+      domain: this.domain,
+      endpoint: this.endpoint
+    };
+  }
+  async send(message, options) {
+    const { domain } = this.getConfig(), logContext = {
+      provider: this.name,
+      to: message.to,
+      subject: message.subject,
+      domain
+    };
+    log.info("Sending email via Mailgun...", 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, formData = new FormData, fromAddress = {
+        address: message.from?.address || config.email.from?.address || "",
+        name: message.from?.name || config.email.from?.name
+      };
+      formData.append("from", this.formatMailgunAddress(fromAddress));
+      this.formatMailgunAddresses(message.to).forEach((to) => formData.append("to", to));
+      if (message.cc)
+        this.formatMailgunAddresses(message.cc).forEach((cc) => formData.append("cc", cc));
+      if (message.bcc)
+        this.formatMailgunAddresses(message.bcc).forEach((bcc) => formData.append("bcc", bcc));
+      formData.append("subject", message.subject);
+      if (message.replyTo) {
+        const formatted = this.formatMailgunAddresses(Array.isArray(message.replyTo) || typeof message.replyTo === "string" ? message.replyTo : [message.replyTo]);
+        if (formatted.length > 0)
+          formData.append("h:Reply-To", formatted.join(", "));
+      }
+      if (message.headers) {
+        for (const [k, v] of Object.entries(message.headers))
+          if (typeof v === "string")
+            formData.append(`h:${k}`, v);
+      }
+      if (finalHtml)
+        formData.append("html", finalHtml);
+      if (message.text)
+        formData.append("text", message.text);
+      if (message.attachments)
+        message.attachments.forEach((attachment) => {
+          const content = typeof attachment.content === "string" ? attachment.content : this.arrayBufferToBase64(attachment.content);
+          formData.append("attachment", new Blob([content], { type: attachment.contentType }), attachment.filename);
+        });
+      const response = await this.sendWithRetry(formData);
+      return this.handleSuccess(message, response.id);
+    } catch (error) {
+      return this.handleError(error, message);
+    }
+  }
+  formatMailgunAddress(address) {
+    return address.name ? `${address.name} <${address.address}>` : address.address;
+  }
+  formatMailgunAddresses(addresses) {
+    if (!addresses)
+      return [];
+    if (typeof addresses === "string")
+      return [addresses];
+    return addresses.map((_addr) => {
+      if (typeof _addr === "string")
+        return _addr;
+      if (!_addr.name)
+        return _addr.address;
+      return `${/[",()<>[\]:;@\\]/.test(_addr.name) ? `"${_addr.name.replace(/\\/g, "\\\\").replace(/"/g, "\\\"")}"` : _addr.name} <${_addr.address}>`;
+    });
+  }
+  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(formData, attempt = 1) {
+    const { apiKey, domain, endpoint } = this.getConfig(), url = `https://${endpoint}/v3/${domain}/messages`, auth = Buffer.from(`api:${apiKey}`).toString("base64");
+    try {
+      const response = await fetch(url, {
+        method: "POST",
+        headers: {
+          Authorization: `Basic ${auth}`
+        },
+        body: formData
+      });
+      if (!response.ok) {
+        const errorData = await response.json();
+        throw Error(`Mailgun API error: ${response.status} - ${JSON.stringify(errorData)}`);
+      }
+      const data = await response.json();
+      log.info(`[${this.name}] Email sent successfully`, { attempt, messageId: data.id });
+      return data;
+    } catch (error) {
+      if (attempt < (config.services.mailgun?.maxRetries ?? 3)) {
+        const retryTimeout = config.services.mailgun?.retryTimeout ?? 1000;
+        log.warn(`[${this.name}] Email send failed, retrying (${attempt}/${config.services.mailgun?.maxRetries ?? 3})`);
+        await new Promise((resolve) => setTimeout(resolve, retryTimeout));
+        return this.sendWithRetry(formData, attempt + 1);
+      }
+      throw error;
+    }
+  }
+}
+export default MailgunDriver;

package/dist/drivers/mailtrap.js

@@ -0,0 +1,129 @@
+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 MailtrapDriver extends BaseEmailDriver {
+  name = "mailtrap";
+  host = null;
+  token = null;
+  inboxId = null;
+  getConfig() {
+    if (this.host === null || this.token === null || this.inboxId === null) {
+      this.host = config.services.mailtrap?.host ?? "https://sandbox.api.mailtrap.io/api/send";
+      this.token = config.services.mailtrap?.token ?? "";
+      this.inboxId = config.services.mailtrap?.inboxId ? Number(config.services.mailtrap.inboxId) : void 0;
+    }
+    return {
+      host: this.host,
+      token: this.token,
+      inboxId: this.inboxId
+    };
+  }
+  async send(message, options) {
+    const { inboxId } = this.getConfig(), logContext = {
+      provider: this.name,
+      to: message.to,
+      subject: message.subject,
+      inboxId
+    };
+    log.info("Sending email via Mailtrap...", logContext);
+    try {
+      this.validateMessage(message);
+      let templ;
+      if (message.template)
+        templ = await template(message.template, options);
+      const htmlContent = templ?.html || message.html, replyTo = this.firstMailtrapAddress(message.replyTo), customHeaders = filterStringHeaders(message.headers), mailtrapPayload = {
+        from: {
+          email: message.from?.address || config.email.from?.address || "",
+          name: message.from?.name || config.email.from?.name
+        },
+        to: this.formatMailtrapAddresses(message.to),
+        ...message.cc && { cc: this.formatMailtrapAddresses(message.cc) },
+        ...message.bcc && { bcc: this.formatMailtrapAddresses(message.bcc) },
+        ...replyTo ? { reply_to: replyTo } : {},
+        ...customHeaders ? { headers: customHeaders } : {},
+        subject: message.subject,
+        ...htmlContent && { html: htmlContent },
+        ...message.text && { text: message.text },
+        ...message.attachments && {
+          attachments: message.attachments.map((attachment) => ({
+            filename: attachment.filename,
+            content: typeof attachment.content === "string" ? attachment.content : this.arrayBufferToBase64(attachment.content),
+            type: attachment.contentType || "application/octet-stream"
+          }))
+        }
+      }, response = await this.sendWithRetry(mailtrapPayload);
+      return this.handleSuccess(message, response.message_ids?.[0]);
+    } catch (error) {
+      return this.handleError(error, message);
+    }
+  }
+  formatMailtrapAddresses(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 } };
+    });
+  }
+  firstMailtrapAddress(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) {
+    const { host, token, inboxId } = this.getConfig();
+    if (!inboxId)
+      throw Error("Mailtrap inbox ID is required but not provided. Please set MAILTRAP_INBOX_ID in your environment variables.");
+    const endpoint = `${host}/${inboxId}`;
+    try {
+      const response = await fetch(endpoint, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${token}`,
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify(payload)
+      });
+      if (!response.ok) {
+        const errorData = await response.json();
+        throw Error(`Mailtrap API error: ${response.status} - ${JSON.stringify(errorData)}`);
+      }
+      const data = await response.json();
+      log.info(`[${this.name}] Email sent successfully`, { attempt, messageId: data.message_ids?.[0] });
+      return data;
+    } catch (error) {
+      if (attempt < (config.services.mailtrap?.maxRetries ?? 3)) {
+        const retryTimeout = config.services.mailtrap?.retryTimeout ?? 1000;
+        log.warn(`[${this.name}] Email send failed, retrying (${attempt}/${config.services.mailtrap?.maxRetries ?? 3})`);
+        await new Promise((resolve) => setTimeout(resolve, retryTimeout));
+        return this.sendWithRetry(payload, attempt + 1);
+      }
+      throw error;
+    }
+  }
+}
+export default MailtrapDriver;