letters

package module
v0.2.5 Latest Latest
Warning

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

 Go to latest Published: Feb 26, 2025 License: MIT Imports: 13 Imported by: 11

README

Letters, or how to parse emails in Go

Go Reference Test Go Report Card

Letters is a minimalistic Golang library for parsing plaintext and MIME emails.

It correctly handles text and MIME mime-types, Base64 and Quoted-Printable Content-Transfer-Encoding, as well as any text encoding that Golang standard library is capable of handling. Letters will parse an email into a simple struct with standard headers and text, enriched text, and HTML content, and decode inline and attached files.

The User Guide

Installation

Install Letters:

go get github.com/mnako/letters@v0.2.5
Quickstart

This section documents the simplified API of Letters.

Parse an Email

The quickest way to get started with parsing emails with Letters is to use the letters.ParseEmail() helper function. It takes an io.Reader with the contents of the email, parses it using the default parser, and returns an Email struct or an error:

package main

import (
  "log"
  "os"

  "github.com/mnako/letters"
)

func main() {
  rawEmail, err := os.Open("email.eml")
  if err != nil {
    log.Fatal("error while reading email from file: %w", err)
    return
  }

  defer func() {
    if err := rawEmail.Close(); err != nil {
      log.Fatal("error while closing rawEmail: %w", err)
      return
    }
  }()

  email, err := letters.ParseEmail(rawEmail)
  if err != nil {
    log.Fatal(err)
  }
}

Now, you can access the common headers:

email.Headers.Sender
// mail.Address{Name: "Alice Sender", Address: "alice.sender@example.com"}

email.Headers.From
// []mail.Address{
//  {Name: "Alice Sender", Address: "alice.sender@example.com"},
//  {Name: "Alice Sender", Address: "alice.sender@example.net"},
// }

email.Headers.Subject
// "📧 Test English Pangrams"

email.Headers.To
// []mail.Address{
//  {Name: "Bob Recipient", Address: "bob.recipient@example.com"},
//  {Name: "Carol Recipient", Address: "carol.recipient@example.com"},
// }

email.Headers.Cc
// []mail.Address{
//  {Name: "Dan Recipient", Address: "dan.recipient@example.com"},
//  {Name: "Eve Recipient", Address: "eve.recipient@example.com"},
// }

email.Headers.Bcc
// []mail.Address{
//  {Name: "Frank Recipient", Address: "frank.recipient@example.com"},
//  {Name: "Grace Recipient", Address: "grace.recipient@example.com"},
// }

and custom headers:

email.Headers.ExtraHeaders
// map[string][]string{
//    "X-Clacks-Overhead": {"GNU Terry Pratchett"},
// }

get decoded bodies:

email.Text
// "The quick brown fox jumps over a lazy dog..."

email.HTML
// "<html><div dir="ltr"><p>The quick brown fox jumps over a lazy dog..."

inline files:

email.InlineFiles
// []InlineFile{
//    {
//        ContentType: ContentTypeHeader{
//            ContentType: "image/jpeg",
//            Params: map[string]string{
//                "name": "inline-jpg-image-without-disposition.jpg",
//            },
//        },
//        ContentDisposition: ContentDispositionHeader{
//            ContentDisposition: "",
//            Params:             map[string]string(nil),
//        },
//        Data: []byte{255, ...},
//    },
//    {
//        ContentID: "inline-jpg-image.jpg@example.com",
//        ContentType: ContentTypeHeader{
//            ContentType: "image/jpeg",
//            Params: map[string]string{
//                "name": "inline-jpg-image-name.jpg",
//            },
//        },
//        ContentDisposition: ContentDispositionHeader{
//            ContentDisposition: inline,
//            Params: map[string]string{
//                "filename": "inline-jpg-image-filename.jpg",
//            },
//        },
//        Data: []byte{255, ...},
//    },
// }

and attached files:

email.AttachedFiles
// []AttachedFile{
//    {
//        ContentType: ContentTypeHeader{
//            ContentType: "application/pdf",
//            Params: map[string]string{
//                "name": "attached-pdf-name.pdf",
//            },
//        },
//        ContentDisposition: ContentDispositionHeader{
//            ContentDisposition: attachment,
//            Params: map[string]string{
//                "filename": "attached-pdf-filename.pdf",
//            },
//        },
//        Data: []byte{37, ...},
//    },
//    {
//        ContentType: ContentTypeHeader{
//            ContentType: "application/pdf",
//            Params: map[string]string{
//                "name": "attached-pdf-without-disposition.pdf",
//            },
//        },
//        ContentDisposition: ContentDispositionHeader{
//            ContentDisposition: "",
//            Params:             map[string]string(nil),
//        },
//        Data: []byte{37, ...},
// }

The same default parser and methods will work for other languages, text encodings, and transfer-encodings:

r := strings.NewReader(```Subject: =?ISO-2022-JP?Q?=1B=24=42=24=24=24=6D=24=4F=32=4E=1B=28=42?=
Content-Type: text/plain; charset=ISO-2022-JP


=1B$B?'$OFw$($I=1B(B
=1B$B;6$j$L$k$r=1B(B```)

email, _ := letters.ParseEmail(r)

email.Headers.Subject
// "いろは歌"

email.Text
// "色は匂えど散りぬるを..."
Parse Email Headers

If you already have a mail.Message and you are only interested in the headers of the email, you can use the letters.ParseEmailHeaders() helper function. It takes a mail.Header with the whole head section of an email, parses it using the default parser, and returns a letters.Headers struct or an error:

msg, err := mail.ReadMessage(rawEmail)
if err != nil {
    log.Fatal("error while reading message from file: %s", err)
    return
}

