enmime: github.com/jhillyerd/enmime Index | Examples | Files | Directories

package enmime

import "github.com/jhillyerd/enmime"

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

Index

Examples

Package Files

boundary.go builder.go detect.go encode.go enmime.go envelope.go error.go header.go match.go part.go

Constants

const (
    // ErrorMalformedBase64 name.
    ErrorMalformedBase64 = "Malformed Base64"
    // ErrorMalformedHeader name.
    ErrorMalformedHeader = "Malformed Header"
    // ErrorMissingBoundary name.
    ErrorMissingBoundary = "Missing Boundary"
    // ErrorMissingContentType name.
    ErrorMissingContentType = "Missing Content-Type"
    // ErrorCharsetConversion name.
    ErrorCharsetConversion = "Character Set Conversion"
    // ErrorContentEncoding name.
    ErrorContentEncoding = "Content Encoding"
    // ErrorPlainTextFromHTML name.
    ErrorPlainTextFromHTML = "Plain Text from HTML"
    // ErrorCharsetDeclaration name.
    ErrorCharsetDeclaration = "Character Set Declaration Mismatch"
)

Variables

var AddressHeaders = map[string]bool{
    "bcc":             true,
    "cc":              true,
    "delivered-to":    true,
    "from":            true,
    "reply-to":        true,
    "to":              true,
    "sender":          true,
    "resent-bcc":      true,
    "resent-cc":       true,
    "resent-from":     true,
    "resent-reply-to": true,
    "resent-to":       true,
    "resent-sender":   true,
}

AddressHeaders is the set of SMTP headers that contain email addresses, used by Envelope.AddressList(). Key characters must be all lowercase.

func ParseMediaType Uses

func ParseMediaType(ctype string) (mtype string, params map[string]string, invalidParams []string, err error)

ParseMediaType is a more tolerant implementation of Go's mime.ParseMediaType function.

Tolerances accounted for:

* Missing ';' between content-type and media parameters
* Repeating media parameters
* Unquoted values in media parameters containing 'tspecials' characters

type Envelope Uses

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
    // All non-text parts that were not placed in Attachments or Inlines, such as multipart/related
    // content.
    OtherParts []*Part
    Errors     []*Error // Errors encountered while parsing
    // contains filtered or unexported fields
}

Envelope is a simplified wrapper for MIME email messages.

ExampleEnvelope demonstrates the relationship between Envelope and Parts.

Code:

// Create sample message in memory
raw := `From: user@inbucket.org
Subject: Example message
Content-Type: multipart/alternative; boundary=Enmime-100

--Enmime-100
Content-Type: text/plain
X-Comment: part1

hello!
--Enmime-100
Content-Type: text/html
X-Comment: part2

<b>hello!</b>
--Enmime-100
Content-Type: text/plain
Content-Disposition: attachment;
filename=hi.txt
X-Comment: part3

hello again!
--Enmime-100--
`

// Parse message body with enmime.ReadEnvelope
r := strings.NewReader(raw)
env, err := enmime.ReadEnvelope(r)
if err != nil {
    fmt.Print(err)
    return
}

// The root Part contains the message header, which is also available via the
// Envelope.GetHeader() method.
fmt.Printf("Root Part Subject: %q\n", env.Root.Header.Get("Subject"))
fmt.Printf("Envelope Subject: %q\n", env.GetHeader("Subject"))
fmt.Println()

// The text from part1 is consumed and placed into the Envelope.Text field.
fmt.Printf("Text Content: %q\n", env.Text)

// But part1 is also available as a child of the root Part.  Only the headers may be accessed,
// because the content has been consumed.
part1 := env.Root.FirstChild
fmt.Printf("Part 1 X-Comment: %q\n", part1.Header.Get("X-Comment"))
fmt.Println()

// The HTML from part2 is consumed and placed into the Envelope.HTML field.
fmt.Printf("HTML Content: %q\n", env.HTML)

// And part2 is available as the second child of the root Part. Only the headers may be
// accessed, because the content has been consumed.
part2 := env.Root.FirstChild.NextSibling
fmt.Printf("Part 2 X-Comment: %q\n", part2.Header.Get("X-Comment"))
fmt.Println()

// Because part3 has a disposition of attachment, it is added to the Envelope.Attachments
// slice
fmt.Printf("Attachment 1 X-Comment: %q\n", env.Attachments[0].Header.Get("X-Comment"))

