enmime

README

enmime

enmime is a MIME parsing library for Go. It's built ontop of Go's included mime/multipart support, but is geared towards parsing MIME encoded emails.

It is being developed in tandem with the Inbucket email service.

API documentation can be found here: http://godoc.org/github.com/jhillyerd/go.enmime

Development Status

enmime is alpha quality: it works but has not been tested with a wide variety of source data, and it's likely the API will evolve some before an official release.

About

enmime is written in Google Go.

enmime is open source software released under the MIT License. The latest version can be found at https://github.com/jhillyerd/go.enmime

Documentation

Overview

Package enmime implements a MIME parsing library for Go. It's built ontop of Go's included mime/multipart support, but is geared towards parsing MIME encoded emails.

Example usage:

package main

import (
	"fmt"
	"github.com/jhillyerd/go.enmime"
	"net/mail"
	"os"
)

func main() {
	f, _ := os.Open(os.Args[1])
	msg, _ := mail.ReadMessage(f)           // Read email using Go's net/mail
	mime, _ := enmime.ParseMIMEBody(msg)    // Parse message body with enmime

	fmt.Printf("Subject: %v\n",             // Headers are in the net/mail msg
		msg.Header.Get("Subject"))
	fmt.Printf("----\n%v\n", mime.Text)     // Display the plain text body

	// List the attachments
	fmt.Printf("----\nAttachments:\n")
	for _, a := range mime.Attachments {
		fmt.Printf("- %v (%v)\n", a.FileName(), a.ContentType())
	}
}

The basics:

Calling ParseMIMEBody causes enmime to parse the body of the message object into a tree of MIMEPart objects, each of which is aware of its content type, filename and headers. If the part was encoded in quoted-printable or base64, it is decoded before being stored in the MIMEPart object.

ParseMIMEBody returns a MIMEBody struct. The struct contains both the plain text and HTML portions of the email (if available). The root of the tree, as well as slices of the email's inlines and attachments are available in the struct.

If you need to locate a particular MIMEPart, you can pass a custom MIMEPartMatcher function into the BreadthMatchFirst() to search the MIMEPart tree. BreadthMatchAll() will collect all matching parts.

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/go.enmime

Index

• func IsMultipartMessage(mailMsg *mail.Message) bool
• func NewMIMEPart(parent MIMEPart, contentType string) *memMIMEPart
• type Base64Cleaner
  • func NewBase64Cleaner(r io.Reader) *Base64Cleaner
  • func (qp *Base64Cleaner) Read(p []byte) (n int, err error)
• type MIMEBody
  • func ParseMIMEBody(mailMsg *mail.Message) (*MIMEBody, error)
  • func (m *MIMEBody) GetHeader(name string) string
• type MIMEPart
  • func BreadthMatchAll(p MIMEPart, matcher MIMEPartMatcher) []MIMEPart
  • func BreadthMatchFirst(p MIMEPart, matcher MIMEPartMatcher) MIMEPart
  • func DepthMatchAll(p MIMEPart, matcher MIMEPartMatcher) []MIMEPart
  • func DepthMatchFirst(p MIMEPart, matcher MIMEPartMatcher) MIMEPart
  • func ParseMIME(reader *bufio.Reader) (MIMEPart, error)
• type MIMEPartMatcher

Functions

func IsMultipartMessage

func IsMultipartMessage(mailMsg *mail.Message) bool

IsMultipartMessage returns true if the message has a recognized multipart Content-Type header. You don't need to check this before calling ParseMIMEBody, it can handle non-multipart messages.

func NewMIMEPart

func NewMIMEPart(parent MIMEPart, contentType string) *memMIMEPart

NewMIMEPart creates a new memMIMEPart object. It does not update the parents FirstChild attribute.

Types

type Base64Cleaner

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

Base64Cleaner helps work around bugs in Go's built-in base64 decoder by stripping out whitespace that would cause Go to lose count of things and issue an "illegal base64 data at input byte..." error

func NewBase64Cleaner

func NewBase64Cleaner(r io.Reader) *Base64Cleaner

NewBase64Cleaner returns a Base64Cleaner object for the specified reader. Base64Cleaner implements the io.Reader interface.

func (*Base64Cleaner) Read

func (qp *Base64Cleaner) Read(p []byte) (n int, err error)

Read method for io.Reader interface.

type MIMEBody

type MIMEBody struct {
	Text        string     // The plain text portion of the message
	Html        string     // The HTML portion of the message
	Root        MIMEPart   // The top-level MIMEPart
	Attachments []MIMEPart // All parts having a Content-Disposition of attachment
	Inlines     []MIMEPart // All parts having a Content-Disposition of inline
	// contains filtered or unexported fields
}

MIMEBody is the outer wrapper for MIME messages.

func ParseMIMEBody

func ParseMIMEBody(mailMsg *mail.Message) (*MIMEBody, error)

ParseMIMEBody parses the body of the message object into a tree of MIMEPart objects, each of which is aware of its content type, filename and headers. If the part was encoded in quoted-printable or base64, it is decoded before being stored in the MIMEPart object.

func (*MIMEBody) GetHeader

func (m *MIMEBody) GetHeader(name string) string

Process the specified header for RFC 2047 encoded words and return the result

type MIMEPart

type MIMEPart interface {
	Parent() MIMEPart             // Parent of this part (can be nil)
	FirstChild() MIMEPart         // First (top most) child of this part
	NextSibling() MIMEPart        // Next sibling of this part
	Header() textproto.MIMEHeader // Header as parsed by textproto package
	ContentType() string          // Content-Type header without parameters
	Disposition() string          // Content-Disposition header without parameters
	FileName() string             // File Name from disposition or type header
	Content() []byte              // Decoded content of this part (can be empty)
}

MIMEPart is the primary interface enmine clients will use. Each MIMEPart represents a node in the MIME multipart tree. The Content-Type, Disposition and File Name are parsed out of the header for easier access.

TODO Content should probably be a reader so that it does not need to be stored in memory.

func BreadthMatchAll

func BreadthMatchAll(p MIMEPart, matcher MIMEPartMatcher) []MIMEPart

BreadthMatchAll performs a breadth first search of the MIMEPart tree and returns all parts that cause the given matcher to return true

func BreadthMatchFirst

func BreadthMatchFirst(p MIMEPart, matcher MIMEPartMatcher) MIMEPart

BreadthMatchFirst performs a breadth first search of the MIMEPart tree and returns the first part that causes the given matcher to return true

func DepthMatchAll

func DepthMatchAll(p MIMEPart, matcher MIMEPartMatcher) []MIMEPart

DepthMatchAll performs a depth first search of the MIMEPart tree and returns all parts that causes the given matcher to return true

func DepthMatchFirst

func DepthMatchFirst(p MIMEPart, matcher MIMEPartMatcher) MIMEPart

DepthMatchFirst performs a depth first search of the MIMEPart tree and returns the first part that causes the given matcher to return true

func ParseMIME

func ParseMIME(reader *bufio.Reader) (MIMEPart, error)

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

type MIMEPartMatcher

type MIMEPartMatcher func(part MIMEPart) bool

MIMEPartMatcher is a function type that you must implement to search for MIMEParts using the BreadthMatch* functions. Implementators should inspect the provided MIMEPart and return true if it matches your criteria.