mail

Documentation

Overview

Package mail implements reading and writing mail messages.

This package assumes that a mail message contains one or more text parts and zero or more attachment parts. Each text part represents a different version of the message content (e.g. a different type, a different language and so on).

RFC 5322 defines the Internet Message Format.

Index

• func CreateSingleInlineWriter(w io.Writer, header Header) (io.WriteCloser, error)
• type Address
  • func ParseAddress(address string) (*Address, error)
  • func ParseAddressList(list string) ([]*Address, error)
• type AttachmentHeader
  • func (h *AttachmentHeader) Filename() (string, error)
  • func (h *AttachmentHeader) SetFilename(filename string)
• type Header
  • func HeaderFromMap(m map[string][]string) Header
  • func (h *Header) AddressList(key string) ([]*Address, error)
  • func (h *Header) Copy() Header
  • func (h *Header) Date() (time.Time, error)
  • func (h *Header) GenerateMessageID() error
  • func (h *Header) GenerateMessageIDWithHostname(hostname string) error
  • func (h *Header) MessageID() (string, error)
  • func (h *Header) MsgIDList(key string) ([]string, error)
  • func (h *Header) SetAddressList(key string, addrs []*Address)
  • func (h *Header) SetDate(t time.Time)
  • func (h *Header) SetMessageID(id string)
  • func (h *Header) SetMsgIDList(key string, l []string)
  • func (h *Header) SetSubject(s string)
  • func (h *Header) Subject() (string, error)
• type InlineHeader
• type InlineWriter
  • func CreateInlineWriter(w io.Writer, header Header) (*InlineWriter, error)
  • func (w *InlineWriter) Close() error
  • func (w *InlineWriter) CreatePart(h InlineHeader) (io.WriteCloser, error)
• type Part
• type PartHeader
• type Reader
  • func CreateReader(r io.Reader) (*Reader, error)
  • func NewReader(e *message.Entity) *Reader
  • func (r *Reader) Close() error
  • func (r *Reader) NextPart() (*Part, error)
• type Writer
  • func CreateWriter(w io.Writer, header Header) (*Writer, error)
  • func (w *Writer) Close() error
  • func (w *Writer) CreateAttachment(h AttachmentHeader) (io.WriteCloser, error)
  • func (w *Writer) CreateInline() (*InlineWriter, error)
  • func (w *Writer) CreateSingleInline(h InlineHeader) (io.WriteCloser, error)

Examples

• Reader
• Writer

Functions

func CreateSingleInlineWriter

func CreateSingleInlineWriter(w io.Writer, header Header) (io.WriteCloser, error)

CreateSingleInlineWriter writes a mail header to w. The mail will contain a single inline part. The body of the part should be written to the returned io.WriteCloser. Only one single inline part should be written, use CreateWriter if you want multiple parts.

Types

type Address

type Address = mail.Address

Address represents a single mail address. The type alias ensures that a net/mail.Address can be used wherever an Address is expected

func ParseAddress

func ParseAddress(address string) (*Address, error)

ParseAddress parses a single RFC 5322 address, e.g. "Barry Gibbs <bg@example.com>" Use this function only if you parse from a string, if you have a Header use Header.AddressList instead

func ParseAddressList

func ParseAddressList(list string) ([]*Address, error)

ParseAddressList parses the given string as a list of addresses. Use this function only if you parse from a string, if you have a Header use Header.AddressList instead

type AttachmentHeader

type AttachmentHeader struct {
	message.Header
}

An AttachmentHeader represents an attachment's header.

func (*AttachmentHeader) Filename

func (h *AttachmentHeader) Filename() (string, error)

Filename parses the attachment's filename.

func (*AttachmentHeader) SetFilename

func (h *AttachmentHeader) SetFilename(filename string)

SetFilename formats the attachment's filename.

type Header

type Header struct {
	message.Header
}

A Header is a mail header.

func HeaderFromMap

func HeaderFromMap(m map[string][]string) Header

HeaderFromMap creates a header from a map of header fields.

This function is provided for interoperability with the standard library. If possible, ReadHeader should be used instead to avoid loosing information. The map representation looses the ordering of the fields, the capitalization of the header keys, and the whitespace of the original header.

func (*Header) AddressList