// And is still available as the third child of the root Part
part3 := env.Root.FirstChild.NextSibling.NextSibling
fmt.Printf("Part 3 X-Comment: %q\n", part3.Header.Get("X-Comment"))

// The content of Attachments, Inlines and OtherParts are available as a slice of bytes
fmt.Printf("Part 3 Content: %q\n", part3.Content)

// part3 contained a malformed header line, enmime has attached an Error to it
p3error := part3.Errors[0]
fmt.Println(p3error.Error())
fmt.Println()

// All Part errors are collected and placed into Envelope.Errors
fmt.Println("Envelope errors:")
for _, e := range env.Errors {
    fmt.Println(e.Error())
}

Output:

Root Part Subject: "Example message"
Envelope Subject: "Example message"

Text Content: "hello!"
Part 1 X-Comment: "part1"

HTML Content: "<b>hello!</b>"
Part 2 X-Comment: "part2"

Attachment 1 X-Comment: "part3"
Part 3 X-Comment: "part3"
Part 3 Content: "hello again!"
[W] Malformed Header: Continued line "filename=hi.txt" was not indented

Envelope errors:
[W] Malformed Header: Continued line "filename=hi.txt" was not indented

func EnvelopeFromPart Uses

func EnvelopeFromPart(root *Part) (*Envelope, error)

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. Errors are collected from all Parts and placed into the Envelopes Errors slice.

func ReadEnvelope Uses

func ReadEnvelope(r io.Reader) (*Envelope, error)

ReadEnvelope is a wrapper around ReadParts and EnvelopeFromPart. It 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. Errors are collected from all Parts and placed into the Envelope.Errors slice.

Code:

// 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>, André Pirard <PIRARD@vm1.ulg.ac.be>
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

func (*Envelope) AddHeader Uses

func (e *Envelope) AddHeader(name string, value string) error

AddHeader appends given header value to header name without changing existing values. If the header does not exist already, it will be created.

func (*Envelope) AddressList Uses

func (e *Envelope) AddressList(key string) ([]*mail.Address, error)

AddressList returns a mail.Address slice with RFC 2047 encoded names converted to UTF-8

func (*Envelope) Clone Uses

func (e *Envelope) Clone() *Envelope

Clone returns a clone of the current Envelope

func (*Envelope) DeleteHeader Uses

func (e *Envelope) DeleteHeader(name string) error

DeleteHeader deletes given header.

func (*Envelope) GetHeader Uses

func (e *Envelope) GetHeader(name string) string

GetHeader processes the specified header for RFC 2047 encoded words and returns the result as a UTF-8 string

func (*Envelope) GetHeaderKeys Uses

func (e *Envelope) GetHeaderKeys() (headers []string)

GetHeaderKeys returns a list of header keys seen in this message. Get individual headers with `GetHeader(name)`

Code:

// Open a sample message file.
r, err := os.Open("testdata/mail/qp-utf8-header.raw")
if err != nil {
    fmt.Print(err)
    return
}

// Parse message with enmime.
env, err := enmime.ReadEnvelope(r)
if err != nil {
    fmt.Print(err)
    return
}

// A list of headers is retrieved via Envelope.GetHeaderKeys().
headers := env.GetHeaderKeys()
sort.Sort(sort.StringSlice(headers))

// Print each header, key and value.
for _, header := range headers {
    fmt.Printf("%s: %v\n", header, env.GetHeader(header))
}

Output:

Content-Type: multipart/alternative; boundary="------------020203040006070307010003"
Date: Fri, 19 Oct 2012 12:22:49 -0700
From: James Hillyerd <jamehi03@jamehi03lx.noa.com>, André Pirard <PIRARD@vm1.ulg.ac.be>
Message-Id: <5081A889.3020108@jamehi03lx.noa.com>
Mime-Version: 1.0
Sender: André Pirard <PIRARD@vm1.ulg.ac.be>
Subject: MIME UTF8 Test ¢ More Text
To: Mirosław Marczak <marczak@inbucket.com>
User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:16.0) Gecko/20121010 Thunderbird/16.0.1

func (*Envelope) GetHeaderValues Uses

func (e *Envelope) GetHeaderValues(name string) []string