headers, err := letters.ParseEmailHeaders(msg.Header)
if err != nil {
    log.Fatal("error while parsing email headers: %s", err)
    return
}

headers.Sender
// mail.Address{Name: "Alice Sender", Address: "alice.sender@example.com"}

headers.Headers.From
// []mail.Address{
//  {Name: "Alice Sender", Address: "alice.sender@example.com"},
//  {Name: "Alice Sender", Address: "alice.sender@example.net"},
// }

// ...

[!TIP] The letters.ParseEmail() and letters.ParseEmailHeaders() helpers exist for developers' convenience and are a good entrypoint to get started quickly. However, if you find yourself in need of customising the parser to, i.a. parse non-compliant headers or conditionally parse only some parts of the email, we recommend following the Advanced Usage section below for a more flexible and maintainable approach.

Advanced Usage

This section documents come of Letters more advanced features.

The Email Parser

The letters.ParseEmail() documented above is a helper function that creates a default email parser and returns the parsed email and error.

You can replace it with the following code to have more control over the parser:

defaultEmailParser := letters.NewEmailParser()
email, err := defaultEmailParser.Parse(rawEmail)
if err != nil {
    log.Fatal(err)
}
Skipping Parts of the Email

By default, letters parses all bodies and files.

You can configure the parser to parse all, some, or none bodies, and files using functional filters.

A functional body filter is a function that takes the Content-Type header of the part and returns true or false. Only bodies for which the filter returns true will be parsed. Parts for which the filter returned false, will be skipped.

Similar to the body filter, a functional file filter is a function that takes the Content-Type and Content-Disposition headers of the part and returns true or false. Only files for which the filter returns true will be parsed. Files for which the filter returned false, will be skipped.

For example, if you do not want to parse any files, you can configure the Email Parser with a file filter that always returns false. For convenience, letters includes a NoFiles filter that does precisely that:

noFilesEmailParser := letters.NewEmailParser(
    letters.WithFileFilter(NoFiles),
)
email, err := noFilesEmailParser.Parse(rawEmail)
if err != nil {
    log.Fatal(err)
}

Letters includes the following convenience filters:

  • NoBodies, a function that always returns false, that can be used with WithBodyFilter(), to skip parsing all bodies of the email;
  • AllBodies, a function that always returns true, that can be used with WithBodyFilter(), to parse all bodies of the email. This is the default behaviour;
  • NoFiles, a function that always returns false, that can be used with WithFileFilter(), to skip parsing all attachments of the email. This option can speed up parsing in use cases where attachments are not needed;
  • AllFiles, a function that always returns true, that can be used with WithFileFilter(), to parse all attachments of the email. This is the default behaviour;

This means that WithBodyFilter(NoBodies) is the more flexible equivalent of the ParseEmailHeaders() helper function from the Quickstart section above, as it allows you to parse only the headers of the email.

More interestingly, bodies and files can be skipped conditionally: bodies can be skipped based on the Content-Type header of the part, and files can be skipped based on the Content-Type and the Content-Disposition headers of the part.

For example, to only parse files with a filename that ends with ".jpg," you can pass a custom File Filter that checks the name Param of the Content-Type header:

customJPGOnlyEmailParser := letters.NewEmailParser(
    letters.WithFileFilter(
        func(
            cth letters.ContentTypeHeader,
            _ letters.ContentDispositionHeader,
        ) bool {
            return strings.HasSuffix(
                strings.ToLower(cth.Params["name"]),
                ".jpg",
            )
        },
    ),
)
email, err := customJPGOnlyEmailParser.Parse(rawEmail)

Files can be filtered based on the Content-Disposition header as well. For example, to parse only inline files and skip attachments, you can pass a custom File Filter that checks the Content-Disposition header:

inlineFilesOnlyParser := letters.NewEmailParser(
    letters.WithFileFilter(
        func(
            _ letters.ContentTypeHeader,
            cdh letters.ContentDispositionHeader,
        ) bool {
            return cdh.ContentDisposition == letters.ContentDispositionInline
        },
    ),
)

You can implement arbitrarily complex conditions with those filter.

Customising Headers Parsers

Letters aims to be spec-compliant and follow email-related RFCs closely. Not all emails that you will encounter in the wild will be compliant with the RFCs, though.

To allow parsing such emails without adding exceptions to the library itself, you can freely customise the parsers according to your needs with With<HeaderName>HeaderParser() options.

For example, to customise the parser for the Date header, you can pass a custom parser function to the WithDateHeaderParser() option:

customDateHeaderEmailParser := letters.NewEmailParser(
    letters.WithHeaderParser(
        func(s string) time.Time {
            // Decode and parse the raw Date header from the s string here
            // and return a time.Time object
        },
    ),
)

Custom parsers for every header can be specified separately. E.g., if you want to customise parsing of all dates, you need to specify a custom parser for the Date header and for the ResentDate header.

The following headers are included in the letters.Headers struct and the following options and types are available:

