std/mail

Standard Library documentation

Pure ZuzuScript mail message object model.

Back to Stdlib View Source

Module

Name
std/mail
Area
Standard Library
Source
modules/std/mail.zzm

NAME

std/mail - Pure ZuzuScript mail message object model.

SYNOPSIS

  from std/mail import Address, Head, Body, Message;
  let message := new Message(
    head: new Head(),
    body: Body.bytes( to_binary("Hello\r\n") )
  );

IMPLEMENTATION SUPPORT

This module is supported by all implementations of ZuzuScript.

DESCRIPTION

This module provides the object model for RFC 5322-style message headers, address objects, MIME-ish bodies, date helpers, a conservative parser, and integration with compatible low-level mailers.

The parser ignores multipart preamble and epilogue bytes in Phase 9. When either is present, Parser.warnings() records the limitation.

The serializer can generate missing multipart boundaries on request. Serializer.serialize() writes matching Content-Type output for the generated boundary. Serializer.serialize_body() returns only body bytes, so callers using it with a generated boundary must provide the matching Content-Type header separately.

EXPORTS

Functions

  • parse_datetime(String text)

    Parameters: text is a mail date string. Returns: Time. Parses a mail header date into a std/time object.

  • format_datetime(Time time)

    Parameters: time is a std/time object. Returns: String. Formats a time for use in mail headers.

Classes

  • Address

    Mail address object.

    • Address.parse(String text), Address.parse_list(String text)

      Parameters: text is address header text. Returns: Address or Array. Parses one address or a comma-separated address list.

    • address.local(), address.domain(), address.display_name(), address.address()

      Parameters: none. Returns: String or null. Returns address components.

    • address.to_header(), address.to_String()

      Parameters: none. Returns: String. Formats the address.

    • address.to_Dict()

      Parameters: none. Returns: Dict. Converts the address to a dictionary.

  • Head

    Ordered mail header collection.

    • head.fields(), head.to_PairList(), head.to_Iterator()

      Parameters: none. Returns: PairList or Function. Returns header fields or an iterator.

    • head.raw(String name, fallback := null), head.raw_all(String name), head.decoded(String name, fallback := null), head.decoded_all(String name), head.get(String name, fallback := null), head.get_all(String name)

      Parameters: name is a header name and fallback is optional. Returns: String, Array, or fallback. Reads header values.

    • head.set(String name, String value), head.add(String name, String value), head.remove(String name)

      Parameters: name is a header name and value is header text. Returns: Head. Mutates header fields.

    • head.has(String name)

      Parameters: name is a header name. Returns: Boolean. Tests whether a header exists.

    • head.content_type(), head.content_transfer_encoding(), head.charset(), head.boundary(), head.message_id(), head.date(), head.from(), head.to(), head.cc(), head.bcc(), head.subject()

      Parameters: none. Returns: header-specific value. Reads common headers.

  • Body

    Mail body value.

    • Body.bytes(BinaryString raw, ... PairList options)

      Parameters: raw is body bytes and options describe content type, encoding, and parts. Returns: Body. Creates a leaf or multipart body.

    • Body.nested(message, ... PairList options)

      Parameters: message is a Message. Returns: Body. Creates a nested message body.

    • body.is_multipart(), body.is_nested()

      Parameters: none. Returns: Boolean. Reports body shape.

    • body.bytes(), body.decoded(), body.encoded()

      Parameters: none. Returns: BinaryString. Returns raw, decoded, or encoded body bytes.

    • body.parts(), body.part(Number index), body.count()

      Parameters: index selects a body part. Returns: Array, Body, or Number. Reads multipart body parts.

    • body.nested(), body.content_type(), body.transfer_encoding(), body.to_Dict()

      Parameters: none. Returns: value. Reads body metadata or converts the body to a dictionary.

  • Message

    Mail message object with head and body.

    • message.head(), message.body()

      Parameters: none. Returns: Head or Body. Returns message parts.

    • message.header(String name, fallback := null), message.headers(String name)

      Parameters: name is a header name and fallback is optional. Returns: String, Array, or fallback. Reads message headers.

    • message.set_header(String name, String value), message.add_header(String name, String value), message.remove_header(String name)

      Parameters: name is a header name and value is header text. Returns: Message. Mutates message headers.

    • message.subject(), message.from(), message.to(), message.cc(), message.bcc(), message.date(), message.message_id()

      Parameters: none. Returns: header-specific value. Reads common message headers.

    • message.is_part(), message.container(), message.toplevel()

      Parameters: none. Returns: Boolean or Message. Reads containment state.

    • message.send(mailer, ... PairList options)

      Parameters: mailer is a compatible low-level mailer. Returns: value. Sends the message.

    • message.to_Dict()

      Parameters: none. Returns: Dict. Converts the message to a dictionary.

  • Parser

    Conservative mail parser.

    • parser.warnings()

      Parameters: none. Returns: Array. Returns non-fatal parse warnings.

    • parser.parse(BinaryString bytes)

      Parameters: bytes is raw message bytes. Returns: Message. Parses a mail message.

  • Serializer

    Mail serializer.

    • serializer.serialize_body(Message message, ... PairList options)

      Parameters: message is a mail message and options control output. Returns: BinaryString. Serializes only the message body.

    • serializer.serialize(Message message, ... PairList options)

      Parameters: message is a mail message and options control output. Returns: BinaryString. Serializes a complete message.

COPYRIGHT AND LICENCE

std/mail is copyright Toby Inkster.

It is free software; you may redistribute it and/or modify it under the terms of either the Artistic License 1.0 or the GNU General Public License version 2.