email

Documentation

Overview

Package email is provides generic tools for representing an email and for parsing email headers. This is used in conjuncion with the simple and mime packages to provide simple email parsing and MIME message handling.

None of the operations of this library are intended to be thread safe. No guarantees are made that the object will be kept in a consistent state while within a method, so you shouldn't try to manipulate or access the data of these objects concurrently.

Index

• Constants
• func FoldValue(f, lb []byte) []byte
• func MakeHeaderFieldMatch(n string) string
• func UnfoldValue(f []byte) []byte
• type Body
  • func NewBody(content []byte) *Body
  • func (m *Body) Bytes() []byte
  • func (m *Body) Content() []byte
  • func (m *Body) ContentString() string
  • func (m *Body) SetContent(c []byte)
  • func (m *Body) SetContentString(s string)
  • func (m *Body) String() string
• type Header
  • func NewHeader(lb string, f ...*HeaderField) *Header
  • func (h *Header) Break() []byte
  • func (h *Header) Bytes() []byte
  • func (h *Header) HeaderFieldIndex(n string, ix int, fb bool) int
  • func (h *Header) HeaderGetAllFields(n string) []*HeaderField
  • func (h *Header) HeaderGetField(n string) *HeaderField
  • func (h *Header) HeaderGetFieldN(n string, ix int) (*HeaderField, error)
  • func (h *Header) String() string
• type HeaderField
  • func NewHeaderField(n, b string, lb []byte) *HeaderField
  • func NewHeaderFieldParsed(n, b string, original []byte) *HeaderField
  • func (f *HeaderField) Body() string
  • func (f *HeaderField) Bytes() []byte
  • func (f *HeaderField) CacheGet(k string) interface{}
  • func (f *HeaderField) CacheSet(k string, v interface{})
  • func (f *HeaderField) Match() string
  • func (f *HeaderField) Name() string
  • func (f *HeaderField) Original() []byte
  • func (f *HeaderField) RawBody() []byte
  • func (f *HeaderField) SetBody(b string, lb []byte)
  • func (f *HeaderField) SetBodyEncoded(sb string, bb []byte, lb []byte)
  • func (f *HeaderField) SetBodyEncodedNoFold(sb string, bb []byte)
  • func (f *HeaderField) SetBodyNoFold(b string, lb []byte)
  • func (f *HeaderField) SetName(n string, lb []byte)
  • func (f *HeaderField) SetNameNoFold(n string)
  • func (f *HeaderField) String() string
• type Message
  • func NewMessage(h *Header, body []byte) *Message
  • func (m *Message) Bytes() []byte
  • func (m *Message) String() string

Constants

const (
	FoldIndent          = " "  // indent placed before folded lines
	PreferredFoldLength = 80   // we prefer headers and 7bit/8bit bodies lines shorter than this
	ForcedFoldLength    = 1000 // we forceably break headers and 7bit/8bit bodies lines longer than this
)

const (
	CRLF = "\x0d\x0a" // "\r\n" - Network linebreak
	LF   = "\x0a"     // "\n"   - Unix and Linux
	CR   = "\x0d"     // "\r"   - Commodores and old Macs
	LFCR = "\x0a\x0d" // "\n\r" - weirdos
)

Constants for use when selecting a line break to use with a new header. If you don't know what to pick, choose CRLF.

Functions

func FoldValue

func FoldValue(f, lb []byte) []byte

FoldValue will take an unfolded or perhaps partially folded value from an email and fold it. It will make sure that every fold line is properly indented, try to break lines on appropriate spaces, and force long lines to be broken before the maximum line length.

func MakeHeaderFieldMatch

func MakeHeaderFieldMatch(n string) string

MakeHeaderFieldMatch trims space and lowers the case of a header name for comparison purposes. All the HeaderGet* and HeaderSet* methods make use of this to make sure header names are matched in a standard way.

func UnfoldValue

func UnfoldValue(f []byte) []byte

UnfoldValue will take a folded header line from an email and unfold it for reading. This gives you the proper header body value.

Types

type Body

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

Body is a basic wrapper around a slice of bytes of data.

func NewBody

func NewBody(content []byte) *Body

NewBody builds a new body with the given content bytes.

func (*Body) Bytes

func (m *Body) Bytes() []byte

Bytes returns the email message as a slice of bytes.

func (*Body) Content

func (m *Body) Content() []byte

Content returns the message body.

func (*Body) ContentString

func (m *Body) ContentString() string

ContentString returns the message body as a string.

func (*Body) SetContent

func (m *Body) SetContent(c []byte)

SetContent sets the message body.

func (*Body) SetContentString

func (m *Body) SetContentString(s string)

SetContentString sets the message body from a string.

func (*Body) String

func (m *Body) String() string

String returns the email message as a string.

type Header

type Header struct {
	Fields []*HeaderField // The list of fields
	// contains filtered or unexported fields
}

Header represents an email message header. The header object stores enough detail that the original header can be recreated byte-for-byte for round-tripping.

func NewHeader

func NewHeader(lb string, f ...*HeaderField) *Header

NewHeader creates a new header.

func (*Header) Break

func (h *Header) Break() []byte

Break returns the line break string associated with this header.

func (*Header) Bytes

func (h *Header) Bytes() []byte

Bytes will return the byte representation of the header. If the header was parsed from an email header and not modified, this will output the original header, preserved byte-for-byte.

func (*Header) HeaderFieldIndex

func (h *Header) HeaderFieldIndex(n string, ix int, fb bool) int

HeaderFieldIndex will look up the (ix+1)th header field with the name n. It returns the index in h.Fields of that field. This also works with negative ix, which finds the (-ix)th header field from the end of the fields list.

If no header field is found with the given name, -1 will be returned.

