Documentation ¶
Overview ¶
Package enmime implements a MIME parsing library for Go. It's built on top of Go's included mime/multipart support, 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. Each Part implements io.Reader, providing access to the content it represents. If the part was encoded in quoted-printable or base64, it is decoded prior to being accessed by the Reader.
If you need to locate a particular Part, you can 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.
The Envelope ¶
EnvelopeFromMessage 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 downconverted using the html2text library1. The root of the Part tree, as well as slices of the inline and attachment Parts are also available.
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
Example ¶
package main import ( "fmt" "os" "github.com/jhillyerd/enmime" ) func main() { // Open a sample message file r, err := os.Open("testdata/mail/qp-utf8-header.raw") if err != nil { fmt.Print(err) return } // Parse message body with enmime env, err := enmime.ReadEnvelope(r) if err != nil { fmt.Print(err) return } // Headers can be retrieved via Envelope.GetHeader(name) fmt.Printf("From: %v\n", env.GetHeader("From")) // Address-type headers can be parsed into a list of decoded mail.Address structs alist, _ := env.AddressList("To") for _, addr := range alist { fmt.Printf("To: %s <%s>\n", addr.Name, addr.Address) } // enmime can decode quoted-printable headers fmt.Printf("Subject: %v\n", env.GetHeader("Subject")) // The plain text body is available as mime.Text fmt.Printf("Text Body: %v chars\n", len(env.Text)) // The HTML body is stored in mime.HTML fmt.Printf("HTML Body: %v chars\n", len(env.HTML)) // mime.Inlines is a slice of inlined attacments fmt.Printf("Inlines: %v\n", len(env.Inlines)) // mime.Attachments contains the non-inline attachments fmt.Printf("Attachments: %v\n", len(env.Attachments)) }
Output: From: James Hillyerd <jamehi03@jamehi03lx.noa.com> To: Mirosław Marczak <marczak@inbucket.com> Subject: MIME UTF8 Test ¢ More Text Text Body: 1300 chars HTML Body: 1736 chars Inlines: 0 Attachments: 0
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var AddressHeaders = map[string]bool{ "bcc": true, "cc": true, "delivered-to": true, "from": true, "reply-to": true, "to": true, }
AddressHeaders is the set of SMTP headers that contain email addresses, used by Envelope.AddressList(). Key characters must be all lowercase.
Functions ¶
This section is empty.
Types ¶
type Envelope ¶
type Envelope struct { Text string // The plain text portion of the message HTML string // The HTML portion of the message Root *Part // The top-level Part Attachments []*Part // All parts having a Content-Disposition of attachment Inlines []*Part // All parts having a Content-Disposition of inline OtherParts []*Part // All parts not in Attachments and Inlines Errors []*Error // Errors encountered while parsing // contains filtered or unexported fields }
Envelope is a simplified wrapper for MIME email messages.
func EnvelopeFromPart ¶
EnvelopeFromPart uses the provided Part tree to build an Envelope,, downconverting HTML to plain text if needed, and sorting the attachments, inlines and other parts into their respective slices.
func ReadEnvelope ¶
ReadEnvelope parses the content of the provided reader into an Envelope, downconverting HTML to plain text if needed, and sorting the attachments, inlines and other parts into their respective slices.
func (*Envelope) AddressList ¶
AddressList returns a mail.Address slice with RFC 2047 encoded names converted to UTF-8
type Error ¶
type Error struct { Name string // The name or type of error encountered Detail string // Additional detail about the cause of the error, if available Severe bool // Indicates that a portion of the message was lost during parsing }
Error describes an error encountered while parsing.
type Part ¶
type Part struct { Header textproto.MIMEHeader // Header for this Part Parent *Part // Parent of this part (can be nil) FirstChild *Part // FirstChild is the top most child of this part NextSibling *Part // NextSibling of this part ContentType string // ContentType header without parameters Disposition string // Content-Disposition header without parameters FileName string // The file-name from disposition or type header Charset string // The content charset encoding label Errors []Error // Errors encountered while parsing this part // contains filtered or unexported fields }
Part is the primary structure enmine clients will interact with. Each Part represents a node in the MIME multipart tree. The Content-Type, Disposition and File Name are parsed out of the header for easier access.
func NewPart ¶
NewPart creates a new Part object. It does not update the parents FirstChild attribute.
func ReadParts ¶
ReadParts reads a MIME document from the provided reader and parses it into tree of Part objects.
func (*Part) BreadthMatchAll ¶
func (p *Part) BreadthMatchAll(matcher PartMatcher) []*Part
BreadthMatchAll performs a breadth first search of the Part tree and returns all parts that cause the given matcher to return true
func (*Part) BreadthMatchFirst ¶
func (p *Part) BreadthMatchFirst(matcher PartMatcher) *Part
BreadthMatchFirst performs a breadth first search of the Part tree and returns the first part that causes the given matcher to return true
func (*Part) DepthMatchAll ¶
func (p *Part) DepthMatchAll(matcher PartMatcher) []*Part
DepthMatchAll performs a depth first search of the Part tree and returns all parts that causes the given matcher to return true
func (*Part) DepthMatchFirst ¶
func (p *Part) DepthMatchFirst(matcher PartMatcher) *Part
DepthMatchFirst performs a depth first search of the Part tree and returns the first part that causes the given matcher to return true
type PartMatcher ¶
PartMatcher is a function type that you must implement to search for Parts using the BreadthMatch* functions. Implementators should inspect the provided Part and return true if it matches your criteria.
Source Files ¶
Directories ¶
Path | Synopsis |
---|---|
mime-dump
Package main outputs a markdown formatted document describing the provided email
|
Package main outputs a markdown formatted document describing the provided email |
mime-extractor
Package main extracts attachments from the provided email
|
Package main extracts attachments from the provided email |