email

package
v0.0.0-...-9f91bea Latest Latest
Warning

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

 Go to latest Published: Mar 9, 2026 License: MIT Imports: 32 Imported by: 4

Documentation

Overview

Package email provides comprehensive email address handling, parsing, validation, and message processing utilities for Go applications.

The package includes: - Email address parsing with lenient validation - Address normalization and validation - Email message parsing (MIME, TNEF) - Address lists and sets management - Database integration (Scanner/Valuer interfaces) - JSON schema generation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// AddressRegexp is a compiled regular expression for an email address without name part
	AddressRegexp = regexp.MustCompile(addressRegex)
)

Functions

func ExtractBodyURLs 

func ExtractBodyURLs(msg *Message) strutil.StringSet

ExtractBodyURLs returns all HTTP URLs from the message body

func HTMLToPlaintext 

func HTMLToPlaintext(html []byte, delimiter string) (string, error)

HTMLToPlaintext converts HTML to plaintext by concaternating the content of text nodes with the passed delimiter between them. Whitespace is trimmed from the text nodes and nodes consisting only of whitespace are ignored. In case of an HTML parsing error all parsed text up until the error will be returned. Empty html will result in empty plaintext.

func IsExtraHeader 

func IsExtraHeader(key string) bool

func IsParsedHeader 

func IsParsedHeader(key string) bool

func NormalizeAddressList 

func NormalizeAddressList(list string) (normalized []string, err error)

NormalizeAddressList parses a comma-separated email address list using lenient validation that fixes common malformations and normalizes address parts to lowercase. Duplicate addresses (based on normalized address parts) are automatically removed. Returns an error if the list does not contain at least one valid address.

func ParseAddress 

func ParseAddress(addr string) (mailAddress *mail.Address, err error)

ParseAddress parses an email address less strict than the standard net/mail.ParseAddress function fixing malformed addresses and lower cases the address part. If the name part is identical with the address part then it will not be returned as name.

func ParseAddressList 

func ParseAddressList(list string) (addrs []*mail.Address, err error)

ParseAddressList parses an email address list less strict than the standard net/mail.ParseAddressList function fixing malformed addresses and lower cases the address part. ParseAddressList returns an error if list does not contain at least one address.

func ProviderDomains 

func ProviderDomains() map[string]struct{}

ProviderDomains returns a set of known email provider domain names.

Types

type Address 

type Address string

Address represents a non-normalized email address string that may contain an optional display name part before the mandatory email address part. Examples: "[email protected]", "John Doe <[email protected]>"

func AddressFrom 

func AddressFrom(addr *mail.Address) Address

AddressFrom creates an Address from a parsed mail.Address. If the address has no name part, returns just the address. If the address has a name part, returns the full formatted string.

func FindAllAddresses 

func FindAllAddresses(text string) []Address

FindAllAddresses uses the AddressRegexp to find all email addresses without name part in the passed text. The addresses are not normalized and returned in the order they were found in the text.

func NormalizedAddress 

func NormalizedAddress(addr string) (normalized Address, err error)

NormalizedAddress parses an email address using lenient validation that fixes common malformations and normalizes the address part to lowercase. This is more permissive than the standard net/mail.ParseAddress function.

func UniqueNormalizedAddressSlice 

func UniqueNormalizedAddressSlice(addrs []Address) []Address

UniqueNormalizedAddressSlice returns the passed Address slice modified to only contain the sorted unique normalized address parts (address without name part) of the passed addresses.

func (Address) AddressPart 

func (a Address) AddressPart() (Address, error)

AddressPart returns the normalized lowercase address part (the part after the @ symbol) as an Address type. This strips any display name and returns just the email address.

func (Address) AddressPartString 

func (a Address) AddressPartString() (string, error)

AddressPartString returns the normalized lowercase address part (the part after the @ symbol) from an email address. This strips any display name and returns just the email address.

func (Address) AsList 

func (a Address) AsList() AddressList

AsList converts the Address to an AddressList containing this single address.

