Crate mail_parser

Expand description

Fast and robust e-mail parsing.

A MessageParser turns the bytes of an RFC 5322 message into a read-only Message: the raw bytes plus a flat, index-based store of every nested message, MIME part and header field. Everything is read through small Copy views (MessageRef, MessagePart, Header, HeaderValue, …), and bodies are decoded on access.

use mail_parser::MessageParser;

let raw = b"From: Ann <ann@example.com>\r\nSubject: Hi\r\n\r\nHello!\r\n";
let message = MessageParser::new().parse(raw).expect("message");
assert_eq!(message.subject(), Some("Hi"));
assert_eq!(message.body_text(0).as_deref(), Some("Hello!\r\n"));

Parsing: MessageParser::parse, MessageParser::parse_owned, MessageParser::parse_headers, and MessageParser::parse_with with MessageBuffers to reuse storage from one message to the next.
Structure: Message::parts and Message::messages in document order, MessagePart::children, MessagePart::nested, the RFC 8621 body lists (MessageRef::text_body, MessageRef::html_body, MessageRef::attachments) and MIME boundaries (MessagePart::boundary, Message::part_by_boundary).
Bodies: MessagePart::decoded, MessagePart::text, MessagePart::text_prefix and MessagePart::decoded_len; MessagePart::decoded_checked and MessagePart::text_checked also report decoding problems.
Header fields: Headers with typed getters, Header::raw_name and Header::raw_value as written, Header::parse_as to parse a field in another form, and HeaderForm::parse for values on their own.
Mailboxes: mailbox::mbox and mailbox::maildir.
Utilities: DateTime, thread_name, html_to_text, text_to_html, preview_text, Charset and the other decoders.

Parsing never fails on malformed input: damaged structure is reported by MessagePart::flags, malformed encodings by the checked decoding methods. The full_encoding feature adds the multi-byte charsets (through encoding_rs), and the serde feature serializes messages.

Re-exports§

pub use decoders::charsets::Charset;
pub use decoders::html::add_html_token;
pub use decoders::html::html_to_text;
pub use decoders::html::strip_charset_meta;
pub use decoders::html::text_to_html;
pub use decoders::preview::preview_html;
pub use decoders::preview::preview_text;
pub use decoders::preview::truncate_html;
pub use decoders::preview::truncate_text;

Modules§

decoders: Decoders the parser uses that are also useful on their own: charset conversion, HTML to text and text to HTML, and body previews. Transfer encodings (base64, quoted-printable, hex) are decoded by encodify; use it directly for those, or crate::Encoding::decode to decode a body as the parser does.
mailbox: Readers for mailbox files: mbox and Maildir.

Structs§

AddressList: An address list: mailboxes and groups in document order (issue #98). Lists compare by content.
AddressRun: A run of consecutive mailboxes: the members of a Group, or a run yielded by AddressList::groups. It is an iterator of Mailbox, and runs compare by content.
ContentType: A Content-Type or Content-Disposition value. Type, subtype and parameter names are lowercase; RFC 2231 and RFC 2047 encoded parameter values are decoded. Values compare by content.
DateTime: An RFC 5322 date and time with its zone offset.
DecodeProblems: Problems found while decoding a body, returned by MessagePart::decoded_checked and MessagePart::text_checked. A non-empty set is what RFC 8621 calls isEncodingProblem.
Group: A named group of mailboxes.
Header: One header field: its name, its parsed value, and where it is in the source buffer of its message (see crate::MessageRef::source).
HeaderIter: Every header of a part in document order, returned by Headers::iter and by iterating a Headers value.
HeaderKey: A header name resolved once by HeaderName::key, for repeated lookups with crate::Headers::all_key and crate::Headers::get_key.
Headers: The header fields of one part, in the order they were written.
Mailbox: A mailbox: a display name and an address (or a URL in RFC 2369 list headers).
Message: A parsed message: the raw bytes and a store of every nested message, MIME part and header field, read through small Copy views such as MessageRef, MessagePart and crate::Header. Bodies are decoded on access.
MessageBuffers: Reusable storage for crate::MessageParser::parse_with.
MessageParser: RFC 5322 message parser and its configuration.
MessagePart: A MIME part: a header block and a body. Parts are numbered in document order across nested messages (MessagePart::id), and every message has a root part holding its own header fields.
MessageRef: A message inside a Message: the root message, or a message nested in a message/rfc822 (or message/global) part. Each message has its own root part, header fields and body lists.
NamedHeaders: The headers with one name, returned by Headers::all.
ParsedValue: A header value parsed on its own, outside a message, by HeaderForm::parse or crate::Header::parse_as. It borrows the input and owns a small store only when the value needs one (a raw, single-line text or date value allocates nothing). Parsed values compare by their value.
PartFlags: What happened while a part was parsed.
Received: A parsed Received trace field (RFC 5321 section 4.4). Every clause is optional; values compare by content.
TextList: A list of text items: message identifiers (without angle brackets), keywords, languages. Lists compare by content.

Enums§

Address: One item of an address list.
Encoding: Declared Content-Transfer-Encoding of a part. The numeric values (0, 1, 2) are stable.
Greeting: The greeting command of a Received from clause comment.
HeaderForm: How a header value is parsed.
HeaderName: A header field name: one of the known names, or any other name with its original spelling.
HeaderValue: A parsed header value. The variant follows the HeaderForm the parser used for the name (see crate::MessageParser::header). Values compare by content.
Host: A host name or an IP address.
PartKind: What a part contains.
PartRole: How the body classification used a part (issue #107). Every part has exactly one role; the roles of a message’s parts partition them.
Protocol: The protocol of a Received with clause (the IANA mail transmission types of RFC 3848 and later).
Source: The buffer the offsets of a message’s parts and headers refer to.
TlsVersion: The TLS version of a Received with clause comment.

Statics§

DOW: Three-letter day names, Sunday first, indexed by DateTime::day_of_week.
MONTH: Three-letter month names, January first.

Functions§

parse_address_detail_part: The detail of a subaddress (RFC 5233): the local part after its last +.
parse_address_domain: The domain of an address (after the first @), when the local part is ASCII and both sides of the @ are non-empty.
parse_address_local_part: The local part of an address (before the first @), when it is ASCII and both sides of the @ are non-empty.
parse_address_user_part: The user of a subaddress (RFC 5233): the local part up to the first +.
thread_name: The thread name of a subject: the subject without reply and forward prefixes (Re:, Fwd: and their translations, with counters such as Re[2]:), bracketed list tags and trailing (fwd) markers, as used to group messages into threads. Borrows from text.

Type Aliases§

MessageId: Index of a message in crate::Message::messages; 0 is the root message.
PartId: Index of a part in crate::Message::parts, in document order across nested messages.