README
¶
The mailaddress package parses email addresses.
It's an alternative to net/mail; significant differences include:
- Better errors.
- When parsing a list it will continue to the next address on an error; this is especially useful when providing feedback to users.
- Some useful utility functions.
Basic example:
addr, err := mailaddress.Parse(`Martin <single_address@example.com>`)
addrs, haveErr := mailaddress.ParseLint(`many@example.com, addresses@example.com`)
if haveErr {
fmt.Println(addrs.Errors())
}
See godoc for more docs.
Documentation
¶
Overview ¶
Package mailaddress deals with email addresses.
It's an alternative to net/mail; significant differences include:
- Better errors.
- When parsing a list it will continue to the next address on an error; this is especially useful when providing feedback to users.
- Some useful utility functions.
The Address and List types are compatible with the net/mail types.
Index ¶
- Constants
- Variables
- type Address
- func (a Address) AddressEncoded() string
- func (a Address) Domain() string
- func (a *Address) Error() error
- func (a Address) Local() string
- func (a Address) NameEncoded() string
- func (a Address) String() string
- func (a Address) StringEncoded() string
- func (a Address) ToList() (l List)
- func (a *Address) Valid() bool
- func (a Address) WithoutTag() string
- type List
- func (l *List) Append(name, address string)
- func (l List) ContainsAddress(address string) bool
- func (l List) ContainsDomain(domain string) bool
- func (l List) Errors() (errs error)
- func (l List) Slice() []string
- func (l List) Sort(key int8)
- func (l List) String() string
- func (l List) StringEncoded() string
- func (l *List) UnmarshalJSON(data []byte) error
- func (l List) ValidAddresses() (valid List)
Constants ¶
const ( ByAddress = iota ByName )
Sort keys
Variables ¶
var ( // ErrInvalidEncoding is used when we can't decode an address because the // encoding is invalid (>95% of the time this means it's spam). ErrInvalidEncoding = errors.New("invalid or incomplete multibyte or wide character") // ErrNoEmail is used when we can't find an email address at all. ErrNoEmail = errors.New("unable to find an email address") // ErrTooManyEmails is used when too many email addresses were found. ErrTooManyEmails = errors.New("only one address expected") // ErrInvalidCharacter is used when unexpected data is encountered. ErrInvalidCharacter = errors.New("invalid character") )
Functions ¶
This section is empty.
Types ¶
type Address ¶
type Address struct {
Name string `db:"name" json:"name"`
Address string `db:"email" json:"address"`
Raw string `db:"-" json:"-"`
// contains filtered or unexported fields
}
Address is a single mail address.
func Parse ¶
Parse will parse exactly one address. More than one addresses is an error, otherwise it behaves as ParseList().
func (Address) AddressEncoded ¶
AddressEncoded returns the address ready to be put in an email header. Special characters will be appropriately escaped and RFC 2047 encoding will be applied.
func (Address) Domain ¶
Domain gets the domain part of an address (i.e. everything after the first @).
TODO: Same as Local().
func (Address) Local ¶
Local gets the local part of an address (i.e. everything before the first @).
TODO: the local part can contain a quoted/escaped @, but practically no email system deals with that, so it's not a huge deal at the moment.
func (Address) NameEncoded ¶
NameEncoded returns the name ready to be put in an email header. Special characters will be appropriately escaped and RFC 2047 encoding will be applied.
func (Address) StringEncoded ¶
StringEncoded makes a string that *is* RFC 2047 encoded
TODO: This won't work with IDN. This is okay since most email clients don't work with IDN. Last I checked this included Gmail, FastMail, Thunderbird, etc. The only client that works 100% correct AFAIK is mutt.
func (*Address) Valid ¶
Valid reports if this email looks valid. This includes some small extra checks for sanity. For example "martin@arp242 is a "valid" email address in the RFC sense, but not in the "something we can send emails to"-sense.
TODO: Perhaps consider renaming to CanSend() or Sendable() or Deliverable()?
It is also useful if the address wasn't created with ParseList() but directly (e.g. addr := Address{...}).
func (Address) WithoutTag ¶
WithoutTag gets the address with the tag part removed (if any). The tag part is everything in the local part after the first +.
type List ¶
type List []Address
List of zero or more addresses.
func (*List) Append ¶
Append adds a new Address to the list. If the address already exists in the list this will be a noop.
func (List) ContainsAddress ¶
ContainsAddress reports if the list contains the specified email address.
func (List) ContainsDomain ¶
ContainsDomain reports if the list contains one or more addresses with the given domain.
func (List) Errors ¶
Errors gets a list of all errors. The returned error is a multierror (github.com/hashicorp/go-multierror).
func (List) Slice ¶
Slice gets all valid addresses in a []string slice. The names are lost and invalid addresses are skipped. Duplicates are ignored.
func (List) StringEncoded ¶
StringEncoded makes a string that *is* RFC 2047 encoded. Duplicates are ignored.
func (*List) UnmarshalJSON ¶
UnmarshalJSON allows accepting several different formats for a list of mail addresses, which are (in order):
1. Standard List struct JSON string output. 2. Slice of strings containing emails. 3. Comma-separated string of emails, as accepted by ParseList().
func (List) ValidAddresses ¶
ValidAddresses returns a copy of the list which only includes valid email addresses.
Source Files