func (Address) DomainPart 

func (a Address) DomainPart() string

DomainPart returns the domain part of the email address (after the @ symbol). This is a simple string extraction that doesn't require parsing. Returns an empty string if no @ symbol is found.

func (Address) JSONSchema 

func (Address) JSONSchema() *jsonschema.Schema

JSONSchema returns the JSON schema definition for the Address type. This is used for API documentation and validation.

func (Address) LocalPart 

func (a Address) LocalPart() (string, error)

LocalPart returns the part of the email address before the @ symbol. This is the local part of the email address (e.g., "user" from "[email protected]").

func (Address) NamePart 

func (a Address) NamePart() (string, error)

NamePart extracts the display name part from the email address. Returns an empty string if no name part is present.

func (Address) Normalized 

func (a Address) Normalized() (Address, error)

Normalized parses the email address using lenient validation that fixes common malformations and normalizes the address part to lowercase. This is more permissive than the standard net/mail.ParseAddress function.

func (Address) Nullable 

func (a Address) Nullable() NullableAddress

Nullable converts the Address to a NullableAddress type.

func (Address) Parse 

func (a Address) Parse() (*mail.Address, error)

Parse converts the Address to a *mail.Address using lenient validation that fixes common malformations and normalizes the address part to lowercase. This is more permissive than the standard net/mail.ParseAddress function.

func (Address) Valid 

func (a Address) Valid() bool

Valid returns true if the Address is a valid email address format.

func (Address) ValidAndNormalized 

func (a Address) ValidAndNormalized() bool

ValidAndNormalized returns true if the Address is valid and already normalized.

func (Address) Validate 

func (a Address) Validate() error

Validate checks if the Address is a valid email address format. Returns an error if the address cannot be parsed.

type AddressList 

type AddressList string

AddressList represents a comma-separated list of email addresses. The list must contain at least one valid email address. Use NullableAddressList for lists that can be empty.

func AddressListJoin 

func AddressListJoin(addrs ...Address) AddressList

AddressListJoin creates an AddressList by joining multiple Address values with comma separators. Empty addresses are skipped.

func AddressListJoinStrings 

func AddressListJoinStrings(addrs ...string) AddressList

AddressListJoinStrings creates an AddressList by joining multiple string values with comma separators. Empty strings are skipped.

func (AddressList) Append 

func (l AddressList) Append(addrs ...Address) AddressList

Append adds additional addresses to the AddressList. Empty addresses are skipped.

func (AddressList) Normalized 

func (l AddressList) Normalized() (AddressList, error)

func (AddressList) Nullable 

func (l AddressList) Nullable() NullableAddressList

func (AddressList) Parse 

func (l AddressList) Parse() ([]*mail.Address, error)

Parse converts the AddressList to a slice of *mail.Address using lenient validation.

func (*AddressList) Scan 

func (l *AddressList) Scan(value any) error

Scan implements the database/sql.Scanner interface. Supports scanning SQL strings and string arrays.

func (AddressList) Split 

func (l AddressList) Split() ([]Address, error)

Split converts the AddressList to a slice of Address values. Returns nil if the list is empty or invalid.

func (AddressList) UniqueAddressParts 

func (l AddressList) UniqueAddressParts() (AddressSet, error)

UniqueAddressParts returns an AddressSet containing the unique normalized address parts from the AddressList. This removes duplicates based on the actual email addresses (ignoring display names).

func (AddressList) Valid 

func (l AddressList) Valid() bool

Valid returns true if the AddressList is a valid list of email addresses.

func (AddressList) ValidAndNormalized 

func (l AddressList) ValidAndNormalized() bool

ValidAndNormalized returns true if the AddressList is valid and already normalized.

func (AddressList) Validate 

func (l AddressList) Validate() error

type AddressSet 

type AddressSet map[Address]struct{}

AddressSet is a set of unique email addresses

func MakeAddressSet 

func MakeAddressSet(addrs ...Address) AddressSet

