Module mail 

The email lexical layer (RFC 5322, RFC 2045, RFC 2047, RFC 2231): header lines and folding, encoded words, MIME parameters with continuations, addresses, and message identifiers. The grammar smtp-net needs to write mail and gate-net needs to validate login addresses (D-008); not a mail parser. Charsets decoded: UTF-8, US-ASCII, ISO-8859-1.

Examples

use parse_net::{mail, SliceSink, Limits};

let mut buf = [0u8; 256];
let mut out = SliceSink::new(&mut buf);
mail::encode_words("Caf\u{e9} au lait", 64, &mut out).expect("room");
assert_eq!(out.written(), b"=?UTF-8?Q?Caf=C3=A9_au_lait?=");

let a = mail::parse_addr_spec(b"\"john doe\"@example.com")?;
assert!(a.is_ascii());
assert!(mail::parse_addr_spec(b"john..doe@example.com").is_err());

let (p, _) = mail::parse_mime_params(b"; filename*0*=UTF-8''caf%C3%A9; filename*1=\".txt\"", &Limits::DEFAULT)?;
let mut name = [0u8; 32];
assert_eq!(p.decode_into("filename", &mut name)?, Some("caf\u{e9}.txt"));

Re-exports

pub use crate::MailDate;

Structs

AddrSpec

An address: local-part "@" domain.

Continuation

The sections of an RFC 2231 continued value, validated at parse.

Mailbox

A mailbox: an optional display name and an address.

MimeParamIter

The parameters of a validated MimeParams.

MimeParams

Validated MIME parameters.

MsgId

A message identifier: "<" id-left "@" id-right ">".

UnfoldIter

The pieces of an Unfolded value.

Unfolded

A validated folded field body.

Enums

Domain

A domain.

LocalPart

A local part.

MimeValue

A MIME parameter value.

Functions

check_header_value

Checks a header field value for writing: no control byte but HTAB, and at most 998 bytes (the physical line limit of RFC 5322 section 2.1.1, which the caller’s Name: also counts toward).

decode_phrase

Decodes a phrase (RFC 5322 section 3.2.5), such as the display name parse_mailbox returns raw, into out and returns its text: comments are dropped, quoted strings lose their quotes and their quoted pairs are unescaped, and the words are joined by one space. RFC 2047 encoded words are decoded where section 5 allows them in a phrase: a whole atom between whitespace, never inside a quoted string; two encoded words with only whitespace between them are joined with none (section 6.2). Encoded words are read as decode_words reads them, and every byte of the text meets its rules: UTF-8, no control character but HTAB.

decode_words

Decodes the RFC 2047 encoded words in unstructured header text into out and returns the text. Text outside encoded words is copied; whitespace between two adjacent encoded words is dropped (section 6.2); _ is a space in Q; an encoded word must stand alone between whitespace, and words inside a quoted string are not decoded (section 5). Charsets: UTF-8, US-ASCII, ISO-8859-1 (transcoded), with an optional RFC 2231 *language. B words are read strictly (D-080): whole groups of four, = padding only at the end with zero bits under it, no whitespace inside, and at most 75 bytes to a word. CRLF WSP folds count as whitespace, so the output of encode_words and encode_words_b reads back as written.

encode_words

Writes text for an unstructured header field: as it is when it is printable ASCII without =? that fits in a 998-byte line, otherwise as RFC 2047 =?UTF-8?Q?...?= words of at most 75 bytes, split only between characters, separated by CRLF SP. The first word fits in room_first_line (the columns left after Name: ); when not even one character fits there, the words start on a new line.

encode_words_b

encode_words with the RFC 2047 B encoding: =?UTF-8?B?...?= words of at most 75 bytes, split only between characters, separated by CRLF SP. Text that goes out as it is under encode_words goes out as it is here. B costs four bytes for every three, Q three for every byte it escapes, so B is the shorter for text that is mostly not ASCII: a Japanese or Chinese subject is about 40% shorter. decode_words reads both.

fold

Writes Name: value with CRLF folds before whitespace so lines stay within 78 columns where the words allow, never creating a line of only whitespace and never one over 998 bytes. A space is added after the colon when value does not start with whitespace. No CRLF is written at the end.

is_field_name

Whether name is an email header field name: one or more ftext (%d33-57 / %d59-126, RFC 5322 section 3.6.8).

parse_addr_spec

Parses an addr-spec (RFC 5322 section 3.4.1) without obsolete forms, comments, or folding: a dot-atom or quoted local part, @, and a dot-atom domain or [domain-literal]. The local part is at most 64 octets and the address at most 254; non-ASCII is accepted only as valid UTF-8 (RFC 6532). Surrounding SP and HTAB are stripped.

parse_mailbox

Parses a mailbox (RFC 5322 section 3.4): [display-name] "<" addr-spec ">" or a bare addr-spec. The display name is checked as a phrase (atoms, dots, quoted strings, comments, UTF-8) and returned raw.

parse_mime_params

Parses *( ";" attribute "=" value ) (RFC 2045 section 5.1) with the MIME token class, CFWS between the parts, and case-insensitive names, and validates every RFC 2231 extended value and continuation. Returns the parameters and the bytes used (parsing stops at the first byte that does not start another parameter).

parse_msg_id

Parses a msg-id (RFC 5322 section 3.6.4): dot-atom-text on both sides of @, or a no-fold-literal ([...]) on the right.

unfold

Validates a folded header field body and returns its pieces: the text between CRLF WSP folds, each CRLF removed and the WSP kept (RFC 5322 section 2.2.3). Concatenated, the pieces are the unfolded value.

write_mime_param

Writes ; name=value: as a token, as a quoted string, or, for non-ASCII or long values, as ; name*=UTF-8''..., split into name*0*, name*1* sections on folded lines when one line would pass 78 columns. The parameter starts a line of its own: use write_mime_param_at after other text on the line. The output parses back with parse_mime_params to the same value.

write_mime_param_at

Writes ; name=value as write_mime_param does, where room_first_line columns are left on the current line (78 less what the line holds), and returns the columns left on the line the parameter ends on, for the next call. A one-line form that does not fit in the room goes on a new line, ;CRLF name=value, before the value is split into sections; the ; always goes on the current line. With a room_first_line of 78 the output is that of write_mime_param.

write_msg_id

Writes <left@right>. left must be ASCII dot-atom-text; right the same or a domain literal in brackets.