hot.dev/google-gmail / ::google::gmail::parse

Read a Gmail message resource (as returned by get-message with format: "full", the default): headers, the plain-text and HTML bodies, and the attachment list, by walking the MIME parts tree. Gmail returns part data base64url encoded; these helpers decode it. All functions are pure.

to-email turns a message into a flat Email record, the shape agents and workflows usually want.

Body text is decoded as UTF-8. Gmail undoes the transfer encoding but not the charset, so a part in another charset (e.g. iso-8859-1) may show replacement characters; check charset.

Functions

all-parts

fn (message: Map): Vec

Every MIME part of a message, depth first, starting with the top-level payload. Empty for format: "raw" / "minimal" messages.

attachments

fn (message: Map): Vec

Every attachment of a message (a Vec of Attachment), found by walking the parts tree.

body-part

fn (message: Map, mime-type: Str): Map?

charset

fn (message: Map): Str?

The declared charset of the plain-text body (else the HTML body), lowercased, or null.

decode-data

fn (data: Any): Bytes

Decode a Gmail base64url data string (padded or not) to Bytes; null or "" give empty Bytes.

header

fn (message: Map, name: Str): Str?

One header value by case-insensitive name (first occurrence), or null: header(message, "Subject").

header-list

fn (part: Any): Vec

header-values

fn (message: Map, name: Str): Vec

Every value of a header, in order (e.g. all Received lines).

headers

fn (message: Map): Map

The message's (or a part's) headers as a Map of lowercased name to value; the first occurrence wins. Accepts a message resource or a payload part.

html-body

fn (message: Map): Str?

The first text/html body (not an attachment), decoded to a Str, or null.

is-attachment

fn (part: Map): Bool

True for a part that is a file: it has a filename, or Content-Disposition: attachment.

param

fn (value: Str?, name: Str): Str?

A parameter from a header value such as text/plain; charset="utf-8": param(value, "charset") is "utf-8". Case-insensitive; null when absent.

part-header

fn (part: Map, name: Str): Str?

part-text

fn (part: Map?): Str?

payload

fn (message: Map): Map

text-body

fn (message: Map): Str?

The first text/plain body (not an attachment), decoded to a Str, or null.

to-attachment

fn (message-id: Str?, part: Map): Attachment

to-email

fn (message: Map): Email

Flatten a message resource into an Email.

email ::google::gmail::parse/to-email(::google::gmail::messages/get-message(id))
`${email.from-email}: ${email.subject}`

walk-parts

fn (part: Map): Vec

A part and all its descendants, depth first (pure).

Types

Attachment

Attachment type {
    message-id: Str?,
    part-id: Str?,
    filename: Str,
    mime-type: Str?,
    size: Int?,
    attachment-id: Str?,
    data: Bytes?,
    content-id: Str?,
    inline: Bool
}

A file attached to a message.

• message-id, part-id, filename, mime-type, size (bytes)
• attachment-id - pass to ::google::gmail::messages/get-attachment (null when the data is inline in the part)
• data - the bytes when Gmail included them inline, else null
• content-id - for inline images referenced as cid: in HTML
• inline - Content-Disposition: inline

Email

Email type {
    id: Str,
    thread-id: Str?,
    history-id: Str?,
    label-ids: Vec,
    snippet: Str?,
    message-id: Str?,
    from: Str?,
    from-email: Str?,
    to: Str?,
    to-emails: Vec,
    cc: Str?,
    cc-emails: Vec,
    reply-to: Str?,
    subject: Str?,
    date: Str?,
    internal-date: Int?,
    unread: Bool,
    starred: Bool,
    in-inbox: Bool,
    text: Str?,
    html: Str?,
    attachments: Vec,
    raw: Map
}

A Gmail message flattened for workflows and agents.

• id, thread-id, history-id, label-ids, snippet
• message-id - the RFC 5322 Message-ID header
• from, to, cc, reply-to, subject, date - header values as Gmail returns them
• from-email - the sender's address, lowercased
• to-emails, cc-emails - recipient addresses, lowercased
• internal-date - when Gmail received it (epoch ms, Int)
• unread, starred, in-inbox
• text, html - decoded bodies (null when absent)
• attachments - Attachments
• raw - the message resource