func NormalizedAddressPartSet 

func NormalizedAddressPartSet(addrs ...Address) (AddressSet, error)

func NormalizedAddressSet 

func NormalizedAddressSet(addrs ...Address) (AddressSet, error)

func (*AddressSet) Add 

func (set *AddressSet) Add(addr Address)

func (*AddressSet) AddAddressPart 

func (set *AddressSet) AddAddressPart(addr Address) error

func (*AddressSet) AddNormalized 

func (set *AddressSet) AddNormalized(addr Address) error

func (*AddressSet) AddSet 

func (set *AddressSet) AddSet(other AddressSet)

func (AddressSet) AddressList 

func (set AddressSet) AddressList() AddressList

func (AddressSet) Clear 

func (set AddressSet) Clear()

func (AddressSet) Clone 

func (set AddressSet) Clone() AddressSet

func (AddressSet) Contains 

func (set AddressSet) Contains(addr Address) bool

func (AddressSet) Delete 

func (set AddressSet) Delete(val Address)

func (AddressSet) DeleteSet 

func (set AddressSet) DeleteSet(other AddressSet)

func (AddressSet) DeleteSlice 

func (set AddressSet) DeleteSlice(vals []Address)

func (AddressSet) GetOne 

func (set AddressSet) GetOne() Address

GetOne returns one address of the set or an empty string if the set is empty.

func (AddressSet) IsEmpty 

func (set AddressSet) IsEmpty() bool

IsEmpty returns true if the set is empty or nil.

func (AddressSet) IsNull 

func (set AddressSet) IsNull() bool

IsNull implements the nullable.Nullable interface by returning true if the set is nil.

func (AddressSet) Len 

func (set AddressSet) Len() int

Len returns the number of values in the set.

func (AddressSet) Normalized 

func (set AddressSet) Normalized() (AddressSet, error)

func (*AddressSet) Scan 

func (set *AddressSet) Scan(value any) error

Scan implements the database/sql.Scanner interface. Supports scanning SQL strings and string arrays.

func (AddressSet) Sorted 

func (set AddressSet) Sorted() []Address

func (AddressSet) String 

func (set AddressSet) String() string

func (AddressSet) Strings 

func (set AddressSet) Strings() []string

func (AddressSet) Valid 

func (set AddressSet) Valid() bool

Valid returns true if all addresses in the set are valid.

func (AddressSet) ValidAndNormalized 

func (set AddressSet) ValidAndNormalized() bool

ValidAndNormalized returns true if all addresses in the set are valid and already normalized.

func (AddressSet) Validate 

func (set AddressSet) Validate() error

Validate returns the first error encountered validating the addresses of the set.

func (AddressSet) Value 

func (set AddressSet) Value() (driver.Value, error)

Value implements the driver database/sql/driver.Valuer interface.

type AllRule 

type AllRule []Rule

func (AllRule) AppliesToMessage 

func (r AllRule) AppliesToMessage(msg *Message) bool

type AnyRule 

type AnyRule []Rule

func (AnyRule) AppliesToMessage 

func (r AnyRule) AppliesToMessage(msg *Message) bool

type Attachment 

type Attachment struct {
	PartID      string `json:",omitempty"`
	ContentID   string `json:",omitempty"`
	ContentType string `json:",omitempty"`
	Inline      bool   `json:",omitempty"`
	OtherPart   bool   `json:",omitempty"`
	Filename    string
	Content     []byte
}

Attachment of an Email. Attachment implements fs.FileReader

func NewAttachment 

func NewAttachment(partID, filename string, content []byte) *Attachment

func (*Attachment) String 

func (a *Attachment) String() string

type BoolRule 

type BoolRule bool

func (BoolRule) AppliesToMessage 

func (r BoolRule) AppliesToMessage(*Message) bool
type Header = textproto.MIMEHeader

type Message 