GetHeaderValues processes the specified header for RFC 2047 encoded words and returns all existing values as a list of UTF-8 strings

func (*Envelope) SetHeader Uses

func (e *Envelope) SetHeader(name string, value []string) error

SetHeader sets given header name to the given value. If the header exists already, all existing values are replaced.

type Error Uses

type Error struct {
    Name   string // The name or type of error encountered, from Error consts.
    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.

func (*Error) Error Uses

func (e *Error) Error() string

Error formats the enmime.Error as a string.

func (*Error) String Uses

func (e *Error) String() string

String formats the enmime.Error as a string. DEPRECATED; use Error() instead.

type MailBuilder Uses

type MailBuilder struct {
    // contains filtered or unexported fields
}

MailBuilder facilitates the easy construction of a MIME message. Each manipulation method returns a copy of the receiver struct. It can be considered immutable if the caller does not modify the string and byte slices passed in. Immutability allows the headers or entire message to be reused across multiple threads.

func Builder Uses

func Builder() MailBuilder

Builder returns an empty MailBuilder struct.

ExampleBuilder illustrates how to build and send a MIME encoded message.

Code:

smtpHost := "smtp.relay.host:25"
smtpAuth := smtp.PlainAuth("", "user", "pw", "host")

// MailBuilder is (mostly) immutable, each method below returns a new MailBuilder without
// modifying the original.
master := enmime.Builder().
    From("Do Not Reply", "noreply@inbucket.org").
    Subject("Inbucket Newsletter").
    Text([]byte("Text body")).
    HTML([]byte("<p>HTML body</p>"))

// master is immutable, causing each msg below to have a single recipient.
msg := master.To("Esteemed Customer", "user1@inbucket.org")
msg.Send(smtpHost, smtpAuth)

msg = master.To("Another Customer", "user2@inbucket.org")
msg.Send(smtpHost, smtpAuth)

func (MailBuilder) AddAttachment Uses

func (p MailBuilder) AddAttachment(b []byte, contentType string, fileName string) MailBuilder

AddAttachment returns a copy of MailBuilder that includes the specified attachment.

func (MailBuilder) AddFileAttachment Uses

func (p MailBuilder) AddFileAttachment(path string) MailBuilder

AddFileAttachment returns a copy of MailBuilder that includes the specified attachment. fileName, will be populated from the base name of path. Content type will be detected from the path extension.

func (MailBuilder) AddFileInline Uses

func (p MailBuilder) AddFileInline(path string) MailBuilder

AddFileInline returns a copy of MailBuilder that includes the specified inline. fileName and contentID will be populated from the base name of path. Content type will be detected from the path extension.

func (MailBuilder) AddInline Uses

func (p MailBuilder) AddInline(
    b []byte,
    contentType string,
    fileName string,
    contentID string,
) MailBuilder

AddInline returns a copy of MailBuilder that includes the specified inline. fileName and contentID may be left empty.

func (MailBuilder) BCC Uses

func (p MailBuilder) BCC(name, addr string) MailBuilder

BCC returns a copy of MailBuilder with this name & address appended to the BCC list. name may be empty. This method only has an effect if the Send method is used to transmit the message, there is no effect on the parts returned by Build().

func (MailBuilder) BCCAddrs Uses

func (p MailBuilder) BCCAddrs(bcc []mail.Address) MailBuilder

BCCAddrs returns a copy of MailBuilder with the specified as the blind CC list. This method only has an effect if the Send method is used to transmit the message, there is no effect on the parts returned by Build().

func (MailBuilder) Build Uses

func (p MailBuilder) Build() (*Part, error)

Build performs some basic validations, then constructs a tree of Part structs from the configured MailBuilder. It will set the Date header to now if it was not explicitly set.

func (MailBuilder) CC Uses

func (p MailBuilder) CC(name, addr string) MailBuilder

CC returns a copy of MailBuilder with this name & address appended to the CC header. name may be empty.

func (MailBuilder) CCAddrs Uses

func (p MailBuilder) CCAddrs(cc []mail.Address) MailBuilder

CCAddrs returns a copy of MailBuilder with the specified CC addresses.

func (MailBuilder) Date Uses

func (p MailBuilder) Date(date time.Time) MailBuilder

Date returns a copy of MailBuilder with the specified Date header.

func (MailBuilder) Equals Uses

func (p MailBuilder) Equals(o MailBuilder) bool

Equals uses the reflect package to test two MailBuilder structs for equality, primarily for unit tests.

func (MailBuilder) Error Uses

func (p MailBuilder) Error() error

Error returns the stored error from a file attachment/inline read or nil.

func (MailBuilder) From Uses

func (p MailBuilder) From(name, addr string) MailBuilder

From returns a copy of MailBuilder with the specified From header.

func (MailBuilder) HTML Uses

func (p MailBuilder) HTML(body []byte) MailBuilder

HTML returns a copy of MailBuilder that will use the provided bytes for its text/html Part.

func (MailBuilder) Header Uses

func (p MailBuilder) Header(name, value string) MailBuilder

Header returns a copy of MailBuilder with the specified value added to the named header.

func (MailBuilder) ReplyTo Uses

func (p MailBuilder) ReplyTo(name, addr string) MailBuilder

ReplyTo returns a copy of MailBuilder with this name & address appended to the To header. name may be empty.

func (MailBuilder) Send Uses

func (p MailBuilder) Send(addr string, a smtp.Auth) error

Send encodes the message and sends it via the SMTP server specified by addr. Send uses net/smtp.SendMail, and accepts the same authentication parameters.

func (MailBuilder) Subject Uses

func (p MailBuilder) Subject(subject string) MailBuilder

Subject returns a copy of MailBuilder with the specified Subject header.

func (MailBuilder) Text Uses

func (p MailBuilder) Text(body []byte) MailBuilder

Text returns a copy of MailBuilder that will use the provided bytes for its text/plain Part.

func (MailBuilder) To Uses

func (p MailBuilder) To(name, addr string) MailBuilder

To returns a copy of MailBuilder with this name & address appended to the To header. name may be empty.

func (MailBuilder) ToAddrs Uses

func (p MailBuilder) ToAddrs(to []mail.Address) MailBuilder

ToAddrs returns a copy of MailBuilder with the specified To addresses.

type Part Uses

type Part struct {
    PartID      string               // PartID labels this parts position within the tree.
    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.
    Header      textproto.MIMEHeader // Header for this Part.

    Boundary    string    // Boundary marker used within this part.
    ContentID   string    // ContentID header for cid URL scheme.
    ContentType string    // ContentType header without parameters.
    Disposition string    // Content-Disposition header without parameters.
    FileName    string    // The file-name from disposition or type header.
    FileModDate time.Time // The modification date of the file.
    Charset     string    // The content charset encoding, may differ from charset in header.
    OrigCharset string    // The original content charset when a different charset was detected.

    Errors   []*Error // Errors encountered while parsing this part.
    Content  []byte   // Content after decoding, UTF-8 conversion if applicable.
    Epilogue []byte   // Epilogue contains data following the closing boundary marker.
}

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 Uses

func NewPart(contentType string) *Part

NewPart creates a new Part object.

func ReadParts Uses

func ReadParts(r io.Reader) (*Part, error)

ReadParts reads a MIME document from the provided reader and parses it into tree of Part objects.

func (*Part) AddChild Uses

func (p *Part) AddChild(child *Part)

AddChild adds a child part to either FirstChild or the end of the children NextSibling chain. The child may have siblings and children attached. This method will set the Parent field on child and all its siblings. Safe to call on nil.

func (*Part) BreadthMatchAll Uses

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 Uses

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) Clone Uses

func (p *Part) Clone(parent *Part) *Part

Clone returns a clone of the current Part.

func (*Part) DepthMatchAll Uses

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 Uses

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

func (*Part) Encode Uses

func (p *Part) Encode(writer io.Writer) error

Encode writes this Part and all its children to the specified writer in MIME format.

func (*Part) TextContent Uses

func (p *Part) TextContent() bool

TextContent indicates whether the content is text based on its content type. This value determines what content transfer encoding scheme to use.

type PartMatcher Uses

type PartMatcher func(part *Part) bool

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.

Directories

PathSynopsis
cmd
cmd/mime-dumpPackage main outputs a markdown formatted document describing the provided email
cmd/mime-extractorPackage main extracts attachments from the provided email
internal/coding
internal/stringutil
internal/test

Package enmime imports 26 packages (graph) and is imported by 23 packages. Updated 2019-08-11. Refresh now. Tools for package owners.