Header Option Expected Parser Signature
Date WithDateHeaderParser(parseDateHeaderFn) func(string) time.Time
Sender WithSenderHeaderParser(parseAddressHeaderFn) func(mail.Header, string) (*mail.Address, error)
From WithFromHeaderParser(parseAddressListHeaderFn) func(mail.Header, string) ([]*mail.Address, error)
Reply-To WithReplyToHeaderParser(parseAddressListHeaderFn) func(mail.Header, string) ([]*mail.Address, error)
To WithToHeaderParser(parseAddressListHeaderFn) func(mail.Header, string) ([]*mail.Address, error)
Cc WithCcHeaderParser(parseAddressListHeaderFn) func(mail.Header, string) ([]*mail.Address, error)
Bcc WithBccHeaderParser(parseAddressListHeaderFn) func(mail.Header, string) ([]*mail.Address, error)
Message-ID WithMessageIdHeaderParser(parseMessageIdHeaderFn) func(string) letters.MessageId
In-Reply-To WithInReplyToHeaderParser(parseCommaSeparatedMessageIdHeaderFn) func(string) []letters.MessageId
References WithReferencesHeaderParser(parseCommaSeparatedMessageIdHeaderFn) func(string) []letters.MessageId
Subject WithSubjectHeaderParser(parseStringHeaderFn) func(string) string
Comments WithCommentsHeaderParser(parseStringHeaderFn) func(string) string
Keywords WithKeywordsHeaderParser(parseCommaSeparatedStringHeaderFn) func(string) []string
Resent-Date WithResentDateHeaderParser(parseDateHeaderFn) func(string) time.Time
Resent-From WithResentFromHeaderParser(parseAddressListHeaderFn) func(mail.Header, string) ([]*mail.Address, error)
Resent-Sender WithResentSenderHeaderParser(parseAddressHeaderFn) func(mail.Header, string) (*mail.Address, error)
Resent-To WithResentToHeaderParser(parseAddressListHeaderFn) func(mail.Header, string) ([]*mail.Address, error)
Resent-Cc WithResentCcHeaderParser(parseAddressListHeaderFn) func(mail.Header, string) ([]*mail.Address, error)
Resent-Bcc WithResentBccHeaderParser(parseAddressListHeaderFn) func(mail.Header, string) ([]*mail.Address, error)
Resent-Message-ID WithResentMessageIdHeaderParser(parseMessageIdHeaderFn) func(string) letters.MessageId
Content-Type WithContentTypeHeaderParser(parseContentTypeHeaderFn) func(string) (letters.ContentTypeHeader, error)
Content-Disposition WithContentDispositionHeaderParser(parseContentDispositionHeaderFn) func(string) (letters.ContentDispositionHeader, error)
Customising Extra Headers Parsers

The RFC-documented headers, their corresponding options and parser signatures are strictly typed.

Letters allows parsing custom headers to the ExtraHeaders map in the letters.Headers struct. You can freely customise the parsers according to your needs with the WithExtraHeaderParser(headerName string, extraHeaderParserFn parseStringHeaderFn) option.

For example, you can customise parsing the X-CrossPremisesHeadersPromoted header:

xCrossPremisesHeadersPromotedHeaderParser := func(s string) string {
    // ...
    return xCrossPremisesHeadersPromotedHeader
}

customEmailParser := letters.NewEmailParser(
    letters.WithExtraHeaderParser(
        "X-CrossPremisesHeadersPromoted",
        xCrossPremisesHeadersPromotedHeaderParser,
      ),
)

You can also specify custom parsers for many extra headers:

xCrossPremisesHeadersPromotedHeaderParser := func(s string) string {
    // ...
    return xCrossPremisesHeadersPromotedHeader
}

xMSExchangeOrganizationProcessedByJournalingHeaderParser := func(s string) string {
    // ...
    return xMSExchangeOrganizationProcessedByJournalingHeader
}

xMSExchangeOrganizationOriginalEnvelopeRecipientsHeaderParser := func(s string) string {
    // ...
    return xMSExchangeOrganizationOriginalEnvelopeRecipientsHeader
}

customEmailParser := letters.NewEmailParser(
    letters.WithExtraHeaderParser(
        "X-CrossPremisesHeadersPromoted",
        xCrossPremisesHeadersPromotedHeaderParser,
    ),
    letters.WithExtraHeaderParser(
        "X-MS-Exchange-Organization-Processed-By-Journaling",
        xMSExchangeOrganizationProcessedByJournalingHeaderParser,
    ),
    letters.WithExtraHeaderParser(
        "X-MS-Exchange-Organization-OriginalEnvelopeRecipients",
        xMSExchangeOrganizationOriginalEnvelopeRecipientsHeaderParser,
    ),
)

Current Scope and Features

  • Parsing plaintext emails and recursively traversing multipart (multipart/alternative, multipart/mixed, multipart/parallel, multipart/related, multipart/signed) emails
  • Unfolding headers
  • Decoding non-US-ASCII email headers according to RFC 2047
  • Decoding Base64 and Quoted-Printable Content-Transfer-Encodings
  • Decoding any text encoding (e.g. UTF-8, Chinese GB18030 or GBK, Finnish ISO-8859-15, Icelandic ISO-8859-1, Japanese ISO-2022-JP, Korean EUC-KR, Polish ISO-8859-2) in combination with any Transfer Encoding (e.g. ASCII-over-7bit, UTF-8-over-Base64, Japanese ISO-2022-JP-over-7bit, Polish ISO-8859-2-over-Quoted-Printable, etc.)
  • Easy access to text, enriched text and HTML content of the email
  • Easy access to inline attachments
  • Easy access to attached files

All of that and more in a minimal Golang library with realistic email examples and thorough test coverage.

Current Limitations

  • S/MIME multipart/signed email are limited to clear-signed messages
  • The decryption and signature verification and any other cryptography-related tasks need to be performed outside of letters.

Current Status

Feature-complete and tests passing.

Currently, gathering feedback and refactoring code before releasing v1.0.0. Fields and API are still subject to change.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AllBodies added in v0.2.4 

func AllBodies(_ ContentTypeHeader) bool

func AllFiles added in v0.2.4 

func AllFiles(_ ContentTypeHeader, __ ContentDispositionHeader) bool

func NoBodies added in v0.2.4 

func NoBodies(_ ContentTypeHeader) bool

func NoFiles added in v0.2.4 

func NoFiles(_ ContentTypeHeader, __ ContentDispositionHeader) bool

func ParseAddressHeader added in v0.2.5 

func ParseAddressHeader(
	header mail.Header,
	name string,
) (*mail.Address, error)

