goemail

README

Go-email

Craft MIME comformant emails in Go

Install

go get github.com/jimtsao/go-email

Usage

General usage

m := goemail.New()
m.From = "alice@example.com"
m.To = `Bob <bob@example.com>`
m.Bcc = `"Eve the eavesdropper" <eve@example.com>`
m.Subject = "Secret Plans"
m.Body = "<b>Attack at Dawn!</b>"
m.AddHeader(header.MessageID("<local@host.com>"))

// header validation
err := m.Validate()
if len(err) > 0 {
    // handle errors
}

raw := m.Raw()
// use in gmail api, aws ses etc

Custom email

headers := []header.Header{
    header.MIMEVersion{},
    header.Address{Field: header.AddressFrom, Value: "alice@example.com"},
    header.Address{Field: header.AddressTo, Value: "Bob <bob@example.com>"},
    header.Subject("Secret Plan"),
    header.MessageID("<local@host.com>"),
    // insert own header that satisfies header.Header interface
}

text := mime.NewEntity(
    []header.Header{header.NewContentType(
        "text/plain",
        header.NewMIMEParams("charset", "us-ascii"),
    ),
    }, "Attack at Dawn!")

html := mime.NewEntity(
    []header.Header{header.NewContentType(
        "text/html",
        header.NewMIMEParams("charset", "utf-8"),
    ),
    }, "<b>Attack at Dawn!</b>")

alt := mime.NewMultipartAlternative(headers, []*mime.Entity{text, html})

// header validation
for _, h := range alt.Headers {
    if err := h.Validate(); err != nil {
        // handle error
    }
}

// generate raw email output, use in gmail api, aws ses etc.
raw := alt.String()

Features

General

• email header validation
• non us-ascii support for header and mime parameter values
• non us-ascii support for email body

Folding

• header (78 octet limit)
• RFC 2045 base64 (76 octet limit)
• support for folding priority

Highly customisable and extensible

• header.Header interface
• folder.Foldable interface
• standalone syntax checking library
• standalone folding library

Relevant Documents

Package makes best effort to conform to following standards:

• RFC 5322 — Internet Message Format. Specification for emails.
• RFC 2045 — MIME Part 1: Message Body Formatting. Supports non-ascii body including attachments.
• RFC 2046 — MIME Part 2: Media Types. Text, image, video, audio, application, multipart and message.
• RFC 2047 — MIME Part 3: Message Header Formatting. Supports non-ascii headers.
• RFC 2049 — MIME Part 5: MIME conformance.
• RFC 2231 — MIME Parameter Value and Encoded Word Extensions. Supports non-ascii header parameters.
• RFC 2183 — Communicating Presentation Information in Internet Messages: The Content-Disposition Header Field.
• RFC 5321 — Simple Mail Transfer Protocol. Imposes some length limits on various parts of message.

Documentation

Index

• type Attachment
  • func (a *Attachment) Entity() *mime.Entity
• type Email
  • func New() *Email
  • func (e *Email) AddHeader(h header.Header)
  • func (e *Email) Raw() string
  • func (e *Email) Validate() []error

Types

type Attachment

type Attachment struct {
	Inline    bool // inline vs attachment
	Filename  string
	ContentID string // for inline ref, eg <img src="cid:[ContentID]" />
	Data      []byte
}

func (*Attachment) Entity

func (a *Attachment) Entity() *mime.Entity

Entity converts to mime.Entity form

type Email

type Email struct {
	From        string
	To          string // accepts comma-separated list
	Cc          string // accepts comma-separated list
	Bcc         string // accepts comma-separated list
	Subject     string // can contain any printable unicode characters
	Body        string
	Attachments []*Attachment
	// contains filtered or unexported fields
}

Email is a wrapper around mime.Entity

For full control use mime.Entity directly

func New

func New() *Email

func (*Email) AddHeader

func (e *Email) AddHeader(h header.Header)

AddHeader appends to generated headers. Headers are not guaranteed to be in any particular order

func (*Email) Raw

func (e *Email) Raw() string

Raw produces RFC 5322 and MIME compliant email

func (*Email) Validate

func (e *Email) Validate() []error

Validate checks syntax of headers for potential errors returns nil if no errors detected