email

README

email

A GO library for the creation of email messages.

Design philosofies

Normal action should be easy and somewhat fool-proof, advanced actions must be possible, but are not necessary fool-proof. As an example, the format of the "to" header is strictly checked, but not all (obscure) headers are checked if they conform the rfc5322

Standards

• Following RFC standards where possible
• Following common practices when in line with RFC's
• Following common practices when not line with RFC's only when necessary

Code

• Targeting Go 1.2 or later
• No dependencies outside Go standard lib
• Fully tested
• Following the Go style guide and common practices
• Possibly in line with parsing packages in net/mail and mime

Scope

• Only creation of messages and exporting them to bytes or writer
• Sending (with smtp or other method) is explicitly not in scope. It might come later in another (sub)-package

Target example cases

• Send a text email to the linux kernel mailing list with patch as inline attachment
• Send a registration email in both html and text
• Send an email with pictures "inline"
• Send an email with pictures as attachments

Other Go email packages

This is a list of other Go packages that aim to do similar things. Some of these are used for inspiration. Any critism mentioned with the package is just meant as a warning to self to avoid similar pitfalls.

https://github.com/jpoehls/gophermail

Does not wrap subject header. Contains unnecessary parts in body

https://github.com/go-gomail/gomail

Does not export complete message directly (tight integration with sending mail). Requires Go 1.3

https://github.com/jordan-wright/email

Does not wrap or encode subject header

Documentation

Overview

Package email is for the construction of email messages.

The defaults of this package are to create RFC5322 compliant messages that are accepted and usable by the majority of existing, popular email clients.

Index

• Variables
• type Email
  • func New(subject string, from mail.Address, to ...mail.Address) *Email
  • func (e *Email) AddBcc(a ...mail.Address)
  • func (e *Email) AddCc(a ...mail.Address)
  • func (e *Email) AddHTMLBody(r io.Reader) error
  • func (e *Email) AddHeader(key, value string) error
  • func (e *Email) AddTextBody(r io.Reader) error
  • func (e *Email) AddTextBodyString(s string) error
  • func (e *Email) AddTo(a ...mail.Address)
  • func (e *Email) Bytes(m Mode) ([]byte, error)
  • func (e *Email) WriteTo(w io.Writer, m Mode) error
• type MIME
• type MIMEMultipart
  • func (p *MIMEMultipart) WriteTo(w io.Writer, m Mode) error
• type MIMEPartBinary
  • func (p *MIMEPartBinary) WriteTo(w io.Writer, m Mode) error
• type MIMEPartText
  • func (p *MIMEPartText) WriteTo(w io.Writer, m Mode) error
• type Mode

Variables

var (
	ErrFromRequired    = errors.New("email: From is required")
	ErrInvalidMimeTree = errors.New("email: Ambigious MIME tree for inserting text or attachment")
	ErrNoBody          = errors.New("email: body is missing")
)

var BoundaryGenerator = func(p *MIMEMultipart) string {
	return "boundary"
}

Function to generate a boundary for a multipart message

var MessageIDGenerator = func(p *Email) string {
	return "messageid"
}

Function to generate message ids

Types

type Email

type Email struct {
	From                 mail.Address
	To, Cc, Bcc, ReplyTo []mail.Address

	// Defaults to Now
	Date    time.Time
	Subject string

	// This will be auto generated if not provided
	MessageId string

	// Optional headers
	Headers textproto.MIMEHeader

	// Actual message
	Message MIME
}

An email contains all field needing for constructing the message. The actual message is a tree of email (MIME) parts.

func New

func New(subject string, from mail.Address, to ...mail.Address) *Email

Create a new email with the required and most important headers filled.

func (*Email) AddBcc

func (e *Email) AddBcc(a ...mail.Address)

Add BCC-receipient

func (*Email) AddCc

func (e *Email) AddCc(a ...mail.Address)

Add CC-receipient

func (*Email) AddHTMLBody

func (e *Email) AddHTMLBody(r io.Reader) error

func (*Email) AddHeader

func (e *Email) AddHeader(key, value string) error

Add a header to the message. These headers are not validated, and headers that are represented in another field are throwing an error.

func (*Email) AddTextBody

func (e *Email) AddTextBody(r io.Reader) error

Add a text body to this message. The text must be UTF-8. Adding multiple text bodies is not recommended, but will not throw an error.

func (*Email) AddTextBodyString

func (e *Email) AddTextBodyString(s string) error

Add a text body to this message. The text must be UTF-8. Adding multiple text bodies is not recommended, but will not throw an error.

func (*Email) AddTo

func (e *Email) AddTo(a ...mail.Address)

Add To-receipient

func (*Email) Bytes

func (e *Email) Bytes(m Mode) ([]byte, error)

Export this emails to a byte string. It calls ToWriter.

func (*Email) WriteTo

func (e *Email) WriteTo(w io.Writer, m Mode) error

Write this email to a writer. The mode determines what is the most liberal encoding the connection accepts. E.g. in case of 8-bit, binary objects will be base64-encoded and in case of 7-bit, utf8-text will be encoded as quoted-printable

type MIME

type MIME interface {
	WriteTo(w io.Writer, m Mode) error
}

type MIMEMultipart

type MIMEMultipart struct {
	Type     string
	Headers  textproto.MIMEHeader
	Boundary string
	Parts    []MIME
}

func (*MIMEMultipart) WriteTo

func (p *MIMEMultipart) WriteTo(w io.Writer, m Mode) error

type MIMEPartBinary

type MIMEPartBinary struct {
	Type        string
	Disposition string
	Headers     textproto.MIMEHeader
	Content     io.Reader
}

func (*MIMEPartBinary) WriteTo

func (p *MIMEPartBinary) WriteTo(w io.Writer, m Mode) error

type MIMEPartText

type MIMEPartText struct {
	Type        string
	Disposition string
	Headers     textproto.MIMEHeader
	Content     *bytes.Buffer
	Charset     string
}

func (*MIMEPartText) WriteTo

func (p *MIMEPartText) WriteTo(w io.Writer, m Mode) error

type Mode

type Mode int

The mode determines the maximum output encoding, 7Bit, 8Bit or Binary. See also MIME.WriteTo()

const (
	Mode7Bit Mode = iota
	Mode8Bit
	ModeBinary
)