func ParseAddressListHeader added in v0.2.5 

func ParseAddressListHeader(
	header mail.Header,
	name string,
) ([]*mail.Address, error)

func ParseCommaSeparatedStringHeader added in v0.2.5 

func ParseCommaSeparatedStringHeader(s string) []string

func ParseDateHeader added in v0.2.5 

func ParseDateHeader(s string) time.Time

func ParseDefaultMediaType added in v0.2.5 

func ParseDefaultMediaType(s string) (string, map[string]string, error)

func ParseStringHeader added in v0.2.5 

func ParseStringHeader(s string) string

Types

type AttachedFile 

type AttachedFile struct {
	ContentType        ContentTypeHeader
	ContentDisposition ContentDispositionHeader
	Data               []byte
}

type ContentDisposition 

type ContentDisposition string
const (
	ContentDispositionAttachment ContentDisposition = "attachment"
	ContentDispositionInline     ContentDisposition = "inline"
)

type ContentDispositionHeader 

type ContentDispositionHeader struct {
	ContentDisposition ContentDisposition
	Params             map[string]string
}

func ParseContentDisposition added in v0.2.5 

func ParseContentDisposition(s string) (ContentDispositionHeader, error)

type ContentTransferEncoding 

type ContentTransferEncoding string

func ParseContentTransferEncoding added in v0.2.5 

func ParseContentTransferEncoding(s string) (ContentTransferEncoding, error)

type ContentTypeHeader 

type ContentTypeHeader struct {
	ContentType string
	Params      map[string]string
}

func ParseContentTypeHeader added in v0.2.5 

func ParseContentTypeHeader(s string) (ContentTypeHeader, error)

type Email 

type Email struct {
	Headers Headers

	Text         string
	EnrichedText string // See RFC 1523, RFC 1563, and RFC 1896
	HTML         string

	InlineFiles   []InlineFile
	AttachedFiles []AttachedFile
}

func ParseEmail 

func ParseEmail(r io.Reader) (Email, error)

type EmailBodyFilter added in v0.2.4 

type EmailBodyFilter func(cth ContentTypeHeader) bool

type EmailFileFilter added in v0.2.4 

type EmailFileFilter func(cth ContentTypeHeader, cdh ContentDispositionHeader) bool

type EmailParser added in v0.2.4 

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

func NewEmailParser added in v0.2.4 

func NewEmailParser(options ...EmailParserOption) *EmailParser

func (*EmailParser) Parse added in v0.2.4 

func (ep *EmailParser) Parse(r io.Reader) (Email, error)

func (*EmailParser) ParseHeaders added in v0.2.5 

func (ep *EmailParser) ParseHeaders(header mail.Header) (Headers, error)

type EmailParserOption added in v0.2.4 

type EmailParserOption func(*EmailParser)

func WithBccHeaderParser added in v0.2.5 

func WithBccHeaderParser(
	bccHeaderParserFn parseAddressListHeaderFn,
) EmailParserOption

func WithBodyFilter added in v0.2.4 

func WithBodyFilter(bodyFilter EmailBodyFilter) EmailParserOption

func WithCcHeaderParser added in v0.2.5 

func WithCcHeaderParser(
	ccHeaderParserFn parseAddressListHeaderFn,
) EmailParserOption

func WithCommentsHeaderParser added in v0.2.5 

func WithCommentsHeaderParser(
	commentsHeaderParserFn parseStringHeaderFn,
) EmailParserOption

func WithContentDispositionHeaderParser added in v0.2.5 

func WithContentDispositionHeaderParser(
	contentDispositionHeaderParserFn parseContentDispositionHeaderFn,
) EmailParserOption

func WithContentTypeHeaderParser added in v0.2.5 

func WithContentTypeHeaderParser(
	contentTypeHeaderParserFn parseContentTypeHeaderFn,
) EmailParserOption

func WithDateHeaderParser added in v0.2.5 

func WithDateHeaderParser(
	dateHeaderParserFn parseDateHeaderFn,
) EmailParserOption

func WithExtraHeaderParser added in v0.2.5 

func WithExtraHeaderParser(
	headerName string,
	extraHeaderParserFn parseStringHeaderFn,
) EmailParserOption

func WithFileFilter added in v0.2.4 

func WithFileFilter(fileFilter EmailFileFilter) EmailParserOption

func WithFromHeaderParser added in v0.2.5 

func WithFromHeaderParser(
	fromHeaderParserFn parseAddressListHeaderFn,
) EmailParserOption

func WithHeadersParsers added in v0.2.5 

func WithHeadersParsers(headersParsers HeadersParsers) EmailParserOption

func WithInReplyHeaderParser added in v0.2.5 

func WithInReplyHeaderParser(
	inReplyHeaderParserFn parseCommaSeparatedMessageIdHeaderFn,
) EmailParserOption

func WithKeywordsHeaderParser added in v0.2.5 

func WithKeywordsHeaderParser(
	keywordsHeaderParserFn parseCommaSeparatedStringHeaderFn,
) EmailParserOption

func WithMessageIdHeaderParser added in v0.2.5 

func WithMessageIdHeaderParser(
	messageIDHeaderParserFn parseMessageIdHeaderFn,
) EmailParserOption

func WithReferencesHeaderParser added in v0.2.5 

func WithReferencesHeaderParser(
	referencesHeaderParserFn parseCommaSeparatedMessageIdHeaderFn,
) EmailParserOption

func WithReplyToHeaderParser added in v0.2.5 

func WithReplyToHeaderParser(
	replyToHeaderParserFn parseAddressListHeaderFn,
) EmailParserOption

func WithResentCcHeaderParser added in v0.2.5 

