postal-mime 2.7.1 → 2.7.3

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [2.7.3](https://github.com/postalsys/postal-mime/compare/v2.7.2...v2.7.3) (2026-01-09)
+
+
+### Bug Fixes
+
+* correct TypeScript type definitions to match implementation ([b225d7c](https://github.com/postalsys/postal-mime/commit/b225d7cca422cb9bc3ab5301e94c4c0bef9a69e2))
+
+## [2.7.2](https://github.com/postalsys/postal-mime/compare/v2.7.1...v2.7.2) (2026-01-08)
+
+
+### Bug Fixes
+
+* add null checks for contentType.parsed access ([ad8f4c6](https://github.com/postalsys/postal-mime/commit/ad8f4c62e0972fd0244859ee5a5184b2cac26395))
+* improve RFC compliance for MIME parsing ([e004c3a](https://github.com/postalsys/postal-mime/commit/e004c3acb29d72ed7eaf1b0b66351cf8b82b970d))
+
 ## [2.7.1](https://github.com/postalsys/postal-mime/compare/v2.7.0...v2.7.1) (2025-12-22)
 
 

package/README.md

@@ -1,6 +1,6 @@
 # postal-mime
 
-**postal-mime** is an email parsing library that runs in browser environments (including Web Workers) and serverless functions (like Cloudflare Email Workers). It takes in a raw email message (RFC822 format) and outputs a structured object containing headers, recipients, attachments, and more.
+**postal-mime** is an email parsing library for Node.js, browsers (including Web Workers), and serverless environments (like Cloudflare Email Workers). It takes in a raw email message (RFC822 format) and outputs a structured object containing headers, recipients, attachments, and more.
 
 > [!TIP]
 > PostalMime is developed by the makers of [EmailEngine](https://emailengine.app/?utm_source=github&utm_campaign=imapflow&utm_medium=readme-link)—a self-hosted email gateway that provides a REST API for IMAP and SMTP servers and sends webhooks whenever something changes in registered accounts.
@@ -243,7 +243,7 @@ if (email.from && isMailbox(email.from)) {
 PostalMime.parse(email, options) -> Promise<Email>
 ```
 
--   **email**: An RFC822 formatted email. This can be a `string`, `ArrayBuffer/Uint8Array`, `Blob` (browser only), `Buffer` (Node.js), or a [ReadableStream](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream).
+-   **email**: An RFC822 formatted email. This can be a `string`, `ArrayBuffer/Uint8Array`, `Blob`, `Buffer` (Node.js), or a [ReadableStream](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream).
 -   **options**: Optional configuration object:
     -   **rfc822Attachments** (boolean, default: `false`): Treat `message/rfc822` attachments without a Content-Disposition as attachments.
     -   **forceRfc822Attachments** (boolean, default: `false`): Treat _all_ `message/rfc822` parts as attachments.
@@ -419,6 +419,6 @@ console.log(decoded); // Hello, エポスカード
 
 ## License
 
-&copy; 2021–2025 Andris Reinman
+&copy; 2021–2026 Andris Reinman
 
 `postal-mime` is licensed under the **MIT No Attribution license**.

package/dist/mime-node.cjs

@@ -54,8 +54,10 @@ class MimeNode {
     this.state = "header";
     this.headerLines = [];
     this.headerSize = 0;
+    const parentMultipartType = this.options.parentMultipartType || null;
+    const defaultContentType = parentMultipartType === "digest" ? "message/rfc822" : "text/plain";
     this.contentType = {
-      value: "text/plain",
+      value: defaultContentType,
       default: true
     };
     this.contentTransferEncoding = {
@@ -100,7 +102,51 @@ class MimeNode {
       await childNode.finalize();
     }
   }
+  // Strip RFC 822 comments (parenthesized text) from structured header values
+  stripComments(str) {
+    let result = "";
+    let depth = 0;
+    let escaped = false;
+    let inQuote = false;
+    for (let i = 0; i < str.length; i++) {
+      const chr = str.charAt(i);
+      if (escaped) {
+        if (depth === 0) {
+          result += chr;
+        }
+        escaped = false;
+        continue;
+      }
+      if (chr === "\\") {
+        escaped = true;
+        if (depth === 0) {
+          result += chr;
+        }
+        continue;
+      }
+      if (chr === '"' && depth === 0) {
+        inQuote = !inQuote;
+        result += chr;
+        continue;
+      }
+      if (!inQuote) {
+        if (chr === "(") {
+          depth++;
+          continue;
+        }
+        if (chr === ")" && depth > 0) {
+          depth--;
+          continue;
+        }
+      }
+      if (depth === 0) {
+        result += chr;
+      }
+    }
+    return result;
+  }
   parseStructuredHeader(str) {
+    str = this.stripComments(str);
     let response = {
       value: false,
       params: {}

package/dist/postal-mime.cjs

@@ -69,21 +69,33 @@ class PostalMime {
     if (boundaries.length && line.length > 2 && line[0] === 45 && line[1] === 45) {
       for (let i = boundaries.length - 1; i >= 0; i--) {
         let boundary = boundaries[i];
-        if (line.length !== boundary.value.length + 2 && line.length !== boundary.value.length + 4) {
+        if (line.length < boundary.value.length + 2) {
           continue;
         }
-        let isTerminator = line.length === boundary.value.length + 4;
-        if (isTerminator && (line[line.length - 2] !== 45 || line[line.length - 1] !== 45)) {
+        let boundaryMatches = true;
+        for (let j = 0; j < boundary.value.length; j++) {
+          if (line[j + 2] !== boundary.value[j]) {
+            boundaryMatches = false;
+            break;
+          }
+        }
+        if (!boundaryMatches) {
           continue;
         }
-        let boudaryMatches = true;
-        for (let i2 = 0; i2 < boundary.value.length; i2++) {
-          if (line[i2 + 2] !== boundary.value[i2]) {
-            boudaryMatches = false;
+        let boundaryEnd = boundary.value.length + 2;
+        let isTerminator = false;
+        if (line.length >= boundary.value.length + 4 && line[boundary.value.length + 2] === 45 && line[boundary.value.length + 3] === 45) {
+          isTerminator = true;
+          boundaryEnd = boundary.value.length + 4;
+        }
+        let hasValidTrailing = true;
+        for (let j = boundaryEnd; j < line.length; j++) {
+          if (line[j] !== 32 && line[j] !== 9) {
+            hasValidTrailing = false;
             break;
           }
         }
-        if (!boudaryMatches) {
+        if (!hasValidTrailing) {
           continue;
         }
         if (isTerminator) {
@@ -94,6 +106,7 @@ class PostalMime {
           this.currentNode = new import_mime_node.default({
             postalMime: this,
             parentNode: boundary.node,
+            parentMultipartType: boundary.node.contentType.multipart,
             ...this.mimeOptions
           });
         }
@@ -286,11 +299,11 @@ class PostalMime {
     this.textContent = textContent;
   }
   isInlineTextNode(node) {
-    var _a, _b;
+    var _a, _b, _c;
     if (((_b = (_a = node.contentDisposition) == null ? void 0 : _a.parsed) == null ? void 0 : _b.value) === "attachment") {
       return false;
     }
-    switch (node.contentType.parsed.value) {
+    switch ((_c = node.contentType.parsed) == null ? void 0 : _c.value) {
       case "text/html":
       case "text/plain":
         return true;
@@ -301,11 +314,11 @@ class PostalMime {
     }
   }
   isInlineMessageRfc822(node) {
-    var _a, _b;
-    if (node.contentType.parsed.value !== "message/rfc822") {
+    var _a, _b, _c;
+    if (((_a = node.contentType.parsed) == null ? void 0 : _a.value) !== "message/rfc822") {
       return false;
     }
-    let disposition = ((_b = (_a = node.contentDisposition) == null ? void 0 : _a.parsed) == null ? void 0 : _b.value) || (this.options.rfc822Attachments ? "attachment" : "inline");
+    let disposition = ((_c = (_b = node.contentDisposition) == null ? void 0 : _b.parsed) == null ? void 0 : _c.value) || (this.options.rfc822Attachments ? "attachment" : "inline");
     return disposition === "inline";
   }
   // Check if this is a specially crafted report email where message/rfc822 content should not be inlined
@@ -316,7 +329,7 @@ class PostalMime {
     let forceRfc822Attachments = false;
     let walk = (node) => {
       if (!node.contentType.multipart) {
-        if (["message/delivery-status", "message/feedback-report"].includes(node.contentType.parsed.value)) {
+        if (node.contentType.parsed && ["message/delivery-status", "message/feedback-report"].includes(node.contentType.parsed.value)) {
           forceRfc822Attachments = true;
         }
       }

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "postal-mime",
-    "version": "2.7.1",
-    "description": "Email parser for browser environments",
+    "version": "2.7.3",
+    "description": "Email parser for Node.js and browser environments",
     "main": "./dist/postal-mime.cjs",
     "module": "./src/postal-mime.js",
     "exports": {

package/postal-mime.d.ts

@@ -1,8 +1,9 @@
 export type RawEmail = string | ArrayBuffer | Uint8Array | Blob | Buffer | ReadableStream;
 
 export type Header = {
+    /** Lowercase header name */
     key: string;
-    originalKey: string;
+    /** Header value */
     value: string;
 };
 
@@ -35,7 +36,7 @@ export type Attachment = {
     description?: string;
     contentId?: string;
     method?: string;
-    content: ArrayBuffer | Uint8Array | string;
+    content: ArrayBuffer | string;
     encoding?: "base64" | "utf8";
 };
 

package/src/mime-node.js

@@ -30,8 +30,12 @@ export default class MimeNode {
         this.headerLines = [];
         this.headerSize = 0;
 
+        // RFC 2046 Section 5.1.5: multipart/digest defaults to message/rfc822
+        const parentMultipartType = this.options.parentMultipartType || null;
+        const defaultContentType = parentMultipartType === 'digest' ? 'message/rfc822' : 'text/plain';
+
         this.contentType = {
-            value: 'text/plain',
+            value: defaultContentType,
             default: true
         };
 
@@ -90,7 +94,61 @@ export default class MimeNode {
         }
     }
 
+    // Strip RFC 822 comments (parenthesized text) from structured header values
+    stripComments(str) {
+        let result = '';
+        let depth = 0;
+        let escaped = false;
+        let inQuote = false;
+
+        for (let i = 0; i < str.length; i++) {
+            const chr = str.charAt(i);
+
+            if (escaped) {
+                if (depth === 0) {
+                    result += chr;
+                }
+                escaped = false;
+                continue;
+            }
+
+            if (chr === '\\') {
+                escaped = true;
+                if (depth === 0) {
+                    result += chr;
+                }
+                continue;
+            }
+
+            if (chr === '"' && depth === 0) {
+                inQuote = !inQuote;
+                result += chr;
+                continue;
+            }
+
+            if (!inQuote) {
+                if (chr === '(') {
+                    depth++;
+                    continue;
+                }
+                if (chr === ')' && depth > 0) {
+                    depth--;
+                    continue;
+                }
+            }
+
+            if (depth === 0) {
+                result += chr;
+            }
+        }
+
+        return result;
+    }
+
     parseStructuredHeader(str) {
+        // Strip RFC 822 comments before parsing
+        str = this.stripComments(str);
+
         let response = {
             value: false,
             params: {}

package/src/postal-mime.js

@@ -55,24 +55,43 @@ export default class PostalMime {
             for (let i = boundaries.length - 1; i >= 0; i--) {
                 let boundary = boundaries[i];
 
-                if (line.length !== boundary.value.length + 2 && line.length !== boundary.value.length + 4) {
+                // Line must be at least long enough for "--" + boundary
+                if (line.length < boundary.value.length + 2) {
                     continue;
                 }
 
-                let isTerminator = line.length === boundary.value.length + 4;
-
-                if (isTerminator && (line[line.length - 2] !== 0x2d || line[line.length - 1] !== 0x2d)) {
+                // Check if boundary value matches
+                let boundaryMatches = true;
+                for (let j = 0; j < boundary.value.length; j++) {
+                    if (line[j + 2] !== boundary.value[j]) {
+                        boundaryMatches = false;
+                        break;
+                    }
+                }
+                if (!boundaryMatches) {
                     continue;
                 }
 
-                let boudaryMatches = true;
-                for (let i = 0; i < boundary.value.length; i++) {
-                    if (line[i + 2] !== boundary.value[i]) {
-                        boudaryMatches = false;
+                // Check for terminator (-- after boundary) and determine where boundary ends
+                let boundaryEnd = boundary.value.length + 2;
+                let isTerminator = false;
+
+                if (line.length >= boundary.value.length + 4 &&
+                    line[boundary.value.length + 2] === 0x2d &&
+                    line[boundary.value.length + 3] === 0x2d) {
+                    isTerminator = true;
+                    boundaryEnd = boundary.value.length + 4;
+                }
+
+                // RFC 2046: boundary line may have trailing whitespace (space/tab) before CRLF
+                let hasValidTrailing = true;
+                for (let j = boundaryEnd; j < line.length; j++) {
+                    if (line[j] !== 0x20 && line[j] !== 0x09) {
+                        hasValidTrailing = false;
                         break;
                     }
                 }
-                if (!boudaryMatches) {
+                if (!hasValidTrailing) {
                     continue;
                 }
 
@@ -87,6 +106,7 @@ export default class PostalMime {
                     this.currentNode = new MimeNode({
                         postalMime: this,
                         parentNode: boundary.node,
+                        parentMultipartType: boundary.node.contentType.multipart,
                         ...this.mimeOptions
                     });
                 }
@@ -338,7 +358,7 @@ export default class PostalMime {
             return false;
         }
 
-        switch (node.contentType.parsed.value) {
+        switch (node.contentType.parsed?.value) {
             case 'text/html':
             case 'text/plain':
                 return true;
@@ -351,7 +371,7 @@ export default class PostalMime {
     }
 
     isInlineMessageRfc822(node) {
-        if (node.contentType.parsed.value !== 'message/rfc822') {
+        if (node.contentType.parsed?.value !== 'message/rfc822') {
             return false;
         }
         let disposition =
@@ -368,7 +388,10 @@ export default class PostalMime {
         let forceRfc822Attachments = false;
         let walk = node => {
             if (!node.contentType.multipart) {
-                if (['message/delivery-status', 'message/feedback-report'].includes(node.contentType.parsed.value)) {
+                if (
+                    node.contentType.parsed &&
+                    ['message/delivery-status', 'message/feedback-report'].includes(node.contentType.parsed.value)
+                ) {
                     forceRfc822Attachments = true;
                 }
             }