Building mail
This page explains how email-mcp builds the mail that an agent writes: the
checks that refuse a message, the rules for recipients, the subject, the HTML
and the addresses, a saved draft, and what the preview shows. Read it before you
change Build, FromDraft or the rules for addresses. Mail
content draws the outgoing pipeline.
What goes out
Build in internal/mime/build.go writes a message, a reply, a
reply to all, or a forward, in the form of RFC 5322 (the numbered document for
the internet message format). internal/mime/body.go has the bodies
and the attachments, internal/mime/recipients.go the recipients,
and internal/mime/address.go the rules for addresses. A message
that the agent writes goes out as the preview can show it. A saved draft goes
out as it was saved (see A saved draft).
What Build refuses
A refusal returns an error that names the field. It holds no address, subject or other text of the message.
| Error | The case |
|---|---|
ErrInvalidAddress |
An address is missing, cannot be parsed, or cannot be sent as it is: a quoted local part such as "a b"@example.com, a domain literal such as bob@[1.2.3.4], or a space, a quote or one of <>()[],;:\ in it |
ErrNonASCIILocalPart |
A recipient that the caller typed has characters outside ASCII (English letters, digits and common signs) before the @. It matches ErrInvalidAddress. |
ErrNoRecipients |
The message goes to nobody. A draft may have none. |
ErrHeaderInjection |
A header value has a CR (carriage return), an LF (line feed) or a NUL (the zero byte). A line break would let the value add a header, such as a Bcc. |
ErrHiddenText |
The subject, the text body or a display name has a character that CleanUntrusted would remove. |
ErrEmptyHTML |
Nothing is left of the HTML body after the parts that a reader cannot see, and those that cannot go out, are removed. |
ErrInvalidFilename |
The file name of an attachment has a character that CleanUntrusted would remove, or a line or paragraph separator. |
ErrInvalidContentType |
The content type of an attachment cannot be written, is multipart, has a charset other than UTF-8 or US-ASCII, or has a media type over MaxMediaTypeBytes (100 bytes). |
ErrNoOriginal, ErrReplyAndForward |
A reply or a forward has no original message, or one request asks for both. |
mail.ErrTooLarge |
The attachments are together over MaxAttachmentBytes, 10 MiB. A MiB (mebibyte) is 1,048,576 bytes. |
ErrHTMLTooComplex |
The HTML body is too complex to clean or to make the text of. |
A value from the original message is cleaned and not refused, because a third party wrote it and it must not stop a reply. An address of the original with a line break is refused, because cleaning would change it.
Recipients
A reply goes to the Reply-To addresses of the original, or to its sender. A
reply to all also copies the To and Cc addresses of the original to Cc. Then the
To, Cc and Bcc addresses of the request are added. For a reply to all, the
addresses of the user (BuildContext.Self) are then removed from To and Cc.
Each address stays once, and the first one wins, in the order To, Cc, Bcc. All
are in RawMessage.Recipients. A Bcc is a blind copy: the other recipients do
not see it. The message has no Bcc header. A draft keeps the header
(BuildContext.ForDraft), and FromDraft removes it before the send.
Subject and threading
When the request has no subject, a reply gets “Re: " before the subject of the
original, unless that starts with “re:” in any case, and a forward gets “Fwd: “.
A reply gets In-Reply-To and References headers. Build does not quote the
original in a reply. A forward puts the text of the original under the header
“Forwarded message”. It copies the attachments of the original only when
IncludeOriginalAttachments is set, with cleaned file names and types. A media
type over MaxMediaTypeBytes goes out as application/octet-stream. The HTML
of the original is never copied.
HTML in outgoing mail
outgoingHTML is VisibleHTML with one more rule. Both clean the HTML with the
policy of SanitizeHTML. The policy keeps headings, paragraphs, inline text
such as b and em, lists, tables and links. A link keeps href, and the
fixed rel="nofollow", only when its address uses http, https or mailto,
and the text shows the whole address. A link whose address the text cuts or does
not show goes out as plain text. The result has no comment, no style and no
image, and no attribute but those two. A message has one text: when the request
has an HTML body, its plain text body is not used, and the text part is made
from the HTML.
Addresses that look like others
ShownAddress writes the ASCII form (punycode, the xn-- spelling) of a domain
outside ASCII next to the address, so that a look-alike domain shows.
AddressWarning names each part of a domain that mixes writing systems, by the
Unicode TS 39 (the Unicode technical standard on security) at the level “highly
restrictive”. The send refuses a domain with no exact ASCII form
(HasExactASCIIDomain). HasNonASCIIAddress makes the service ask the person
before it sends to an address outside ASCII (see The send
flow).
The shape of the message
One text/plain part; or a multipart/alternative with the text part first and
the HTML part last, because mail programs use the last part that they can show;
and a multipart/mixed around it when there are attachments. Build gives the
message its own Message-ID: 16 random bytes in hex, an @, and the domain of
the sender. Of the content type of an attachment, only the media type and a
UTF-8 (a way to write each character as one to four bytes) or US-ASCII charset
go out.
A saved draft
FromDraft in internal/mime/draft.go makes a saved draft ready to
send. It reads the sender from the first From address and the recipients from
To, Cc and Bcc. The message that goes out is the draft as it was saved,
minus the Bcc fields. It refuses a bare CR (a carriage return with no line
feed after it) in the header (ErrHeaderInjection), a missing sender or an
unreadable address (ErrInvalidAddress), and a draft with no recipient
(ErrNoRecipients). It does not refuse or clean hidden characters or HTML the
way Build does: a draft goes out as the person saved it, with its styles and
images. The preview of a draft counts its hidden characters and shows its text
only. Check a draft that came from another mail program before you send it (see
Security).
The preview and the text part
For a message made from HTML, composeBodies makes the text part with
HTMLToText of the cleaned HTML, and Build writes it first. The service, in
internal/service/send.go, reads the built message again and shows
the person the start of the text part. So the start of the text that the person
sees is the start of the text that goes out. For a saved draft, the preview
shows the parts that LayoutOf picks. The send
flow explains the
preview and how the answer of the person is tied to the message.
Related pages
- Mail content
- The send flow
- What the agent can do in the user manual
- Security in the user manual