type Message struct {
	// ProviderID is the optional ID of the message
	// at the email provider like GMail that might be
	// different from the RFC 822 Message-ID.
	ProviderID nullable.TrimmedString `json:"providerID,omitempty"`

	// InReplyToProviderID is the ProviderID of the message
	// that this message is a reply to.
	InReplyToProviderID nullable.TrimmedString `json:"inReplyToProviderID,omitempty"`

	// ProviderLabels are optional labels from the email provider
	// like GMail that are not encoded in the message itself.
	ProviderLabels []string `json:"providerLabels,omitempty"`

	// MessageID is the "Message-ID" header according to RFC 822/2822/5322.
	// Find in Gmail via filter: rfc822msgid:MessageID
	MessageID nullable.TrimmedString `json:"messageID,omitempty"`

	// In-Reply-To header
	InReplyTo nullable.TrimmedString `json:"inReplyTo,omitempty"`

	// References header
	References nullable.TrimmedString `json:"references,omitempty"`

	// Date header
	Date *time.Time `json:"date,omitempty"`

	From        Address             `json:"from,omitempty"`
	ReplyTo     NullableAddress     `json:"replyTo,omitempty"`
	To          AddressList         `json:"to,omitempty"`
	DeliveredTo NullableAddressList `json:"deliveredTo,omitempty"`
	Cc          NullableAddressList `json:"cc,omitempty"`
	Bcc         NullableAddressList `json:"bcc,omitempty"`

	// ExtraHeader can be used for additional header data
	// not covered by the other fields of the struct.
	ExtraHeader Header `json:"extraHeader,omitempty"`

	Subject string `json:"subject,omitempty"`

	// Body is the plaintext body of the email.
	Body string `json:"body,omitempty"`

	// BodyHTML returns the HTML body if available.
	BodyHTML nullable.TrimmedString `json:"bodyHTML,omitempty"`

	Attachments []*Attachment `json:"attachments,omitempty"`
}

func NewMessage 

func NewMessage(from Address, to AddressList, subject, body string, bodyHTML nullable.TrimmedString) *Message

NewMessage returns a new message using the passed from, to, subject, body, and bodyHTML arguments.

func ParseMIMEMessage 

func ParseMIMEMessage(reader io.Reader) (msg *Message, err error)

func ParseMIMEMessageBytes 

func ParseMIMEMessageBytes(msgBytes []byte) (msg *Message, err error)

func ParseMessage 

func ParseMessage(data []byte) (msg *Message, err error)

func ParseTNEFMessageBytes 

func ParseTNEFMessageBytes(messageBytes []byte) (msg *Message, err error)

func (*Message) AddAttachment 

func (msg *Message) AddAttachment(partID, filename string, content []byte)

func (*Message) AutoResponseSuppress 

func (msg *Message) AutoResponseSuppress() bool

Returns if the X-Auto-Response-Suppress header contains any of the values "DR", "AutoReply", or "All". See https://docs.microsoft.com/en-us/openspecs/exchange_server_protocols/ms-oxcmail/ced68690-498a-4567-9d14-5c01f974d8b1

func (*Message) BuildRawMessage 

func (msg *Message) BuildRawMessage() (raw []byte, err error)

func (*Message) FeedbackID 

func (msg *Message) FeedbackID() string

FeedbackID returns the value of the "Feedback-Id" header or an empty string if not available.

func (*Message) IsAutoSubmitted 

func (msg *Message) IsAutoSubmitted() bool

Returns if the "Auto-Submitted" header is set and has a different value than "no". See RFC 3834: https://datatracker.ietf.org/doc/html/rfc3834

func (*Message) ListID 

func (msg *Message) ListID() string

ListID returns the value of the "List-Id" header or an empty string if not available.

func (*Message) NewReplyMessage 

func (msg *Message) NewReplyMessage(from Address, replyText, replyHTML string, keepAttachments bool, textTempl, htmlTempl string) (re *Message, err error)

NewReplyMessage creates a reply based on an existing message. The textTempl and htmlTempl templates will called with a ReplyTemplateData struct instance as context and are responsible to render the passed replyText and replyHTML together with a quotation of the original message. The passed replyText and replyHTML are not interpreted as templates.

