58 lines
2.9 KiB
Go
58 lines
2.9 KiB
Go
// Package enmime implements a MIME encoding and decoding library. It's built on top of Go's
|
|
// included mime/multipart support where possible, but is geared towards parsing MIME encoded
|
|
// emails.
|
|
//
|
|
// Overview
|
|
//
|
|
// The enmime API has two conceptual layers. The lower layer is a tree of Part structs,
|
|
// representing each component of a decoded MIME message. The upper layer, called an Envelope
|
|
// provides an intuitive way to interact with a MIME message.
|
|
//
|
|
// Part Tree
|
|
//
|
|
// Calling ReadParts causes enmime to parse the body of a MIME message into a tree of Part objects,
|
|
// each of which is aware of its content type, filename and headers. The content of a Part is
|
|
// available as a slice of bytes via the Content field.
|
|
//
|
|
// If the part was encoded in quoted-printable or base64, it is decoded prior to being placed in
|
|
// Content. If the Part contains text in a character set other than utf-8, enmime will attempt to
|
|
// convert it to utf-8.
|
|
//
|
|
// To locate a particular Part, pass a custom PartMatcher function into the BreadthMatchFirst() or
|
|
// DepthMatchFirst() methods to search the Part tree. BreadthMatchAll() and DepthMatchAll() will
|
|
// collect all Parts matching your criteria.
|
|
//
|
|
// Envelope
|
|
//
|
|
// ReadEnvelope returns an Envelope struct. Behind the scenes a Part tree is constructed, and then
|
|
// sorted into the correct fields of the Envelope.
|
|
//
|
|
// The Envelope contains both the plain text and HTML portions of the email. If there was no plain
|
|
// text Part available, the HTML Part will be down-converted using the html2text library[1]. The
|
|
// root of the Part tree, as well as slices of the inline and attachment Parts are also available.
|
|
//
|
|
// Headers
|
|
//
|
|
// Every MIME Part has its own headers, accessible via the Part.Header field. The raw headers for
|
|
// an Envelope are available in Root.Header. Envelope also provides helper methods to fetch
|
|
// headers: GetHeader(key) will return the RFC 2047 decoded value of the specified header.
|
|
// AddressList(key) will convert the specified address header into a slice of net/mail.Address
|
|
// values.
|
|
//
|
|
// Errors
|
|
//
|
|
// enmime attempts to be tolerant of poorly encoded MIME messages. In situations where parsing is
|
|
// not possible, the ReadEnvelope and ReadParts functions will return a hard error. If enmime is
|
|
// able to continue parsing the message, it will add an entry to the Errors slice on the relevant
|
|
// Part. After parsing is complete, all Part errors will be appended to the Envelope Errors slice.
|
|
// The Error* constants can be used to identify a specific class of error.
|
|
//
|
|
// Please note that enmime parses messages into memory, so it is not likely to perform well with
|
|
// multi-gigabyte attachments.
|
|
//
|
|
// enmime is open source software released under the MIT License. The latest version can be found
|
|
// at https://github.com/jhillyerd/enmime
|
|
//
|
|
// [1]: https://github.com/jaytaylor/html2text
|
|
package enmime // import "github.com/jhillyerd/enmime"
|