func (h *Header) AddressList(key string) ([]*Address, error)

AddressList parses the named header field as a list of addresses. If the header field is missing, it returns nil.

This can be used on From, Sender, Reply-To, To, Cc and Bcc header fields.

func (*Header) Copy

func (h *Header) Copy() Header

Copy creates a stand-alone copy of the header.

func (*Header) Date

func (h *Header) Date() (time.Time, error)

Date parses the Date header field. If the header field is missing, it returns the zero time.

func (*Header) GenerateMessageID

func (h *Header) GenerateMessageID() error

GenerateMessageID wraps GenerateMessageIDWithHostname and therefore uses the hostname of the local machine. This is done to not break existing software. Wherever possible better use GenerateMessageIDWithHostname, because the local hostname of a machine tends to not be unique nor a FQDN which especially brings problems with spam filters.

func (*Header) GenerateMessageIDWithHostname

func (h *Header) GenerateMessageIDWithHostname(hostname string) error

GenerateMessageIDWithHostname generates an RFC 2822-compliant Message-Id based on the informational draft "Recommendations for generating Message IDs", it takes an hostname as argument, so that software using this library could use a hostname they know to be unique

func (*Header) MessageID

func (h *Header) MessageID() (string, error)

MessageID parses the Message-ID field. It returns the message identifier, without the angle brackets. If the message doesn't have a Message-ID header field, it returns an empty string.

func (*Header) MsgIDList

func (h *Header) MsgIDList(key string) ([]string, error)

MsgIDList parses a list of message identifiers. It returns message identifiers without angle brackets. If the header field is missing, it returns nil.

This can be used on In-Reply-To and References header fields.

func (*Header) SetAddressList

func (h *Header) SetAddressList(key string, addrs []*Address)

SetAddressList formats the named header field to the provided list of addresses.

This can be used on From, Sender, Reply-To, To, Cc and Bcc header fields.

func (*Header) SetDate

func (h *Header) SetDate(t time.Time)

SetDate formats the Date header field.

func (*Header) SetMessageID

func (h *Header) SetMessageID(id string)

SetMessageID sets the Message-ID field. id is the message identifier, without the angle brackets.

func (*Header) SetMsgIDList

func (h *Header) SetMsgIDList(key string, l []string)

SetMsgIDList formats a list of message identifiers. Message identifiers don't include angle brackets.

This can be used on In-Reply-To and References header fields.

func (*Header) SetSubject

func (h *Header) SetSubject(s string)

SetSubject formats the Subject header field.

func (*Header) Subject

func (h *Header) Subject() (string, error)

Subject parses the Subject header field. If there is an error, the raw field value is returned alongside the error.

type InlineHeader

type InlineHeader struct {
	message.Header
}

A InlineHeader represents a message text header.

type InlineWriter

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

InlineWriter writes a mail message's text.

func CreateInlineWriter

func CreateInlineWriter(w io.Writer, header Header) (*InlineWriter, error)

CreateInlineWriter writes a mail header to w. The mail will contain an inline part, allowing to represent the same text in different formats. Attachments cannot be included.

func (*InlineWriter) Close

func (w *InlineWriter) Close() error

Close finishes the InlineWriter.

func (*InlineWriter) CreatePart

func (w *InlineWriter) CreatePart(h InlineHeader) (io.WriteCloser, error)

CreatePart creates a new text part with the provided header. The body of the part should be written to the returned io.WriteCloser.

type Part

type Part struct {
	Header PartHeader
	Body   io.Reader
}

A Part is either a mail text or an attachment. Header is either a InlineHeader or an AttachmentHeader.

type PartHeader

type PartHeader interface {
	// Add adds the key, value pair to the header.
	Add(key, value string)
	// Del deletes the values associated with key.
	Del(key string)
	// Get gets the first value associated with the given key. If there are no
	// values associated with the key, Get returns "".
	Get(key string) string
	// Set sets the header entries associated with key to the single element
	// value. It replaces any existing values associated with key.
	Set(key, value string)
}

A PartHeader is a mail part header. It contains convenience functions to get and set header fields.

type Reader

type Reader struct {
	Header Header
	// contains filtered or unexported fields
}

A Reader reads a mail message.

Example