func (*Message) Recipients 

func (msg *Message) Recipients() []string

Recipients returns the valid, normalized, name stripped, deduplicated addresses from the To, Cc, and Bcc fields.

func (*Message) ReferencesMessageIDs 

func (msg *Message) ReferencesMessageIDs() []string

ReferencesMessageIDs returns the message IDs listed in the References header.

func (*Message) ReplyToAddress 

func (msg *Message) ReplyToAddress() Address

ReplyToAddress returns the ReplyTo address if available, else the From address.

func (*Message) String 

func (msg *Message) String() string

type NullableAddress 

type NullableAddress string

NullableAddress is a string containing a non-normalized email-address with an optional name part before the mandatory address part. An empty string represents the SQL/JSON null value. 

const AddressNull NullableAddress = ""

func NormalizedNullableAddress 

func NormalizedNullableAddress(addr string) (normalized NullableAddress, err error)

NormalizedNullableAddress parses an email address less strict than the standard net/mail.ParseAddress function fixing malformed addresses and lower cases the address part. An empty string is interpreted as valid NULL address.

func NullableAddressFrom 

func NullableAddressFrom(a *mail.Address) NullableAddress

func (NullableAddress) AddressPart 

func (n NullableAddress) AddressPart() (NullableAddress, error)

AddressPart returns the normalized lower case address part of an email address that may also contain a name part.

func (NullableAddress) AsList 

func (n NullableAddress) AsList() NullableAddressList

func (NullableAddress) DomainPart 

func (n NullableAddress) DomainPart() string

DomainPart returns the part of the address after the @ character or an empty string in case of a null address.

func (NullableAddress) Get 

func (n NullableAddress) Get() Address

Get returns the non nullable Address or panics if the NullableAddress is null. Note: check with IsNull before using Get!

func (NullableAddress) GetOr 

func (n NullableAddress) GetOr(defaultAddress Address) Address

GetOr returns the non nullable Address value or the passed defaultAddress if the NullableAddress is null.

func (NullableAddress) IsNotNull 

func (n NullableAddress) IsNotNull() bool

IsNotNull returns true if the string n is not empty.

func (NullableAddress) IsNull 

func (n NullableAddress) IsNull() bool

IsNull returns true if the string n is empty.

func (NullableAddress) JSONSchema 

func (NullableAddress) JSONSchema() *jsonschema.Schema

func (NullableAddress) LocalPart 

func (n NullableAddress) LocalPart() (string, error)

LocalPart returns the sub-part of the address part before the @ character or an empty string in case of a null address.

func (NullableAddress) MarshalJSON 

func (n NullableAddress) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface.

func (NullableAddress) NamePart 

func (n NullableAddress) NamePart() (string, error)

func (NullableAddress) Normalized 

func (n NullableAddress) Normalized() (NullableAddress, error)

Normalized parses an email address less strict than the standard net/mail.ParseAddress function fixing malformed addresses and lower cases the address part. An empty string is interpreted as valid NULL address.

func (NullableAddress) Parse 

func (n NullableAddress) Parse() (*mail.Address, error)

func (*NullableAddress) Scan 

func (n *NullableAddress) Scan(value any) error

Scan implements the database/sql.Scanner interface.

func (*NullableAddress) Set 

func (n *NullableAddress) Set(s Address)

Set the passed Address as NullableAddress. Passing an empty string will be interpreted as setting NULL.

func (*NullableAddress) SetNull 

func (n *NullableAddress) SetNull()

SetNull sets the string to its null value

func (NullableAddress) StringOr 

func (n NullableAddress) StringOr(nullString string) string

StringOr returns the string value of n or the passed nullString if n.IsNull()

func (*NullableAddress) UnmarshalJSON 

func (n *NullableAddress) UnmarshalJSON(data []byte) error

UnmarshalJSON implements the json.Unmarshaler interface returning the JSON null value for and empty/NULL address.

