repository·main·Indexed 19 days ago
https://github.com/jhillyerd/enmimeA Go-based MIME encoding and decoding library focused on the generation and parsing of MIME-encoded emails. It provides a fluent MailBuilder interface for constructing complex MIME messages, an Envelope type for high-level access to email content, and utilities like mime-dump for debugging and mime-extractor for extracting attachments.
When running mime-dump, the output is a Markdown document organized into the following sections:
From, To, and Subject.multipart/alternative, text/plain, image/png) including dispositions and filenames.Envelope
--------
From: James Hillyerd <james@makita.skynet>
To: greg@nobody.com
Subject: MIME test 1
Body Text
---------
Test of text section
Body HTML
---------
Test of HTML section
Attachment List
---------------
MIME Part Tree
--------------
multipart/alternative
|-- text/plain
`-- multipart/related
|-- text/html
`-- image/png, disposition: inline, filename: "favicon.png"The mime-dump utility is used to debug enmime parsing by converting an email file into a human-readable Markdown document. This document describes the email's envelope, body text, body HTML, attachments, and the MIME part tree structure.
# Build the utility
go build
# Run it against an email file
./mime-dump ../test-data/mail/html-mime-inline.rawThe ReadPartErrorPolicy type allows you to define how the parser should behave when an error occurs while reading a Part's content. The policy function receives the *Part and the error, returning a bool that indicates whether the parser should attempt to recover (e.g., by using partial content).
// Example of a policy that recovers from corrupt base64 in text parts
policy := enmime.AllowCorruptTextPartErrorPolicy
// Apply it during parser creation
parser := enmime.NewParser(enmime.WithReadPartErrorPolicy(policy))When Build() is called, MailBuilder automatically determines the most efficient MIME structure based on the provided content. It builds a tree of Part structs following this hierarchy:
multipart/mixed (Root)multipart/relatedmultipart/alternativetext/plaintext/htmlContent-ID)If only text/plain or text/html is provided, the tree is simplified. If both are provided, they are wrapped in a multipart/alternative container.
The Sender interface defines the contract for sending MIME messages. Implementing this interface allows you to swap out different delivery mechanisms (like SMTP, SendGrid, or a mock sender for testing) while keeping your message construction logic decoupled from the transport layer.
To send a message, call Send with:
reversePath: The email address used for delivery error reporting (the MAIL FROM command in SMTP).recipients: A slice of strings containing the destination email addresses.msg: The raw byte slice of the MIME message (including headers like From, To, and Subject).Note on BCC: To send a BCC message, include the recipient's address in the recipients slice but omit it from the msg headers.
// Example of the Sender interface signature
type Sender interface {
Send(reversePath string, recipients []string, msg []byte) error
}When calling Encode, the library automatically selects the Content-Transfer-Encoding (CTE) using the following logic:
ContentType starts with message/, it uses 8bit (per RFC 1341).quoted-printable. If the density of non-ASCII characters exceeds a threshold (20%), it switches to base64.base64 for non-text content.rawContent enabled, it uses teRaw (no encoding).This logic ensures that the resulting MIME message is as efficient as possible while remaining compliant with RFC standards.
The MailBuilder provides a fluent, immutable-style interface for constructing complex MIME messages. Each manipulation method returns a copy of the MailBuilder, allowing you to chain calls. This design makes the builder thread-safe for reuse if the underlying data is not modified externally.
To use it, start with enmime.Builder(), chain your configuration methods (like From, To, Subject, Text, HTML, etc.), and finally call Build() to generate a *Part tree or Send() to transmit the message.
package main
import (
"github.com/jhillyerd/enmime/v2"
)
func main() {
builder := enmime.Builder().
From("Sender Name", "sender@example.com").
To("Recipient", "recipient@example.com").
Subject("Hello World").
Text([]byte("This is the plain text body")).
HTML([]byte("<h1>This is the HTML body</h1>"))
part, err := builder.Build()
if err != nil {
panic(err)
}
// Use the resulting *Part tree...
}To parse a MIME email message, use ReadEnvelope(r io.Reader). This function reads the content from the provided reader and returns an *Envelope.
An Envelope is a simplified wrapper that automatically:
text/plain part is present (unless configured otherwise).Attachments, Inlines, and OtherParts based on their Content-Disposition.Errors slice.If you need to use specific parser configurations, use the Parser.ReadEnvelope(r io.Reader) method instead of the package-level ReadEnvelope.
import "github.com/jhillyerd/enmime/v2"
// ...
// r is an io.Reader containing the raw MIME message
envelope, err := enmime.ReadEnvelope(r)
if err != nil {
// handle error
}
// Access content
fmt.Println(envelope.Text)
fmt.Println(envelope.HTML)
for _, attachment := range envelope.Attachments {
fmt.Println("Attachment found:", attachment.Header.Get("Content-Disposition"))
}The MailBuilder captures errors during the construction process (specifically during file I/O in AddFileAttachment, AddFileInline, or AddFileOtherPart).
If an error occurs during a file operation, subsequent builder calls will be ignored, and the error will be stored. You must check for this error using the Error() method before calling Build() or Send().
builder := enmime.Builder().AddFileAttachment("missing.txt")
if err := builder.Error(); err != nil {
// Handle the error
}The AllowCorruptTextPartErrorPolicy is a built-in error policy designed to recover partial content when encountering a base64.CorruptInputError, specifically when the part's ContentType is text/plain or text/html. This is useful for handling slightly malformed text-based MIME parts without failing the entire parsing process.
// Use this policy to allow the parser to continue even if text parts have base64 corruption
parser := enmime.NewParser(enmime.WithReadPartErrorPolicy(enmime.AllowCorruptTextPartErrorPolicy))TextContent() bool method returns true if the part's ContentType indicates it is text-based (e.g., starts with text/ or is a multipart/ type). This is used to determine appropriate content transfer encoding schemes. If ContentType is empty, it is treated as text/plain; charset=us-ascii per RFC 2045.