func WithResentCcHeaderParser(
	resentCcHeaderParserFn parseAddressListHeaderFn,
) EmailParserOption

func WithResentDateHeaderParser added in v0.2.5 

func WithResentDateHeaderParser(
	resentDateHeaderParserFn parseDateHeaderFn,
) EmailParserOption

func WithResentFromHeaderParser added in v0.2.5 

func WithResentFromHeaderParser(
	resentFromHeaderParserFn parseAddressListHeaderFn,
) EmailParserOption

func WithResentFromParser added in v0.2.5 

func WithResentFromParser(
	resentFromHeaderParserFn parseAddressListHeaderFn,
) EmailParserOption

func WithResentMessageIdHeaderParser added in v0.2.5 

func WithResentMessageIdHeaderParser(
	resentMessageIDHeaderParserFn parseMessageIdHeaderFn,
) EmailParserOption

func WithResentSenderHeaderParser added in v0.2.5 

func WithResentSenderHeaderParser(
	resentSenderHeaderParserFn parseAddressHeaderFn,
) EmailParserOption

func WithResentToHeaderParser added in v0.2.5 

func WithResentToHeaderParser(
	resentToHeaderParserFn parseAddressListHeaderFn,
) EmailParserOption

func WithSenderHeaderParser added in v0.2.5 

func WithSenderHeaderParser(
	senderHeaderParserFn parseAddressHeaderFn,
) EmailParserOption

func WithSubjectHeaderParser added in v0.2.5 

func WithSubjectHeaderParser(
	subjectHeaderParserFn parseStringHeaderFn,
) EmailParserOption

func WithToHeaderParser added in v0.2.5 

func WithToHeaderParser(
	toHeaderParserFn parseAddressListHeaderFn,
) EmailParserOption

type Headers 

