@maestro-js/mail 1.0.0-alpha.26 → 1.0.0-alpha.27

package/dist/index.d.ts

@@ -19,11 +19,22 @@ interface MailAttachment {
     disposition?: string;
     contentId?: string;
 }
-interface MailHeaders {
+type MailHeaders = {
     listUnsubscribePost?: string;
     listUnsubscribe?: string;
     replyTo?: MailAddress;
-}
+    /**
+     * Stable `Message-ID` (e.g. `<abc@your.domain>`) set explicitly so it can be stored and later
+     * reused in a thread's `References`. If omitted, the driver/transport generates one.
+     */
+    messageId?: string;
+    /** Parent message's `Message-ID` — becomes the `In-Reply-To` header. */
+    inReplyTo?: string;
+    /** Ordered chain of `Message-ID`s for the thread — becomes the `References` header. */
+    references?: string | string[];
+} & {
+    [key: string]: string | string[] | MailAddress | undefined;
+};
 interface MailEnvelope {
     to: MailAddress | MailAddress[];
     from?: MailAddress;
@@ -97,6 +108,7 @@ interface SendGrid {
         cc?: EmailData | EmailData[];
         bcc?: EmailData | EmailData[];
         from: EmailData;
+        replyTo?: EmailData;
         subject?: string;
         attachments?: {
             content: string;
@@ -106,6 +118,9 @@ interface SendGrid {
             contentId?: string;
         }[];
         category?: string;
+        headers?: {
+            [key: string]: string;
+        };
         customArgs?: {
             [key: string]: any;
         };
@@ -143,6 +158,7 @@ interface MailTrap {
         cc?: Address[];
         bcc?: Address[];
         from: Address;
+        reply_to?: Address;
         subject: string;
         text?: string;
         html?: string;
@@ -154,6 +170,7 @@ interface MailTrap {
             contentId?: string;
         }[];
         category?: string;
+        headers?: Record<string, string>;
         custom_variables?: Record<string, string | number | boolean>;
     } & ({
         text?: string;
@@ -352,7 +369,10 @@ declare namespace Mail {
     type Content = MailContent;
     /** File attachment with base64-encoded content, filename, optional MIME type and disposition */
     type Attachment = MailAttachment;
-    /** Email headers: `listUnsubscribe`, `listUnsubscribePost`, and `replyTo` */
+    /**
+     * Email headers: well-known `replyTo`, `listUnsubscribe`, `listUnsubscribePost`, the threading
+     * headers `messageId`/`inReplyTo`/`references`, plus arbitrary string header keys.
+     */
     type Headers = MailHeaders;
     /** Complete email message: recipients, subject, content, optional attachments, headers, category, and extras */
     type Envelope = MailEnvelope;

package/dist/index.js

@@ -2,6 +2,30 @@
 import "iso-fns2";
 
 // src/mail-types.ts
+var KNOWN_MAIL_HEADER_KEYS = /* @__PURE__ */ new Set([
+  "listUnsubscribe",
+  "listUnsubscribePost",
+  "replyTo",
+  "messageId",
+  "inReplyTo",
+  "references"
+]);
+function getCustomHeaders(headers) {
+  if (!headers) return {};
+  return Object.fromEntries(
+    Object.entries(headers).filter(([key, value]) => !KNOWN_MAIL_HEADER_KEYS.has(key) && typeof value === "string")
+  );
+}
+function getThreadingHeaders(headers) {
+  if (!headers) return {};
+  const out = {};
+  if (headers.messageId) out["Message-ID"] = headers.messageId;
+  if (headers.inReplyTo) out["In-Reply-To"] = headers.inReplyTo;
+  if (headers.references) {
+    out["References"] = Array.isArray(headers.references) ? headers.references.join(" ") : headers.references;
+  }
+  return out;
+}
 function getEmails(address) {
   const list = Array.isArray(address) ? address : [address];
   return list.map((a) => typeof a === "string" ? a.trim() : a.email.trim());
@@ -25,10 +49,12 @@ function sendGridMailDriver(sendGrid) {
           cc: envelope.cc,
           bcc: envelope.bcc,
           from,
+          replyTo: envelope.headers?.replyTo,
           subject: envelope.subject ?? void 0,
           ...envelope.content,
           attachments: envelope.attachments,
           category: envelope.category ?? void 0,
+          headers: { ...getCustomHeaders(envelope.headers), ...getThreadingHeaders(envelope.headers) },
           customArgs: { ...envelope.extras ?? {}, __extraKeys__: JSON.stringify(Object.keys(envelope.extras ?? {})) }
         },
         false,
@@ -85,10 +111,12 @@ function mailTrapMailDriver(mailTrap) {
         cc: envelope.cc ? convertAddress(envelope.cc) : [],
         bcc: envelope.bcc ? convertAddress(envelope.bcc) : [],
         from: typeof envelope.from === "string" ? { email: envelope.from } : envelope.from,
+        reply_to: envelope.headers?.replyTo ? convertAddress(envelope.headers.replyTo)[0] : void 0,
         subject: envelope.subject ?? "",
         ...envelope.content,
         attachments: envelope.attachments,
         category: envelope.category ?? void 0,
+        headers: { ...getCustomHeaders(envelope.headers), ...getThreadingHeaders(envelope.headers) },
         custom_variables: Object.fromEntries(Object.entries(envelope.extras ?? {}).filter((e) => e[1] != null))
       }),
       {
@@ -165,7 +193,11 @@ function sesMailDriver(ses) {
       text: "text" in envelope.content ? envelope.content.text : void 0,
       html: "html" in envelope.content ? envelope.content.html : void 0,
       replyTo: replyToComposer,
+      messageId: envelope.headers?.messageId,
+      inReplyTo: envelope.headers?.inReplyTo,
+      references: envelope.headers?.references,
       headers: {
+        ...getCustomHeaders(envelope.headers),
         ...envelope.headers?.listUnsubscribe && { "List-Unsubscribe": envelope.headers.listUnsubscribe },
         ...envelope.headers?.listUnsubscribePost && { "List-Unsubscribe-Post": envelope.headers.listUnsubscribePost }
       },

package/package.json

@@ -12,21 +12,21 @@
     "ics": "^3.8.1",
     "iso-fns2": "npm:iso-fns@2.0.0-alpha.26",
     "nodemailer": "^7.0.5",
-    "@maestro-js/helpers": "1.0.0-alpha.26",
-    "@maestro-js/service-registry": "1.0.0-alpha.26"
+    "@maestro-js/helpers": "1.0.0-alpha.27",
+    "@maestro-js/service-registry": "1.0.0-alpha.27"
   },
   "peerDependencies": {
-    "@maestro-js/log": "1.0.0-alpha.26"
+    "@maestro-js/log": "1.0.0-alpha.27"
   },
   "devDependencies": {
     "@react-email/render": "0.0.7",
     "@types/node": "^22.19.11",
     "@types/nodemailer": "^6.4.17",
     "@types/react": "^19.0.0",
-    "@maestro-js/log": "1.0.0-alpha.26",
-    "@maestro-js/queue": "1.0.0-alpha.26"
+    "@maestro-js/log": "1.0.0-alpha.27",
+    "@maestro-js/queue": "1.0.0-alpha.27"
   },
-  "version": "1.0.0-alpha.26",
+  "version": "1.0.0-alpha.27",
   "publishConfig": {
     "access": "public"
   },