libmime is written in TypeScript and ships both an ES module and a CommonJS build, each with type declarations. Node.js 20 or newer is required.
// ES modulesimport libmime from 'libmime';// CommonJSconst libmime = require('libmime');
The default export is a shared Libmime instance. The class itself is available as Libmime for creating instances of your own:
import { Libmime } from 'libmime';// or: const { Libmime } = require('libmime');const mime = new Libmime();
The helper modules can be loaded directly as well, for example libmime/lib/charset (encode, decode, convert, normalizeCharset, createDecodeStream, DecodeStream) and libmime/lib/mimetypes (list, extensions).
TypeScript
The bundled declarations replace @types/libmime, which can be removed. The type names it used keep working: libmime.StructuredHeader and libmime.MimeWordEncoding are available through the default export, next to the other public types (ParsedHeaderValue, StructuredHeaderValue, HeaderParam, HeaderLine, HeaderObject), which can also be imported by name:
import libmime, { type ParsedHeaderValue } from 'libmime';const parsed: ParsedHeaderValue = libmime.parseHeaderValue('text/plain; charset=utf-8');
Adds soft line breaks to content marked with format=flowed options to ensure that no line in the message is never longer than lineLength.
libmime.encodeFlowed(str [, lineLength]) → String
str Plaintext string that requires wrapping
lineLength (defaults to 76) Maximum length of a line
#decodeFlowed
Unwraps a plaintext string in format=flowed wrapping.
libmime.decodeFlowed(str [, delSp]) → String
str Plaintext string with format=flowed to decode
delSp If true, delete leading spaces (delsp=yes)
Headers
#decodeHeader
Unfolds a header line and splits it to key and value pair. The return value is in the form of {key: 'subject', value: 'test'}. The value is not mime word decoded, you need to do your own decoding based on the rules for the specific header key.
libmime.decodeHeader(headerLine) → Object
headerLine - Single header line, might include linebreaks as well if folded
#decodeHeaders
Parses a block of header lines. Does not decode mime words as every header might have its own rules (eg. formatted email addresses and such).
Return value is an object of headers, where header keys are object keys and values are arrays.
skipPrototypeKeys - if true, headers named like an Object.prototype member (__proto__, constructor) are left out. By default they are kept as own properties of the result
#parseHeaderValue
Parses a header value with key=value arguments into a structured object. Useful when dealing with
content-type and such. Continuation encoded params are joined into mime encoded words.
parseHeaderValue(valueString[, options]) → Object
valueString - a header value without the key
options - optional options object
stripComments - if true, RFC 822 comments outside quoted strings are dropped, so boundary=b (comment) gives the boundary b. A parenthesis right behind the = of a parameter or behind a token of its value continues the token, filename=Invoice(1).pdf keeps its name and boundary=(c)b names the boundary (c)b, as both do for Python and postal-mime. A comment that never closes runs to the end of the value, unless a parameter follows it, in which case it is content and the parameter survives. Use it for the MIME headers (Content-Type, Content-Disposition). By default comments are kept, since a header such as Authentication-Results carries information in them
A parameter value is a token or a quoted string, so what follows a closed quoted string up to the next ; is
dropped (boundary="b"c gives b), and a parameter that occurs more than once keeps its first value, both as Python and postal-mime read them. An RFC 2231
continuation overrides the plain parameter of the same name in either order, libmime's own rule after RFC 6266
section 4.3.
Resolves a charset name to its canonical form, eg. win-1257 becomes windows-1257. Unknown names are returned uppercased.
libmime.normalizeCharset(charset) → String
#createDecodeStream
Creates a Transform stream that decodes bytes in a charset into UTF-8 Buffers, for example a message body. The output is what decoding the whole input at once gives, however it is split into chunks. The charset name is resolved the same way as for encoded words, the Japanese charsets iconv-lite does not support (ISO-2022-JP and friends) are decoded with encoding-japanese, which is not incremental, so such input is collected until the stream ends. The double byte charsets (Shift_JIS, GBK, GB18030, Big5, EUC-KR, EUC-JP) are decoded up to the last byte below 0x30 (a space, a line break, most ASCII punctuation) of what has arrived, so input without any such byte is held until the stream ends as well.
charset - Charset the input is encoded in, defaults to UTF-8
The stream has two extra properties:
charset - the canonical charset name
supported - false when the charset is unknown or refused (UTF-7, which could smuggle markup past filters, and the base64 and hex transfer encodings). The input is then decoded as UTF-8 regardless, invalid bytes replaced with U+FFFD, the same fallback encoded words get. Check it before piping when the bytes must not be relabelled as UTF-8, for example to keep the original part as it is