type Headers struct {
	// RFC 3522 3.6.1.  The Origination Date Field
	// The origination date field consists of the field name "Date" followed
	// by a date-time specification.
	//
	// orig-date       =   "Date:" date-time CRLF
	//
	// The origination date specifies the date and time at which the creator
	// of the message indicated that the message was complete and ready to
	// enter the mail delivery system.  For instance, this might be the time
	// that a user pushes the "send" or "submit" button in an application
	// program.  In any case, it is specifically not intended to convey the
	// time that the message is actually transported, but rather the time at
	// which the human or other creator of the message has put the message
	// into its final form, ready for transport.  (For example, a portable
	// computer user who is not connected to a network might queue a message
	// for delivery.  The origination date is intended to contain the date
	// and time that the user queued the message, not the time when the user
	// connected to the network to send the message.)
	Date time.Time

	// RFC 3522 3.6.2.  Originator Fields
	//
	// The originator fields of a message consist of the from field, the
	// sender field (when applicable), and optionally the reply-to field.
	// The from field consists of the field name "From" and a comma-
	// separated list of one or more mailbox specifications.  If the from
	// field contains more than one mailbox specification in the mailbox-
	// list, then the sender field, containing the field name "Sender" and a
	// single mailbox specification, MUST appear in the message.  In either
	// case, an optional reply-to field MAY also be included, which contains
	// the field name "Reply-To" and a comma-separated list of one or more
	// addresses.
	//
	// from            =   "From:" mailbox-list CRLF
	//
	// sender          =   "Sender:" mailbox CRLF
	//
	// reply-to        =   "Reply-To:" address-list CRLF
	//
	// The originator fields indicate the mailbox(es) of the source of the
	// message.  The "From:" field specifies the author(s) of the message,
	// that is, the mailbox(es) of the person(s) or system(s) responsible
	// for the writing of the message.  The "Sender:" field specifies the
	// mailbox of the agent responsible for the actual transmission of the
	// message.  For example, if a secretary were to send a message for
	// another person, the mailbox of the secretary would appear in the
	// "Sender:" field and the mailbox of the actual author would appear in
	// the "From:" field.  If the originator of the message can be indicated
	// by a single mailbox and the author and transmitter are identical, the
	// "Sender:" field SHOULD NOT be used.  Otherwise, both fields SHOULD
	// appear.
	//
	//    Note: The transmitter information is always present.  The absence
	//    of the "Sender:" field is sometimes mistakenly taken to mean that
	//    the agent responsible for transmission of the message has not been
	//    specified.  This absence merely means that the transmitter is
	//    identical to the author and is therefore not redundantly placed
	//    into the "Sender:" field.
	//
	// The originator fields also provide the information required when
	// replying to a message.  When the "Reply-To:" field is present, it
	// indicates the address(es) to which the author of the message suggests
	// that replies be sent.  In the absence of the "Reply-To:" field,
	// replies SHOULD by default be sent to the mailbox(es) specified in the
	// "From:" field unless otherwise specified by the person composing the
	// reply.
	//
	// In all cases, the "From:" field SHOULD NOT contain any mailbox that
	// does not belong to the author(s) of the message.  See also section
	// 3.6.3 for more information on forming the destination addresses for a
	// reply.
	Sender  *mail.Address
	From    []*mail.Address
	ReplyTo []*mail.Address

	// RFC 3522 3.6.3.  Destination Address Fields
	//
	// The destination fields of a message consist of three possible fields,
	// each of the same form: the field name, which is either "To", "Cc", or
	// "Bcc", followed by a comma-separated list of one or more addresses
	// (either mailbox or group syntax).
	//
	// to              =   "To:" address-list CRLF
	//
	// cc              =   "Cc:" address-list CRLF
	//
	// bcc             =   "Bcc:" [address-list / CFWS] CRLF
	//
	// The destination fields specify the recipients of the message.  Each
	// destination field may have one or more addresses, and the addresses
	// indicate the intended recipients of the message.  The only difference
	// between the three fields is how each is used.
	//
	// The "To:" field contains the address(es) of the primary recipient(s)
	// of the message.
	To  []*mail.Address
	Cc  []*mail.Address
	Bcc []*mail.Address

	// RFC 3522 3.6.4.  Identification Fields
	//
	// Though listed as optional in the table in section 3.6, every message
	// SHOULD have a "Message-ID:" field.  Furthermore, reply messages
	// SHOULD have "In-Reply-To:" and "References:" fields as appropriate
	// and as described below.
	//
	// The "Message-ID:" field contains a single unique message identifier.
	// The "References:" and "In-Reply-To:" fields each contain one or more
	// unique message identifiers, optionally separated by CFWS.
	//
	// The message identifier (msg-id) syntax is a limited version of the
	// addr-spec construct enclosed in the angle bracket characters, "<" and
	// ">".  Unlike addr-spec, this syntax only permits the dot-atom-text
	// form on the left-hand side of the "@" and does not have internal CFWS
	// anywhere in the message identifier.
	//
	//    Note: As with addr-spec, a liberal syntax is given for the right-
	//    hand side of the "@" in a msg-id.  However, later in this section,
	//    the use of a domain for the right-hand side of the "@" is
	//    RECOMMENDED.  Again, the syntax of domain constructs is specified
	//    by and used in other protocols (e.g., [RFC1034], [RFC1035],
	//    [RFC1123], [RFC5321]).  It is therefore incumbent upon
	//    implementations to conform to the syntax of addresses for the
	//    context in which they are used.
	//
	// message-id      =   "Message-ID:" msg-id CRLF
	//
	// in-reply-to     =   "In-Reply-To:" 1*msg-id CRLF
	//
	// references      =   "References:" 1*msg-id CRLF
	//
	// msg-id          =   [CFWS] "<" id-left "@" id-right ">" [CFWS]
	//
	// id-left         =   dot-atom-text / obs-id-left
	//
	// id-right        =   dot-atom-text / no-fold-literal / obs-id-right
	//
	// no-fold-literal =   "[" *dtext "]"
	//
	// The "Message-ID:" field provides a unique message identifier that
	// refers to a particular version of a particular message.  The
	// uniqueness of the message identifier is guaranteed by the host that
	// generates it (see below).  This message identifier is intended to be
	// machine readable and not necessarily meaningful to humans.  A message
	// identifier pertains to exactly one version of a particular message;
	// subsequent revisions to the message each receive new message
	// identifiers.
	//
	//    Note: There are many instances when messages are "changed", but
	//    those changes do not constitute a new instantiation of that
	//    message, and therefore the message would not get a new message
	//    identifier.  For example, when messages are introduced into the
	//    transport system, they are often prepended with additional header
	//    fields such as trace fields (described in section 3.6.7) and
	//    resent fields (described in section 3.6.6).  The addition of such
	//    header fields does not change the identity of the message and
	//    therefore the original "Message-ID:" field is retained.  In all
	//    cases, it is the meaning that the sender of the message wishes to
	//    convey (i.e., whether this is the same message or a different
	//    message) that determines whether or not the "Message-ID:" field
	//    changes, not any particular syntactic difference that appears (or
	//    does not appear) in the message.
	//
	// The "In-Reply-To:" and "References:" fields are used when creating a
	// reply to a message.  They hold the message identifier of the original
	// message and the message identifiers of other messages (for example,
	// in the case of a reply to a message that was itself a reply).  The
	// "In-Reply-To:" field may be used to identify the message (or
	// messages) to which the new message is a reply, while the
	// "References:" field may be used to identify a "thread" of
	// conversation.
	//
	// When creating a reply to a message, the "In-Reply-To:" and
	// "References:" fields of the resultant message are constructed as
	// follows:
	//
	// The "In-Reply-To:" field will contain the contents of the
	// "Message-ID:" field of the message to which this one is a reply (the
	// "parent message").  If there is more than one parent message, then
	// the "In-Reply-To:" field will contain the contents of all of the
	// parents' "Message-ID:" fields.  If there is no "Message-ID:" field in
	// any of the parent messages, then the new message will have no "In-
	// Reply-To:" field.
	//
	// The "References:" field will contain the contents of the parent's
	// "References:" field (if any) followed by the contents of the parent's
	// "Message-ID:" field (if any).  If the parent message does not contain
	// a "References:" field but does have an "In-Reply-To:" field
	// containing a single message identifier, then the "References:" field
	// will contain the contents of the parent's "In-Reply-To:" field
	// followed by the contents of the parent's "Message-ID:" field (if
	// any).  If the parent has none of the "References:", "In-Reply-To:",
	// or "Message-ID:" fields, then the new message will have no
	// "References:" field.
	//
	//    Note: Some implementations parse the "References:" field to
	//    display the "thread of the discussion".  These implementations
	//    assume that each new message is a reply to a single parent and
	//    hence that they can walk backwards through the "References:" field
	//    to find the parent of each message listed there.  Therefore,
	//    trying to form a "References:" field for a reply that has multiple
	//    parents is discouraged; how to do so is not defined in this
	//    document.
	//
	// The message identifier (msg-id) itself MUST be a globally unique
	// identifier for a message.  The generator of the message identifier
	// MUST guarantee that the msg-id is unique.  There are several
	// algorithms that can be used to accomplish this.  Since the msg-id has
	// a similar syntax to addr-spec (identical except that quoted strings,
	// comments, and folding white space are not allowed), a good method is
	// to put the domain name (or a domain literal IP address) of the host
	// on which the message identifier was created on the right-hand side of
	// the "@" (since domain names and IP addresses are normally unique),
	// and put a combination of the current absolute date and time along
	// with some other currently unique (perhaps sequential) identifier
	// available on the system (for example, a process id number) on the
	// left-hand side.  Though other algorithms will work, it is RECOMMENDED
	// that the right-hand side contain some domain identifier (either of
	// the host itself or otherwise) such that the generator of the message
	// identifier can guarantee the uniqueness of the left-hand side within
	// the scope of that domain.
	//
	// Semantically, the angle bracket characters are not part of the
	// msg-id; the msg-id is what is contained between the two angle bracket
	// characters.
	MessageID  MessageId
	InReplyTo  []MessageId
	References []MessageId

	// RFC 3522 3.6.5.  Informational Fields
	//
	// The informational fields are all optional.  The "Subject:" and
	// "Comments:" fields are unstructured fields as defined in section
	// 2.2.1, and therefore may contain text or folding white space.  The
	// "Keywords:" field contains a comma-separated list of one or more
	// words or quoted-strings.
	//
	// subject         =   "Subject:" unstructured CRLF
	//
	// comments        =   "Comments:" unstructured CRLF
	//
	// keywords        =   "Keywords:" phrase *("," phrase) CRLF
	//
	// These three fields are intended to have only human-readable content
	// with information about the message.  The "Subject:" field is the most
	// common and contains a short string identifying the topic of the
	// message.  When used in a reply, the field body MAY start with the
	// string "Re: " (an abbreviation of the Latin "in re", meaning "in the
	// matter of") followed by the contents of the "Subject:" field body of
	// the original message.  If this is done, only one instance of the
	// literal string "Re: " ought to be used since use of other strings or
	// more than one instance can lead to undesirable consequences.  The
	// "Comments:" field contains any additional comments on the text of the
	// body of the message.  The "Keywords:" field contains a comma-
	// separated list of important words and phrases that might be useful
	// for the recipient.
	Subject  string
	Comments string
	Keywords []string

	// RFC 3522 3.6.6.  Resent Fields
	//
	// Resent fields SHOULD be added to any message that is reintroduced by
	// a user into the transport system.  A separate set of resent fields
	// SHOULD be added each time this is done.  All of the resent fields
	// corresponding to a particular resending of the message SHOULD be
	// grouped together.  Each new set of resent fields is prepended to the
	// message; that is, the most recent set of resent fields appears
	// earlier in the message.  No other fields in the message are changed
	// when resent fields are added.
	//
	// Each of the resent fields corresponds to a particular field elsewhere
	// in the syntax.  For instance, the "Resent-Date:" field corresponds to
	// the "Date:" field and the "Resent-To:" field corresponds to the "To:"
	// field.  In each case, the syntax for the field body is identical to
	// the syntax given previously for the corresponding field.
	//
	// When resent fields are used, the "Resent-From:" and "Resent-Date:"
	// fields MUST be sent.  The "Resent-Message-ID:" field SHOULD be sent.
	// "Resent-Sender:" SHOULD NOT be used if "Resent-Sender:" would be
	// identical to "Resent-From:".
	//
	// resent-date     =   "Resent-Date:" date-time CRLF
	//
	// resent-from     =   "Resent-From:" mailbox-list CRLF
	//
	// resent-sender   =   "Resent-Sender:" mailbox CRLF
	//
	// resent-to       =   "Resent-To:" address-list CRLF
	//
	// resent-cc       =   "Resent-Cc:" address-list CRLF
	//
	// resent-bcc      =   "Resent-Bcc:" [address-list / CFWS] CRLF
	//
	// resent-msg-id   =   "Resent-Message-ID:" msg-id CRLF
	//
	// Resent fields are used to identify a message as having been
	// reintroduced into the transport system by a user.  The purpose of
	// using resent fields is to have the message appear to the final
	// recipient as if it were sent directly by the original sender, with
	// all of the original fields remaining the same.  Each set of resent
	// fields correspond to a particular resending event.  That is, if a
	// message is resent multiple times, each set of resent fields gives
	// identifying information for each individual time.  Resent fields are
	// strictly informational.  They MUST NOT be used in the normal
	// processing of replies or other such automatic actions on messages.
	//
	//    Note: Reintroducing a message into the transport system and using
	//    resent fields is a different operation from "forwarding".
	//    "Forwarding" has two meanings: One sense of forwarding is that a
	//    mail reading program can be told by a user to forward a copy of a
	//    message to another person, making the forwarded message the body
	//    of the new message.  A forwarded message in this sense does not
	//    appear to have come from the original sender, but is an entirely
	//    new message from the forwarder of the message.  Forwarding may
	//    also mean that a mail transport program gets a message and
	//    forwards it on to a different destination for final delivery.
	//    Resent header fields are not intended for use with either type of
	//    forwarding.
	//
	// The resent originator fields indicate the mailbox of the person(s) or
	// system(s) that resent the message.  As with the regular originator
	// fields, there are two forms: a simple "Resent-From:" form, which
	// contains the mailbox of the individual doing the resending, and the
	// more complex form, when one individual (identified in the "Resent-
	// Sender:" field) resends a message on behalf of one or more others
	// (identified in the "Resent-From:" field).
	//
	//    Note: When replying to a resent message, replies behave just as
	//    they would with any other message, using the original "From:",
	//    "Reply-To:", "Message-ID:", and other fields.  The resent fields
	//    are only informational and MUST NOT be used in the normal
	//    processing of replies.
	//
	// The "Resent-Date:" indicates the date and time at which the resent
	// message is dispatched by the resender of the message.  Like the
	// "Date:" field, it is not the date and time that the message was
	// actually transported.
	//
	// The "Resent-To:", "Resent-Cc:", and "Resent-Bcc:" fields function
	// identically to the "To:", "Cc:", and "Bcc:" fields, respectively,
	// except that they indicate the recipients of the resent message, not
	// the recipients of the original message.
	//
	// The "Resent-Message-ID:" field provides a unique identifier for the
	// resent message.
	ResentDate      time.Time
	ResentFrom      []*mail.Address
	ResentSender    *mail.Address
	ResentTo        []*mail.Address
	ResentCc        []*mail.Address
	ResentBcc       []*mail.Address
	ResentMessageID MessageId

	// RFC 2045 5.  Content-Type Header Field
	//
	// The purpose of the Content-Type field is to describe the data
	// contained in the body fully enough that the receiving user agent can
	// pick an appropriate agent or mechanism to present the data to the
	// user, or otherwise deal with the data in an appropriate manner. The
	// value in this field is called a media type.
	//
	// HISTORICAL NOTE:  The Content-Type header field was first defined in
	// RFC 1049.  RFC 1049 used a simpler and less powerful syntax, but one
	// that is largely compatible with the mechanism given here.
	//
	// The Content-Type header field specifies the nature of the data in the
	// body of an entity by giving media type and subtype identifiers, and
	// by providing auxiliary information that may be required for certain
	// media types.  After the media type and subtype names, the remainder
	// of the header field is simply a set of parameters, specified in an
	// attribute=value notation.  The ordering of parameters is not
	// significant.
	//
	// In general, the top-level media type is used to declare the general
	// type of data, while the subtype specifies a specific format for that
	// type of data.  Thus, a media type of "image/xyz" is enough to tell a
	// user agent that the data is an image, even if the user agent has no
	// knowledge of the specific image format "xyz".  Such information can
	// be used, for example, to decide whether or not to show a user the raw
	// data from an unrecognized subtype -- such an action might be
	// reasonable for unrecognized subtypes of text, but not for
	// unrecognized subtypes of image or audio.  For this reason, registered
	// subtypes of text, image, audio, and video should not contain embedded
	// information that is really of a different type.  Such compound
	// formats should be represented using the "multipart" or "application"
	// types.
	//
	// Parameters are modifiers of the media subtype, and as such do not
	// fundamentally affect the nature of the content.  The set of
	// meaningful parameters depends on the media type and subtype.  Most
	// parameters are associated with a single specific subtype.  However, a
	// given top-level media type may define parameters which are applicable
	// to any subtype of that type.  Parameters may be required by their
	// defining content type or subtype or they may be optional. MIME
	// implementations must ignore any parameters whose names they do not
	// recognize.
	//
	// For example, the "charset" parameter is applicable to any subtype of
	// "text", while the "boundary" parameter is required for any subtype of
	// the "multipart" media type.
	//
	// There are NO globally-meaningful parameters that apply to all media
	// types.  Truly global mechanisms are best addressed, in the MIME
	// model, by the definition of additional Content-* header fields.
	//
	// An initial set of seven top-level media types is defined in RFC 2046.
	// Five of these are discrete types whose content is essentially opaque
	// as far as MIME processing is concerned.  The remaining two are
	// composite types whose contents require additional handling by MIME
	// processors.
	//
	// This set of top-level media types is intended to be substantially
	// complete.  It is expected that additions to the larger set of
	// supported types can generally be accomplished by the creation of new
	// subtypes of these initial types.  In the future, more top-level types
	// may be defined only by a standards-track extension to this standard.
	// If another top-level type is to be used for any reason, it must be
	// given a name starting with "X-" to indicate its non-standard status
	// and to avoid a potential conflict with a future official name.
	ContentType        ContentTypeHeader
	ContentDisposition ContentDispositionHeader
	ExtraHeaders       map[string][]string
}