If fb is false and there is no (ix+1)th or (-ix)th header, based on whether ix is non-negative or negative, respectively, then -1 is returned.

If fb is true and ix is non-negative and there is no (ix+1)th header field, but there was at least one header, the index of the latest header field with that name is returned.

If fb is true and ix is negative and there is no (-ix)th header field, but there was at least one header, the index of the earliest header field with that name is returned.

func (*Header) HeaderGetAllFields

func (h *Header) HeaderGetAllFields(n string) []*HeaderField

HeaderGetAllFields will find all the header fields with a matching name and return the list of field objects. It will return any empty slice if no headers with this name are present.

func (*Header) HeaderGetField

func (h *Header) HeaderGetField(n string) *HeaderField

HeaderGetField will find the first header field and return the header field object itself. It will return nil if no such header is present.

func (*Header) HeaderGetFieldN

func (h *Header) HeaderGetFieldN(n string, ix int) (*HeaderField, error)

HeaderGetFieldN locates the (ix+1)th named header and returns the header field object. If no such header exists, the field is returned as nil and an error is returned.

If ix is negative, it will return the (-ix)th header from the end.

func (*Header) String

func (h *Header) String() string

String will return the string representation of the header. If the header was parsed from an email header and not modified, this will output the original header, preserved byte-for-byte.

type HeaderField

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

HeaderField represents an individual field in the message header. When taken from a parsed header, it will preserve the original field, byte-for-byte.

HeaderField is just for storing information about the field. Otherwise it is completely stupid. It provides for storing the field body in a fully native string that is fully decoded and for storing a totally different encoded form as octets. However, it does nothing to assist you in this.

The name field, in particular, should be kept in ASCII only. If you set a name to something other than ASCII, you probably won't appreciate the results. Weirdness will ensue. It won't be pretty. I promise you.

func NewHeaderField

func NewHeaderField(n, b string, lb []byte) *HeaderField

NewHeaderField constructs a new header field using the given name, body, and line break string.

func NewHeaderFieldParsed

func NewHeaderFieldParsed(n, b string, original []byte) *HeaderField

NewHeaderFieldParsed constructs a new header field using the given name, body, line break, and original. No checks are performed on the name or body.

func (*HeaderField) Body

func (f *HeaderField) Body() string

Body returns the field body.

func (*HeaderField) Bytes

func (f *HeaderField) Bytes() []byte

Bytes returns the original as bytes.

func (*HeaderField) CacheGet

func (f *HeaderField) CacheGet(k string) interface{}

CacheGet retrieves a value from a structured data cache associated with the header. Fields in the structured data cache are cleared when any setter method is called on the header field

func (*HeaderField) CacheSet

func (f *HeaderField) CacheSet(k string, v interface{})

CacheSet sets a value in the structured data cache associated with the header field. The intention is for this to be set to structured data associated with the header value. If the name or body of the header is changed, this cache will be cleared.

func (*HeaderField) Match

func (f *HeaderField) Match() string

Match returns a string useful for matching this header. It will be the name string converted to lowercase.

func (*HeaderField) Name

func (f *HeaderField) Name() string

Name returns the field name.

func (*HeaderField) Original

func (f *HeaderField) Original() []byte

Original returns the original text of the field or the newly set rendered text for the field.

func (*HeaderField) RawBody

func (f *HeaderField) RawBody() []byte

RawBody returns the field body in the final encoded form as it will be output in the email.

func (*HeaderField) SetBody

func (f *HeaderField) SetBody(b string, lb []byte)

SetBody will update the body of the field. You must supply the line break to be used for folding. The body value should not be terminated with a line ending. The line ending will be added for you.

func (*HeaderField) SetBodyEncoded

func (f *HeaderField) SetBodyEncoded(sb string, bb []byte, lb []byte)

SetBodyEncoded will update the body of the field, but provides the string value of field as well as an octet representation. This is useful in cases where the native string representation of the field is significantly different from the octet representation (due to MIME word encoding or similar). You must also supply the line ending use for folding. The line ending should not already be applied to the binary representation.

func (*HeaderField) SetBodyEncodedNoFold

func (f *HeaderField) SetBodyEncodedNoFold(sb string, bb []byte)

SetBodyEncodedNoFold will update the body of the field without performing any folding. This allows the encoded version of the value to be very different from the octet representation for use with MIME word encoding and such. No folding is performed. Make sure to provide an appropriate line ending to the value as well.

func (*HeaderField) SetBodyNoFold

func (f *HeaderField) SetBodyNoFold(b string, lb []byte)

SetBodyNoFold will update the body of the field without performing any folding.

func (*HeaderField) SetName

func (f *HeaderField) SetName(n string, lb []byte)

SetName will rename a field. The line break parameter must be passed so it can refold the line as needed.

It is only safe to place ASCII characters into the name of a field. Any characters that are 8-bit or longer may result in undefined behavior.

func (*HeaderField) SetNameNoFold

func (f *HeaderField) SetNameNoFold(n string)

SetNameNoFold will rename a field without folding. The name will be set as is.

It is only safe to place ASCII characters into the name of a field. Any other characters that are 8-bit or longer may result in undefined behavior.

func (*HeaderField) String

func (f *HeaderField) String() string

String is an alias for Original.

type Message

type Message struct {
	Header
	Body
}

Message represents an email message and body. The message object stores enough detail that the original message can be roundtripped and preserved byte-for-byte while still providing useful tools for reading the header fields and other information.

func NewMessage

func NewMessage(h *Header, body []byte) *Message

NewMessage builds a new basic email message from the given header and body.

func (*Message) Bytes

func (m *Message) Bytes() []byte

Bytes returns the email message as a slice of bytes.

func (*Message) String

func (m *Message) String() string

String returns the email message as a string.