@portable/mime-stream

Splits a raw MIME message into a stream of header blocks, bodies and multipart structure, and writes it back out byte for byte. Use it to change a message on its way through, such as removing attachments or hashing bodies, without parsing the whole message into objects. Runs in browsers, Cloudflare Workers, Deno, Bun and Node 24+.

Replaces mailsplit (now @zone-eu/mailsplit). To parse a message into text, HTML and attachments, use postal-mime.

npm install @portable/mime-stream

import * as MimeStream from '@portable/mime-stream';
 
// Replace every PDF attachment with a note, and keep the rest of the message as it was.
const output = message
  .pipeThrough(new MimeStream.DecoderStream())
  .pipeThrough(
    new TransformStream<
      MimeStream.Chunk,
      MimeStream.EncoderStream.Input
    >({
      transform(chunk, controller) {
        if (chunk.part.contentType !== 'application/pdf') {
          controller.enqueue(chunk);
        } else if (chunk.type === 'headers') {
          controller.enqueue(
            'Content-Type: text/plain\r\n\r\nAttachment removed.',
          );
        }
      },
    }),
  )
  .pipeThrough(new MimeStream.EncoderStream());

message is a ReadableStream<Uint8Array>, such as request.body or file.stream().

To read only the header block, for example to check a DKIM signature, use splitHeaders. It doesn't look for parts, so the body passes through untouched:

const { headers, body } = await MimeStream.splitHeaders(message);
// headers: the header block as received, with the empty line that ends it
// body: a ReadableStream of every byte after it

API

A Chunk is { type, part, bytes }. Joining every chunk's bytes in order gives back the input.

A Part is a plain object, shared by every chunk of that part:

Parts are split as RFC 2046 says. A delimiter is -- and the boundary on a line of its own, optionally followed by -- (the close delimiter) and spaces or tabs. The line break before a delimiter belongs to the delimiter, so a body never ends with it. Lines may end in CRLF or LF. A delimiter of an outer multipart also ends every multipart inside it, and a close delimiter in the preamble is preamble text. After the close delimiter, lines that look like delimiters of that multipart are epilogue text.

Options

The size limits default to Infinity. Set maxHeaderBytes, maxBoundaryLineBytes and maxParts when you read mail from outside your program, because without them a message can make the decoder buffer a header block or boundary line of any size, or report any number of parts. maxHeaderBytes: 1024 * 1024, maxBoundaryLineBytes: 1000 and maxParts: 1000 are enough for real mail.

Types

Why use this over mailsplit

mailsplit is a Node Transform stream with libmime, libqp and libbase64 as dependencies. DecoderStream is a TransformStream with no dependencies outside @portable/*, so it reads a fetch body or a Workers email in any runtime.

• Splitting and joining 1.5 MB of mail took 1.3 ms on Node 24, against 7.9 ms for mailsplit. splitHeaders reads the header block and passes on the body of the same message in 0.06 ms. mailsplit has no equivalent, and with ignoreEmbedded it took 7.9 ms.
• A part that has headers and no body, followed by a delimiter (--B\r\nX-Only: headers\r\n--B), is kept. mailsplit 5.4.23 drops its bytes, so its output is not the input.
• A delimiter followed by spaces or tabs is read as a delimiter, as RFC 2046 allows. mailsplit reads it as body text, so it sees different parts from mail clients.
• Header values are decoded as UTF-8 and the raw bytes are kept in the headers chunk. mailsplit returns Latin-1 strings, which turns UTF-8 addresses into mojibake (mailsplit #21).
• A part with no Content-Type is text/plain, as RFC 2045 says. mailsplit guesses a type from the file name.
• Chunks are plain objects. To change a header, enqueue new bytes for the headers chunk, for example from MimeHeaders.fold. There is no headers object to keep in sync.
• mailsplit splits embedded messages unless ignoreEmbedded is set. DecoderStream splits them only with embedded: true.
• mailsplit's maxHeadSize defaults to 1 MiB and counts each line as at least 64 bytes. maxHeaderBytes counts bytes and defaults to no limit, so pass maxHeaderBytes: 1024 * 1024 to keep mailsplit's limit.
• mailsplit's maxChildNodes defaults to 1000, and maxParts defaults to no limit, so pass maxParts: 1000 to keep mailsplit's limit.
• mailsplit's limit errors have the code 'EMAXLEN'. For an exceeded limit, DecoderStream throws MaxHeaderBytesError, MaxBoundaryLineBytesError or MaxPartsError.
• A part has no charset, filename or disposition field as mailsplit's nodes do. Read them with MimeHeaders.parseValue from the Content-Type or Content-Disposition field.
• mailsplit's headers.mbox and headers.http have no equivalent. The mbox From line or HTTP status line stays at the start of the root headers chunk, and part.headers skips it.
• part.headers skips a first line that starts with whitespace and a line with no valid field name. A bare CR doesn't end a line.
• encoding drops every comment, including an unclosed one, so base64 (x is base64. mailsplit keeps the text when a comment isn't closed.
• An empty part between two delimiters is reported as a part. mailsplit reports nothing for it.

Operations per second from pnpm bench, higher is better, in Node 24.22.0, on Intel(R) Xeon(R) Processor @ 2.10GHz (4 cores). A dash means the library has no equivalent.

Sizes cover the imports in the usage example, or the equivalent imports of each library, bundled for the browser by scripts/bundle-size.ts. Runtime dependencies count every package installed with the published package. A library that uses Node built-ins needs polyfills in a browser and the nodejs_compat flag in Cloudflare Workers.