header

package
v2.3.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 31, 2023 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

Package header provides low-level and high-level tooling for dealing with email message headers. If you need low-level access, you want to deal with methods that work with field.Field objects. However, it is generally expected that devs will prefer the high-level methods which will try to keep your reading and manipulation of the header safe and strictly correct on output.

The provided Parse() method will parse up headers in a flexible way that is built on top of field.Parse() to preserve message headers as-is for output.

Index

Constants

View Source 
const (
	Bcc                     = "Bcc"
	Cc                      = "Cc"
	Comments                = "Comments"
	ContentDisposition      = "Content-disposition"
	ContentTransferEncoding = "Content-transfer-encoding"
	ContentType             = "Content-type"
	Date                    = "Date"
	From                    = "From"
	InReplyTo               = "In-reply-to"
	Keywords                = "Keywords"
	MessageID               = "Message-id"
	References              = "References"
	ReplyTo                 = "Reply-to"
	Sender                  = "Sender"
	Subject                 = "Subject"
	To                      = "To"
)

These are standard headers defined in RFC 5322.

View Source 
const (
	// UnixDateWithEarlyYear is a weird one, eh?
	UnixDateWithEarlyYear = "Mon Jan 02 15:04:05 2006 MST"
)

Even more custom date formats, built from those seen in the wild that the usual parsers have trouble with.

Variables

View Source 
var (
	// ErrNoSuchField is returned by Header methods when the operation
	// being performed failed because the header named does not exist.
	ErrNoSuchField = errors.New("no such header field")

	// ErrNoSuchFieldParameter is returned by Header methods when the
	// operation being performed failed because the header exists, but a
	// sub-field of the header does not exist.
	ErrNoSuchFieldParameter = errors.New("no such header field parameter")

	// ErrManyFields is returned by Header methods when the operation
	// being performed failed because the there are multiple fields with the
	// given name.
	ErrManyFields = errors.New("many header fields found")

	// ErrWrongAddressType is returned by address setting methods that accept
	// either a string or an addr.AddressList when something other than those
	// types is provided.
	ErrWrongAddressType = errors.New("incorrect address type during write")
)

Errors returned by various header methods and functions.

View Source 
var (
	// ErrIndexOutOfRange when an attempt is made to access a header field index
	// that is too large or to small.
	ErrIndexOutOfRange = errors.New("header field index is out of range")
)

Functions

func ParseAddressList added in v2.3.0 

func ParseAddressList(body string) addr.AddressList

ParseAddressList provides the same address parsing functionality build into the GetAddressList() and GetAllAddressLists() and can be used to parse any field body. It will attempt a strict parse of the email address list. However, if that fails, an extremely lenient parsing will be attempted, which might result in results that can only be described as "weird" in the effort to provide some kind of result. It is so forgiving, it will return some kind of value for any input.

It will either return an addr.AddressList or an error describing the parse error.

func ParseTime added in v2.3.0 

func ParseTime(body string) (time.Time, error)

ParseTime is a function that provides the time parsing used by GetTime() and GetDate() to parse dates to be used on any field body. This will attempt to parse the date using the format specified by RFC 5322 first and fallback to parsing it in many other formats.

It either returns a parsed time or the parse error.

Types

type Base 

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

Base represents a basic email message header. It is a low-level interface to headers, but with the ability to apply field folding during output.

func (*Base) Break 

func (h *Base) Break() Break

Break returns the line break used to separate header fields and terminate the header.

func (*Base) ClearFields 

func (h *Base) ClearFields()

ClearFields removes all fields from the header.

func (*Base) Clone added in v2.0.3 

func (h *Base) Clone() *Base

Clone creates a deep copy of the header object and returns it.

func (*Base) DeleteField 

func (h *Base) DeleteField(n int) error

DeleteField removes the nth field from the header. Fails with an error if the given index is out of range.

func (*Base) FoldEncoding 

func (h *Base) FoldEncoding() *field.FoldEncoding

FoldEncoding returns the value folder used by this header during rendering.

func (*Base) GetAllFieldsNamed 

func (h *Base) GetAllFieldsNamed(name string) []*field.Field

GetAllFieldsNamed returns all the fields with the given name or nil if no fields are set with that name.

func (*Base) GetField 

func (h *Base) GetField(n int) *field.Field

GetField returns the nth field.

func (*Base) GetFieldNamed 

func (h *Base) GetFieldNamed(name string, n int) *field.Field