func (*NullableAddress) UnmarshalText 

func (n *NullableAddress) UnmarshalText(text []byte) error

UnmarshalText implements encoding.TextUnmarshaler

func (NullableAddress) ValidAndNormalized 

func (n NullableAddress) ValidAndNormalized() bool

ValidAndNormalized returns true if the NullableAddress is valid and already normalized.

func (NullableAddress) Validate 

func (n NullableAddress) Validate() error

func (NullableAddress) Value 

func (n NullableAddress) Value() (driver.Value, error)

Value implements the driver database/sql/driver.Valuer interface.

type NullableAddressList 

type NullableAddressList string

NullableAddressList is a comma separated list of email addresses. The empty string default value represents an empty list and maps to SQL NULL and JSON null.

func NullableAddressListJoin 

func NullableAddressListJoin(addrs ...Address) NullableAddressList

func NullableAddressListJoinStrings 

func NullableAddressListJoinStrings(addrs ...string) NullableAddressList

func (NullableAddressList) Append 

func (n NullableAddressList) Append(addrs ...Address) NullableAddressList

func (NullableAddressList) Get 

func (n NullableAddressList) Get() AddressList

Get returns the non nullable string value or panics if the NullableAddressList is null. Note: check with IsNull before using Get!

func (NullableAddressList) GetOr 

func (n NullableAddressList) GetOr(defaultValue AddressList) AddressList

func (NullableAddressList) IsNotNull 

func (n NullableAddressList) IsNotNull() bool

IsNotNull returns true if the string n is not empty.

func (NullableAddressList) IsNull 

func (n NullableAddressList) IsNull() bool

IsNull returns true if the string n is empty.

func (NullableAddressList) MarshalJSON 

func (n NullableAddressList) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface.

func (NullableAddressList) Normalized 

func (n NullableAddressList) Normalized() (NullableAddressList, error)

func (NullableAddressList) Parse 

func (n NullableAddressList) Parse() ([]*mail.Address, error)

func (*NullableAddressList) Scan 

func (n *NullableAddressList) Scan(value any) error

Scan implements the database/sql.Scanner interface. Supports scanning SQL strings and string arrays.

func (*NullableAddressList) Set 

func (n *NullableAddressList) Set(s AddressList)

func (*NullableAddressList) SetNull 

func (n *NullableAddressList) SetNull()

SetNull sets the string to its null value

func (NullableAddressList) Split 

func (n NullableAddressList) Split() ([]Address, error)

func (NullableAddressList) StringOr 

func (n NullableAddressList) StringOr(nullString string) string

StringOr returns the string value of n or the passed nullString if n.IsNull()

func (*NullableAddressList) UnmarshalJSON 

func (n *NullableAddressList) UnmarshalJSON(data []byte) error

UnmarshalJSON implements the json.Unmarshaler interface returning the JSON null value for and empty/NULL address list.

func (*NullableAddressList) UnmarshalText 

func (n *NullableAddressList) UnmarshalText(text []byte) error

UnmarshalText implements encoding.TextUnmarshaler

func (NullableAddressList) ValidAndNormalized 

func (n NullableAddressList) ValidAndNormalized() bool

ValidAndNormalized returns true if the NullableAddressList is valid and already normalized.

func (NullableAddressList) Validate 

func (n NullableAddressList) Validate() error

func (NullableAddressList) Value 

func (n NullableAddressList) Value() (driver.Value, error)

Value implements the driver database/sql/driver.Valuer interface.

type ReplyTemplateData 

type ReplyTemplateData struct {
	Message
	Date      string
	BodyLines []string
	BodyHTML  template.HTML
	ReplyText string
	ReplyHTML template.HTML
}

type Rule 

type Rule interface {
	AppliesToMessage(msg *Message) bool
}

type RuleFunc 

type RuleFunc func(*Message) bool

func (RuleFunc) AppliesToMessage 

func (f RuleFunc) AppliesToMessage(msg *Message) bool

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.