package main

import (
	"io"
	"io/ioutil"
	"log"

	"github.com/emersion/go-message/mail"
)

func main() {
	// Let's assume r is an io.Reader that contains a mail.
	var r io.Reader

	// Create a new mail reader
	mr, err := mail.CreateReader(r)
	if err != nil {
		log.Fatal(err)
	}

	// Read each mail's part
	for {
		p, err := mr.NextPart()
		if err == io.EOF {
			break
		} else if err != nil {
			log.Fatal(err)
		}

		switch h := p.Header.(type) {
		case *mail.InlineHeader:
			b, _ := ioutil.ReadAll(p.Body)
			log.Printf("Got text: %v\n", string(b))
		case *mail.AttachmentHeader:
			filename, _ := h.Filename()
			log.Printf("Got attachment: %v\n", filename)
		}
	}
}

func CreateReader

func CreateReader(r io.Reader) (*Reader, error)

CreateReader reads a mail header from r and returns a new mail reader.

If the message uses an unknown transfer encoding or charset, CreateReader returns an error that verifies message.IsUnknownCharset, but also returns a Reader that can be used.

func NewReader

func NewReader(e *message.Entity) *Reader

NewReader creates a new mail reader.

func (*Reader) Close

func (r *Reader) Close() error

Close finishes the reader.

func (*Reader) NextPart

func (r *Reader) NextPart() (*Part, error)

NextPart returns the next mail part. If there is no more part, io.EOF is returned as error.

The returned Part.Body must be read completely before the next call to NextPart, otherwise it will be discarded.

If the part uses an unknown transfer encoding or charset, NextPart returns an error that verifies message.IsUnknownCharset, but also returns a Part that can be used.

type Writer

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

A Writer writes a mail message. A mail message contains one or more text parts and zero or more attachments.

Example

package main

import (
	"bytes"
	"io"
	"log"
	"time"

	"github.com/emersion/go-message/mail"
)

func main() {
	var b bytes.Buffer

	from := []*mail.Address{{"Mitsuha Miyamizu", "mitsuha.miyamizu@example.org"}}
	to := []*mail.Address{{"Taki Tachibana", "taki.tachibana@example.org"}}

	// Create our mail header
	var h mail.Header
	h.SetDate(time.Now())
	h.SetAddressList("From", from)
	h.SetAddressList("To", to)

	// Create a new mail writer
	mw, err := mail.CreateWriter(&b, h)
	if err != nil {
		log.Fatal(err)
	}

	// Create a text part
	tw, err := mw.CreateInline()
	if err != nil {
		log.Fatal(err)
	}
	var th mail.InlineHeader
	th.Set("Content-Type", "text/plain")
	w, err := tw.CreatePart(th)
	if err != nil {
		log.Fatal(err)
	}
	io.WriteString(w, "Who are you?")
	w.Close()
	tw.Close()

	// Create an attachment
	var ah mail.AttachmentHeader
	ah.Set("Content-Type", "image/jpeg")
	ah.SetFilename("picture.jpg")
	w, err = mw.CreateAttachment(ah)
	if err != nil {
		log.Fatal(err)
	}
	// TODO: write a JPEG file to w
	w.Close()

	mw.Close()

	log.Println(b.String())
}

func CreateWriter

func CreateWriter(w io.Writer, header Header) (*Writer, error)

CreateWriter writes a mail header to w and creates a new Writer.

func (*Writer) Close

func (w *Writer) Close() error

Close finishes the Writer.

func (*Writer) CreateAttachment

func (w *Writer) CreateAttachment(h AttachmentHeader) (io.WriteCloser, error)

CreateAttachment creates a new attachment with the provided header. The body of the part should be written to the returned io.WriteCloser.

func (*Writer) CreateInline

func (w *Writer) CreateInline() (*InlineWriter, error)

CreateInline creates a InlineWriter. One or more parts representing the same text in different formats can be written to a InlineWriter.

func (*Writer) CreateSingleInline

func (w *Writer) CreateSingleInline(h InlineHeader) (io.WriteCloser, error)

CreateSingleInline creates a new single text part with the provided header. The body of the part should be written to the returned io.WriteCloser. Only one single text part should be written, use CreateInline if you want multiple text parts.