func ParseEmailHeaders added in v0.2.5 

func ParseEmailHeaders(header mail.Header) (Headers, error)

func ParseHeaders added in v0.2.3 

func ParseHeaders(header mail.Header) (Headers, error)

type HeadersParsers added in v0.2.5 

type HeadersParsers struct {
	Date               parseDateHeaderFn
	Sender             parseAddressHeaderFn
	From               parseAddressListHeaderFn
	ReplyTo            parseAddressListHeaderFn
	To                 parseAddressListHeaderFn
	Cc                 parseAddressListHeaderFn
	Bcc                parseAddressListHeaderFn
	MessageID          parseMessageIdHeaderFn
	InReplyTo          parseCommaSeparatedMessageIdHeaderFn
	References         parseCommaSeparatedMessageIdHeaderFn
	Subject            parseStringHeaderFn
	Comments           parseStringHeaderFn
	Keywords           parseCommaSeparatedStringHeaderFn
	ResentDate         parseDateHeaderFn
	ResentFrom         parseAddressListHeaderFn
	ResentSender       parseAddressHeaderFn
	ResentTo           parseAddressListHeaderFn
	ResentCc           parseAddressListHeaderFn
	ResentBcc          parseAddressListHeaderFn
	ResentMessageID    parseMessageIdHeaderFn
	ContentType        parseContentTypeHeaderFn
	ContentDisposition parseContentDispositionHeaderFn
	ExtraHeaders       map[string]parseStringHeaderFn
}

func DefaultHeadersParsers added in v0.2.5 

func DefaultHeadersParsers() HeadersParsers

type InlineFile 

type InlineFile struct {
	ContentID          string
	ContentType        ContentTypeHeader
	ContentDisposition ContentDispositionHeader
	Data               []byte
}

type MessageId 

type MessageId string

func ParseCommaSeparatedMessageIdHeader added in v0.2.5 

func ParseCommaSeparatedMessageIdHeader(s string) []MessageId

func ParseMessageIdHeader added in v0.2.5 

func ParseMessageIdHeader(s string) MessageId

type UnknownContentTypeError 

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

func (*UnknownContentTypeError) Error 

func (e *UnknownContentTypeError) Error() string

Source Files

View all Source files

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.