MIMEText

MIMEText (published as mimetext on npm) builds RFC-5322 compliant email messages as raw MIME strings, without touching SMTP or any transport layer. It exposes a small fluent API — set sender and recipients, add plaintext and HTML bodies, attach files inline or as attachments — and produces a fully formed multipart message ready to hand to Amazon SES, the Gmail API, or any other email service that accepts raw MIME.

The library ships environment-specific entry points for Node.js, browsers, and Google Apps Script, each sharing the same API surface with only base64 encoding and content-type resolution swapped out under the hood. It is fully typed in TypeScript, has no dependency on any single email provider, and is commonly used as the message-construction layer feeding Amazon SES’s raw-email commands and the Gmail API’s raw message field.

What You Get

• A createMimeMessage() factory that returns a MIMEMessage instance with a fluent API for headers, recipients, and content.
• Automatic multipart structure selection — mixed, related, alternative, or a combination — chosen based on which content types and attachments you add.
• Separate mimetext, mimetext/browser, and mimetext/gas entry points sharing one API, with base64 encoding and MIME-type lookup swapped per runtime.
• asRaw() and asEncoded() output methods, ready to pass directly into Amazon SES’s raw email API or Gmail API’s raw message field.
• Typed MIMETextError exceptions with stable error codes (e.g. MIMETEXT_MISSING_BODY, MIMETEXT_INVALID_MAILBOX) for input validation failures.

Common Use Cases

• Sending via Amazon SES raw email - services building on SendRawEmailCommand or SES v2’s raw content field use MIMEText to assemble the multipart body with attachments before handing it to the AWS SDK.
• Sending via Gmail API - apps authenticating with googleapis construct the raw, base64url-encoded message MIMEText produces and pass it to gmail.users.messages.send.
• Email testing and parsing fixtures - test suites generate deterministic RFC-5322 messages with MIMEText to feed into email-parsing or spam-filter test cases.

Under The Hood

Architecture MIMEMessage.ts (350 lines) is the core orchestrator: its constructor takes an EnvironmentContext (runtime-specific base64/EOL/content-type functions), instantiates a MIMEMessageHeader, and holds an array of MIMEMessageContent instances plus three random multipart boundaries generated in generateBoundaries(). asRaw() is the central method — it fetches plaintext/html content via getMessageByType(), checks for attachments/inline-attachments via hasAttachments()/hasInlineAttachments(), and branches into one of four multipart structures (‘mixed+related’, ‘mixed’, ‘related’, ‘alternative’) or a bare single-part fallback, hand-assembling boundary-delimited strings via concatenation. MIMEMessageContent (48 lines) wraps a single body part’s headers and data, exposing isAttachment()/isInlineAttachment() by inspecting Content-Disposition. Mailbox.ts (79 lines) parses To/From/Cc/Bcc values from either a string (“Name <addr>”) or object form via a self-contained regex, with no external validation dependency. The three entry points (entrypoints/node.ts, browser.ts, gas.ts) are the only place that differs per runtime — each defines an envctx object (toBase64, toBase64WebSafe, eol, validateContentType) and exports createMimeMessage() bound to it; node.ts sources EOL from node:os and content-type validation from the mime-types package, letting the same MIMEMessage/MIMEMessageContent/Mailbox classes run unmodified across Node, browser, and Google Apps Script.

Tech Stack TypeScript throughout (GitHub reports 69.85% TS / 30.15% JS, the JS being generated dist/ output). Two runtime dependencies: js-base64 (browser-safe base64 fallback) and mime-types (Node content-type resolution). Build via Rollup (rollup.config.js), producing ES and CJS bundles per entry point plus an IIFE browser bundle; Babel (@babel/preset-env, @babel/preset-typescript) handles transpilation with core-js polyfills for a browserslist target reaching down to IE10. Tests run under Jest with @swc/jest for fast TS transform. Linting uses ESLint 9’s flat config with typescript-eslint. Husky, commitizen, and semantic-release wire up conventional commits and automated releases. The package ships prebuilt dist/ artifacts, so consumers need no build step of their own.

Code Quality Six spec files live under tests/ (Mailbox.spec.js, MIMEMessage.spec.js, MIMEMessageContent.spec.js, MIMEMessageHeader.spec.js, MIMETextError.spec.js, MIMEText.spec.js) totaling 714 lines against 856 lines of src — roughly a 1:1 test-to-source ratio covering both class-level unit behavior and, via MIMEText.spec.js, end-to-end raw-output assertions. Error handling is explicit and typed: every invalid-input path throws a MIMETextError with one of a fixed set of string codes (MIMETEXT_MISSING_BODY, MIMETEXT_MISSING_FILENAME, MIMETEXT_INVALID_MESSAGE_TYPE, MIMETEXT_INVALID_MAILBOX) rather than failing silently. Naming is consistent and low-abbreviation (setSender/setRecipients/addMessage/addAttachment); the main readability cost is asRaw()‘s long four-way structure branch, which repeats similar boundary-joining logic across cases instead of sharing a helper. A few non-null assertions (e.g. (primaryMessage!).dump()) stand in for proper narrowing, a minor type-safety tradeoff.

API Design The public surface is small and consistent — one factory (createMimeMessage), one builder class with paired setX/getX methods (setSender/getSender, setHeader/getHeader), and calls that return the value or object they created (e.g. setRecipients returns the Mailbox[] it built). Getting started takes one import and four or five lines to produce a working raw message, with no configuration object or class instantiation boilerplate beyond createMimeMessage(). Full TypeScript types ship for every export (MailboxAddrObject, ContentOptions, AttachmentOptions, HeadersObject), and the README documents every runtime entry point plus two complete worked integrations (Amazon SES v1/v2, Gmail API) rather than just API reference — a high documentation-to-code ratio for a project this size.