GetFieldNamed returns the nth (0-indexed) with the given name or nil if no such header field is set.

func (*Base) GetIndexesNamed 

func (h *Base) GetIndexesNamed(name string) []int

GetIndexesNamed returns the indexes of fields with the given name.

func (*Base) InsertBeforeField 

func (h *Base) InsertBeforeField(
	n int,
	name,
	body string,
)

InsertBeforeField will insert the given name and body values into the header at the given index.

func (*Base) Len 

func (h *Base) Len() int

Len returns the number of header fields in the header.

func (*Base) ListFields 

func (h *Base) ListFields() []*field.Field

ListFields returns all the fields in the header.

func (*Base) SetBreak 

func (h *Base) SetBreak(lbr Break)

SetBreak changes the line break to use with this header.

func (*Base) SetFoldEncoding 

func (h *Base) SetFoldEncoding(vf *field.FoldEncoding)

SetFoldEncoding changes the value folder used by this header during rendering.

func (*Base) WriteTo 

func (h *Base) WriteTo(w io.Writer) (int64, error)

WriteTo will write the contents of the header to the given io.Writer.

type Break 

type Break string

Break represents the linebreak to use when working with an email. 

const (
	Meh  Break = ""         // Sometimes it doesn't matter
	CRLF Break = "\x0d\x0a" // \r\n - Network linebreak
	LF   Break = "\x0a"     // \n - Unix/Linux/BSD linebreak
	CR   Break = "\x0d"     // \r - Commodores/old Macs linebreak
	LFCR Break = "\x0a\x0d" // \n\r - for 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.

func (Break) Bytes 

func (b Break) Bytes() []byte

Bytes returns the break as a slice of bytes.

func (Break) String 

func (b Break) String() string

String returns the break as a string. 

type Header struct {
	// Base provides the low-level storage of header fields.
	Base
	// contains filtered or unexported fields
}

Header wraps a Base, which does the actual storage and low-level field manipulation. This provides several methods to make reading and manipulating the header more convenient and some caching for complex values parsed from header fields.

The getter methods of this object will return an error if the field being fetched has not been set on the header. The error returned will be ErrNoSuchField.

func Parse 

func Parse(m []byte, lb Break) (*Header, error)

Parse will parse the given slice of bytes into an email header using the given line break string. It will assume the entire string given represents the header to be parsed.

The parsed message will have field.DoNotFoldEncoding. This allows us the code to round-trip without modifying the original. Use SetFoldEncoding() if this is something you would like to change.

func (*Header) Clone added in v2.0.3 

func (h *Header) Clone() *Header

Clone returns a deep copy of the header object.

func (*Header) Get 

func (h *Header) Get(name string) (string, error)

Get retrieves the string value of the named field.

If the named field is not set in the header, it will return an empty string with ErrNoSuchField. If there are multiple headers for the given named field, it will return the first value found and return ErrManyFields.

func (*Header) GetAddressList 

func (h *Header) GetAddressList(name string) (addr.AddressList, error)

GetAddressList will return an addr.AddressList for the named field. This method works hard to avoid parse errors and tries to accept anything. As such a badly formatted address field might return a weird address value.

It will return nil and ErrNoSuchField if the field is not set on the header. It will return ErrManyFields if the field is set more than once on the header.

func (*Header) GetAll 

func (h *Header) GetAll(name string) ([]string, error)

GetAll fetches all the header field bodies for fields with the given name and returns them as a slice of strings.

It returns nil with ErrNoSuchField if no field with the given name is set on the header.

func (*Header) GetAllAddressLists 

func (h *Header) GetAllAddressLists(name string) ([]addr.AddressList, error)

GetAllAddressLists will return a slice of addr.AddressList for all headers with the given name.

This uses a very forgiving parser for email addresses, so it won't error on weird and wonky addresses, but do its best to return them, so you may get weird results from this.

If the named field does not exist in the header, this will return nil with ErrNoSuchField.

func (*Header) GetBcc 

func (h *Header) GetBcc() (addr.AddressList, error)

GetBcc returns the Bcc address field as an addr.AddressList.

It will return nil and ErrNoSuchField if the field is not set on the header. It will return ErrManyFields if the field is set more than once on the header.

func (*Header) GetBoundary 

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

GetBoundary gets the boundary from the Content-type header field.

This method returns an empty string with ErrNoSuchField if no field is present in the header. This method returns an empty string with ErrNoSuchFieldParameter if the field is present, but the parameter is not set on the field. This method returns an empty string with ErrManyFields if the field is set more than once on the header. This method returns an empty string and an error if the parameter values cannot be parsed out of the field for some reason.

func (*Header) GetCc 

func (h *Header) GetCc() (addr.AddressList, error)

GetCc returns the Cc address field as an addr.AddressList.

It will return nil and ErrNoSuchField if the field is not set on the header. It will return ErrManyFields if the field is set more than once on the header.

func (*Header) GetCharset 

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

GetCharset gets the charset from the Content-type header field.

This method returns an empty string with ErrNoSuchField if no field is present in the header. This method returns an empty string with ErrNoSuchFieldParameter if the field is present, but the parameter is not set on the field. This method returns an empty string with ErrManyFields if the field is set more than once on the header. This method returns an empty string and an error if the parameter values cannot be parsed out of the field for some reason.

func (*Header) GetComments 

func (h *Header) GetComments() ([]string, error)

GetComments returns the content of the Comments header fields.

func (*Header) GetContentDisposition 

func (h *Header) GetContentDisposition() (*param.Value, error)

GetContentDisposition returns the Content-disposition header as a param.Value.

It returns nil and ErrNoSuchField if the field is not set on the header. It returns nil and ErrManyFields if the field is set more than once on the header. It will return nil and an error if there is a problem parsing the param.Value.

func (*Header) GetContentType 

func (h *Header) GetContentType() (*param.Value, error)

GetContentType returns the Content-type header as a param.Value.

It returns nil and ErrNoSuchField if the field is not set on the header. It returns nil and ErrManyFields if the field is set more than once on the header. It will return nil and an error if there is a problem parsing the param.Value.

func (*Header) GetDate 

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

GetDate retrieves the Date header as a time.Time value.

It will return an error if it is unable to parse the time value from the Date header. It will return the zero value and ErrNoSuchField if the header does not exist. It will return the zero value and ErrManyFields if more than one Date field is set on the header.

func (*Header) GetFilename 

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

GetFilename gets the filename parameter of the Content-disposition header.

This method returns an empty string with ErrNoSuchField if no field is present in the header. This method returns an empty string with ErrNoSuchFieldParameter if the field is present, but the parameter is not set on the field. This method returns an empty string with ErrManyFields if the field is set more than once on the header. This method returns an empty string and an error if the parameter values cannot be parsed out of the field for some reason.

func (*Header) GetFrom 

func (h *Header) GetFrom() (addr.AddressList, error)

GetFrom returns the From address field as an addr.AddressList.

It will return nil and ErrNoSuchField if the field is not set on the header. It will return ErrManyFields if the field is set more than once on the header.

func (*Header) GetInReplyTo 

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

GetInReplyTo returns the message ID in the In-reply-to header, if any.

If In-reply-to is not set in the header, it will return an empty string with ErrNoSuchField. If there are multiple In-reply-to headers, it will return ErrManyFields.

func (*Header) GetKeywords 

func (h *Header) GetKeywords() ([]string, error)

GetKeywords returns all the keywords set on all the Keywords fields.

This method will return nil with ErrNoSuchField if the Keywords field does not exist.

func (*Header) GetKeywordsList 

func (h *Header) GetKeywordsList(name string) ([]string, error)

GetKeywordsList will return a list of strings representing all the keywords set on the named header. These are formatted as for the Keywords header, but this is the generic method that allows for treating other headers as Keywords. There can be zero or more Keywords headers. Each header is, then, a comma-separated list of Keywords. This will collect those values from all the headers with the given name and return them.

This method will return nil with ErrNoSuchField if the named field does not exist.

func (*Header) GetMediaType 

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

GetMediaType returns the MIME type set in the Content-type header (other parameters will not be returned).

It returns nil and ErrNoSuchField if the field is not set on the header. It returns nil and ErrManyFields fi the field is set more than once on the header. It will return nil and an error if there is a problem parsing the media type information out of the header.

func (*Header) GetMessageID 

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

GetMessageID returns the Message ID found in the Message-id header, if any.

If Message-id is not set in the header, it will return an empty string with ErrNoSuchField. If there are multiple Message-id headers, it will return ErrManyFields.

func (*Header) GetParamValue 

func (h *Header) GetParamValue(name string) (*param.Value, error)

GetParamValue will return a param.Value for the header field matching the given name.

This will return an error if it is unable to parse a param.Value. This will ErrNoSuchField if no field with the given name is present. It will return ErrManyFields if more than one field with the given name is found.

func (*Header) GetPresentation 

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

GetPresentation returns the primary value of the Content-disposition header, describing what the function of this part of the message is.

It returns nil and ErrNoSuchField if the field is not set on the header. It returns nil and ErrManyFields fi the field is set more than once on the header. It will return nil and an error if there is a problem parsing the presentation information out of the header.

func (*Header) GetReferences 

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

GetReferences returns the message ID in the References header, if any.

If References is not set in the header, it will return an empty string with ErrNoSuchField. If there are multiple References headers, it will return ErrManyFields.

func (*Header) GetReplyTo 

func (h *Header) GetReplyTo() (addr.AddressList, error)

GetReplyTo returns the ReplyTo address field as an addr.AddressList.

It will return nil and ErrNoSuchField if the field is not set on the header. It will return ErrManyFields if the field is set more than once on the header.

func (*Header) GetSender 

func (h *Header) GetSender() (addr.AddressList, error)

GetSender returns the address list in the Sender header, if any.

It will return nil and ErrNoSuchField if the field is not set on the header. It will return ErrManyFields if the field is set more than once on the header.

func (*Header) GetSubject 

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

GetSubject returns the value of the Subject header field.

If Subject is not set in the header, it will return an empty string with ErrNoSuchField. If there are multiple Subject headers, it will return ErrManyFields.

func (*Header) GetTime 

func (h *Header) GetTime(name string) (time.Time, error)

GetTime gets the given date header field as a time.Time. It will attempt to parse the date in many formats, not just the format specified by RFC 5322 (though, it will try that first).

It will return an error if it is unable to parse the time value from the date header. It will return the zero value and ErrNoSuchField if the header does not exist. It will return the zero value and ErrManyFields if more than one field with the name is set on the header.

func (*Header) GetTo 

func (h *Header) GetTo() (addr.AddressList, error)

GetTo returns the To address field as an addr.AddressList.

It will return nil and ErrNoSuchField if the field is not set on the header. It will return ErrManyFields if the field is set more than once on the header.

func (*Header) GetTransferEncoding 

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

GetTransferEncoding returns the content of the Content-transfer-encoding header.

It will return ErrNoSuchField if the header is not set. it will return ErrManyFields if the field is set more than once.

func (*Header) Set 

func (h *Header) Set(name, body string)

Set will replace all existing header fields with the given name with a single header field with the given name and body. If the field already exists on the header, then the first occurrence will be replaced with this value and any other values will be deleted. If the field does not exist, it will be appended to the end of the header.

The procedure for replacing above is used to fall the Set* methods that replace all fields with a single field.

func (*Header) SetAddressList 

func (h *Header) SetAddressList(name string, body ...addr.Address)

SetAddressList will replace all existing header fields with the given name with a single header containing the given addr.AddressList.

func (*Header) SetAll 

func (h *Header) SetAll(name string, bodies ...string)

SetAll replaces all the header fields with the given name with the bodies given. After a successful completion of this method, the field with the given name will occur exactly len(bodies) times in the header. If the field is already present in the header, existing fields will have their bodies replaced with the new values. Any new fields will be appended to the end of the header.

func (*Header) SetAllAddressLists 

func (h *Header) SetAllAddressLists(name string, bodies ...addr.AddressList)

SetAllAddressLists will replace all existing header fields with a new set of header fields from the given slice of addr.AddressList.

func (*Header) SetBcc 

func (h *Header) SetBcc(a ...any) error

SetBcc sets the Bcc address field with either an addr.AddressList or a string.

It will fail with an error returned if something other than those types is provided or if the given string fails to strictly parse.

func (*Header) SetBoundary 

func (h *Header) SetBoundary(b string) error

SetBoundary sets the boundary on the Content-type header.

This method fails with a ErrNoSuchField if the field is not set on the header. This method fails with an error if the parameter values cannot be parsed out of the field for some reason.

func (*Header) SetCc 

func (h *Header) SetCc(a ...any) error

SetCc sets the Cc address field with either an addr.AddressList or a string.

It will fail with an error returned if something other than those types is provided or if the given string fails to strictly parse.

func (*Header) SetCharset 

func (h *Header) SetCharset(c string) error

SetCharset sets the charset on the Content-type header.

This method fails with a ErrNoSuchField if the field is not set on the header. This method fails with an error if the parameter values cannot be parsed out of the field for some reason.

func (*Header) SetComments 

func (h *Header) SetComments(cs ...string)

SetComments replaces all Comments fields with the given bodies.

func (*Header) SetContentDisposition 

func (h *Header) SetContentDisposition(v *param.Value)

SetContentDisposition sets the Content-disposition to a new value from a param.Value.

func (*Header) SetContentType 

func (h *Header) SetContentType(v *param.Value)

SetContentType replaces the Content-type with the given param.Value.

func (*Header) SetDate 

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

SetDate updates the Date header from the given time.Time value.

func (*Header) SetFilename 

func (h *Header) SetFilename(f string) error

SetFilename sets the filename parameter of the Content-disposition header.

This method fails with a ErrNoSuchField if the field is not set on the header. This method fails with an error if the parameter values cannot be parsed out of the field for some reason.

func (*Header) SetFrom 

func (h *Header) SetFrom(a ...any) error

SetFrom sets the From address field with either an addr.AddressList or a string.

It will fail with an error returned if something other than those types is provided or if the given string fails to strictly parse.

func (*Header) SetInReplyTo 

func (h *Header) SetInReplyTo(ref string)

SetInReplyTo returns the message ID in the In-reply-to header.

func (*Header) SetKeywords 

func (h *Header) SetKeywords(ks ...string)

SetKeywords sets keywords on the Keywords header.

func (*Header) SetKeywordsList 

func (h *Header) SetKeywordsList(name string, keywords ...string)

SetKeywordsList will replace all Keywords headers currently set in the header with one Keywords header with all the given keywords separated by a comma.

func (*Header) SetMediaType 

func (h *Header) SetMediaType(mt string)

SetMediaType replaces the MIME type on the Content-type header, creating it if it has not been set yet. If the Content-type header already exists, any other parameters already set will be preserved. If this header is set multiple times (in violation of RFC 5322), it will remove all but the first instance and replace the media type of the first instance.

func (*Header) SetMessageID 

func (h *Header) SetMessageID(ref string)

SetMessageID sets the Message-ID header of the message header.

func (*Header) SetParamValue 

func (h *Header) SetParamValue(name string, body *param.Value)

SetParamValue will replace all existing header fields with the given name with a single param.Value header containing the given param.Value.

func (*Header) SetPresentation 

func (h *Header) SetPresentation(d string)

SetPresentation sets the disposition value of the Content-disposition header field. If the Content-disposition header already exists, any other parameters already set will be preserved. If this header is set multiple times (in violation of RFC 5322), it will remove all but the first instance and replace the presentation of the first instance.

func (*Header) SetReferences 

func (h *Header) SetReferences(ref string)

SetReferences sets the message ID to store in the References header.

func (*Header) SetReplyTo 

func (h *Header) SetReplyTo(a ...any) error

SetReplyTo sets the ReplyTo address field with either an addr.AddressList or a string.

It will fail with an error returned if something other than those types is provided or if the given string fails to strictly parse.

func (*Header) SetSender 

func (h *Header) SetSender(a ...any) error

SetSender sets the Sender address field with either an addr.AddressList or a string.

It will fail with an error returned if something other than those types is provided or if the given string fails to strictly parse.

func (*Header) SetSubject 

func (h *Header) SetSubject(s string)

SetSubject replaces the Subject header field.

func (*Header) SetTime 

func (h *Header) SetTime(name string, body time.Time)

SetTime will replace all existing header fields with the given name with a single header field with the given name and time. The time will be formatted via time.RFC1123Z.

func (*Header) SetTo 

func (h *Header) SetTo(a ...any) error

SetTo sets the To address field with either an addr.AddressList or a string.

It will fail with an error returned if something other than those types is provided or if the given string fails to strictly parse.

func (*Header) SetTransferEncoding 

func (h *Header) SetTransferEncoding(b string)

SetTransferEncoding replaces the Content-transfer-encoding with the given value.

Source Files

View all Source files

Directories

Path Synopsis
Package encoding provides a replacement encoder and decoder for use with mime.CharsetEncoder and mime.CharsetDecoder.
 Package encoding provides a replacement encoder and decoder for use with mime.CharsetEncoder and mime.CharsetDecoder.
Package field provides low-level functions and types for working with individual header fields.
 Package field provides low-level functions and types for working with individual header fields.
Package param provides a tool for dealing with parameterized headers.
 Package param provides a tool for dealing with parameterized headers.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.