#mime API reference

Build and parse MIME messages (RFC 5322 headers + RFC 2045/2046 bodies): a header-and-boundary structure that is exactly the text orchestration a .j module does well. The transfer codecs (base64, quoted-printable) are delegated to the encoding system library. This is the message-structure foundation the mail clients (SMTP / POP3 / IMAP) build on; it does no networking itself. A Part is a leaf (headers + a decoded body/data with a transfer encoding) or a multipart container (headers + child parts + a boundary); bodies are held decoded as text, encode applies the transfer encoding and parse removes it. RFC 2047 encoded-words are applied automatically on encode and decoded on parse, with encodeWord / decodeWord exposed for manual use. Every leaf carries its raw decoded data (bytes), so binary attachments round-trip; body is the text view, populated for text parts and decoded per the Content-Type charset (UTF-8 by default; ISO-8859 / Windows single-byte codecs are honoured, with a UTF-8 fallback for an unknown label). Attachment filenames are read and written in RFC 2231 extended form (filename*=) when they carry non-ASCII characters. Use walk / attachments / textBodies to pull parts out of a received message.

Import with import "mime.j" as mime;. See the mime guide for prose and examples.

#Functions

#mime.address(name as string, email as string)

Format an RFC 5322 mailbox: email alone, or Name <email> with the name quoted when it carries a special character.

Parameters

• name {string} - the display name (empty for a bare address)
• email {string} - the email address

Returns {string} - the formatted mailbox

#mime.attachment(filename as string, contentType as string, body as string)

Build a base64 leaf part with a filename. body is text content (UTF-8); binary bodies are not yet supported.

Parameters

• filename {string} - the attachment filename
• contentType {string} - the media type
• body {string} - the text content to attach

Returns {Part} - the attachment part

#mime.attachmentBytes(filename as string, contentType as string, data as bytes)

Build a base64 attachment part from raw bytes (images, PDFs, any binary). The binary counterpart to attachment; encode base64-wraps the data and parse restores it, so it round-trips intact.

Parameters

• filename {string} - the attachment filename
• contentType {string} - the media type (e.g. "image/png")
• data {bytes} - the raw file content

Returns {Part} - the attachment part

#mime.attachments(part as Part)

Return every attachment leaf in the message (see isAttachment). Each part's bytes are data($part) and its name filename($part).

Parameters

• part {Part} - the parsed message (or any subtree)

Returns {list of Part} - the attachment parts

#mime.body(part as Part)

Return a leaf part's decoded text body.

Parameters

• part {Part} - the leaf part

Returns {string} - the decoded body text

#mime.contentType(part as Part)

Return a part's media type without parameters (e.g. "text/plain").

Parameters

• part {Part} - the part to read

Returns {string} - the media type

#mime.data(part as Part)

Return a leaf part's raw decoded content bytes (any type, including binary attachments). This is the byte-accurate counterpart to body.

Parameters

• part {Part} - the leaf part

Returns {bytes} - the raw decoded content

#mime.decodeWord(value as string)

Decode every RFC 2047 encoded-word in value, dropping the linear whitespace that separates two adjacent encoded-words (as a reader should). A word that fails to decode is left verbatim so parse never crashes.

Parameters

• value {string} - the header value possibly carrying encoded-words

Returns {string} - the decoded text

#mime.disposition(part as Part)

Return a part's Content-Disposition (lowercased, without parameters): "attachment", "inline", or "" when the header is absent.

Parameters

• part {Part} - the part to read

Returns {string} - the disposition

#mime.encode(part as Part)

Serialize a part (and its subtree) to a MIME message string with CRLF line endings and the declared transfer encodings applied.

Parameters

• part {Part} - the part to serialize

Returns {string} - the encoded MIME message

#mime.encodeWord(text as string)

Render text as one or more RFC 2047 UTF-8 base64 encoded-words, each kept under the 75-character limit (split on rune boundaries, never mid-character) and folded with CRLF + space when more than one is needed.

Parameters

• text {string} - the text to encode

Returns {string} - the encoded-word sequence

#mime.filename(part as Part)

Return a part's filename: the Content-Disposition filename parameter, else the Content-Type name parameter. RFC 2231 extended / continued forms (filename*=, filename*0=...) and RFC 2047 encoded-words are both decoded; "" when neither is present.

Parameters

• part {Part} - the part to read

Returns {string} - the filename

#mime.findParts(part as Part, mediaType as string)

Return every leaf whose media type equals mediaType (e.g. "text/html").

Parameters

• part {Part} - the parsed message (or any subtree)
• mediaType {string} - the exact media type to match (case-insensitive)

Returns {list of Part} - the matching leaf parts

#mime.headerValue(part as Part, name as string)

Return a part's header value (case-insensitive) or "".

Parameters

• part {Part} - the part to read
• name {string} - the header name

Returns {string} - the header value, or "" when absent

#mime.isAttachment(part as Part)

Report whether a part is an attachment: Content-Disposition is "attachment", or a filename is set.

Parameters

• part {Part} - the part to read

Returns {bool} - true when the part is an attachment

#mime.multipart(subtype as string, boundary as string, parts as list of Part)

Build a container part; every child ships under one boundary.

Parameters

• subtype {string} - the multipart subtype (e.g. "mixed", "alternative")
• boundary {string} - the boundary delimiter separating children
• parts {list of Part} - the child parts

Returns {Part} - the multipart container part

#mime.parse(text as string)

Read a MIME message string into a Part tree: headers are unfolded, a multipart body is split on its boundary (recursively), and a leaf body is transfer-decoded.

Parameters

• text {string} - the MIME message text

Returns {Part} - the parsed part tree

#mime.parts(part as Part)

Return a multipart container's child parts.

Parameters

• part {Part} - the multipart container

Returns {list of Part} - the child parts

#mime.text(contentType as string, body as string)

Build a leaf text part; the body is sent 7bit when ASCII, else quoted-printable. charset=utf-8 is appended to the content type.

Parameters

• contentType {string} - the media type (e.g. "text/plain")
• body {string} - the decoded text body

Returns {Part} - the leaf text part

#mime.textBodies(part as Part)

Return the readable text bodies: text parts (any text/ subtype) that are not attachments (so both the text/plain and text/html alternatives of a message).

Parameters

• part {Part} - the parsed message (or any subtree)

Returns {list of Part} - the text body parts

#mime.walk(part as Part)

Flatten a part tree to its leaf parts (depth-first). A leaf is a part with no child parts; the building block for attachments / textBodies.

Parameters

• part {Part} - the part (leaf or container) to walk

Returns {list of Part} - every leaf part, in document order

#mime.withHeader(part as Part, name as string, value as string)

Return a copy of the part with name set (replaced or appended).

Parameters

• part {Part} - the part to copy
• name {string} - the header name to set
• value {string} - the header value

Returns {Part} - the updated copy

#Structs

#mime.Header

A single header field.

#mime.Part

A MIME part: a leaf (data/body + encoding, parts empty) or a multipart container (parts + boundary, body/data empty).