mail

Documentation

Overview

Package mail provides a conveniency interface over net/smtp, to facilitate the most common tasks when sending emails.

Index

• Constants
• Variables
• func AdminEmail() string
• func DefaultFrom() string
• func DefaultServer() string
• func MustParseAddressList(s string) []string
• func ParseAddressList(s string) ([]string, error)
• func Send(msg *Message) error
• func Validate(address string, useNetwork bool) (email string, err error)
• type Attachment
  • func NewAttachment(filename string, r io.Reader) (*Attachment, error)
• type Headers
• type Message

Constants

const (
	// Emails sent to the Admin pseudo-address will be sent to the
	// administrator (on non-GAE, this means sending it to AdminEmail()).
	Admin = "admin"
)

Variables

var Config struct {
	MailServer  string `default:"localhost:25" help:"Default mail server used by gnd.la/net/mail"`
	DefaultFrom string `help:"Default From address when sending emails"`
	AdminEmail  string `help:"When running in non-debug mode, any error messages will be emailed to this adddress"`
}

Config specifies the mail configuration. It's not recommended to change this fields manually. Instead, use their respective config keys or flags. See DefaultServer, DefaultFrom and AdminEmail.

Functions

func AdminEmail

func AdminEmail() string

AdminEmail returns the administrator email. When email logging is enabled, errors will be sent to this address. Use the configuration file key admin_email or the command line flag -admin-email to change it.

func DefaultFrom

func DefaultFrom() string

DefaultFrom returns the default From address used in outgoing emails. Use the configuration file key default_from or the command line flag -default-from to change it.

func DefaultServer

func DefaultServer() string

DefaultServer returns the default mail server address. Use the configuration file key mail_server or the command line flag -mail-server to change it. The format for the mail server is [user:password]@host[:port]. If you want to use CRAM authentication, prefix the username with "cram?" - witout quotes, otherwise PLAIN authentication is used. Additionally, the special value "echo" can be used for testing, and will cause the email to be printed to the standard output, rather than sent. The following are valid examples of server addresses.

• localhost
• localhost:25
• user@gmail.com:patata@smtp.gmail.com
• cram?pepe:12345@example.com
• echo

The default server value is localhost:25.

func MustParseAddressList

func MustParseAddressList(s string) []string

MustParseAddressList works like ParseAddressList, but panics if there's an error.

func ParseAddressList

func ParseAddressList(s string) ([]string, error)

ParseAddressList splits a comma separated list of addresses into multiple email addresses. The returned addresses can be used to call Send().

func Send

func Send(msg *Message) error

Send sends an email to the given addresses and using the given Message. Note that if Message is nil, an error is returned. See the Options documentation for further information. This function does not work on App Engine. Use gnd.la/app.Context.SendMail.

func Validate

func Validate(address string, useNetwork bool) (email string, err error)

Validate performs some basic email address validation on a given address, just ensuring it's indeed a valid address according to RFC 5322. If useNetwork is true, the domain will be also validated. Even if this function returns no error, IT DOESN'T MEAN THE ADDRESS EXISTS. The only way to be completely sure the address exist and can receive email is sending an email with a link back to your site including a randomly generated token that the user has to click to verify the he can read email sent to that address. The returned string is the address part of the given string (e.g. "Alberto G. Hierro <alberto@garciahierro.com>" would return "alberto@garciahierro").

Note for GAE: Due to the GAE runtime restrictions, there's no way to perform DNS lookus, so the useNetwork parameter is ignored when running on GAE.

Types

type Attachment

type Attachment struct {
	Name        string
	ContentType string
	Data        []byte
	// ContentID is used to reference attachments from
	// the message HTML body. Note that attachments with
	// a non-empty ContentID which is referenced from the
	// HTML will not be included as downloadable attachments.
	// However, if their ContentID is not found in the HTML
	// they will be treated as normal attachments.
	ContentID string
}

Attachment represents an email attachment. See the conveniency function NewAttachment.

func NewAttachment

func NewAttachment(filename string, r io.Reader) (*Attachment, error)

NewAttachment returns a new attachment which can be included in the Message passed to Send(). The ContentType is derived from the file name.

type Headers

type Headers map[string]string

Headers represent additional headers to be added to the email.

type Message

type Message struct {
	// Server to send the email. If empty, the value returned from
	// DefaultServer() is used. See DefaultServer() documentation
	// for the format of this field.
	Server string
	// From address. If empty, defaults to the value from DefaultFrom().
	// Note that this (or DefaultFrom()) always overwrites any From header
	// set using the Headers field.
	From string
	// ReplyTo address.
	ReplyTo string
	// Destinataries fields. These might be either a string or a []string. In the
	// former case, the value is parsed using ParseAddressList.
	// At least of them must be non-empty.
	To, Cc, Bcc interface{}
	// Subject of the email. If non-empty, overwrites any Subject header
	// set using the Headers field.
	Subject string
	// TextBody is the message body to be sent as text/plain. Either this
	// or HTMLBody must be non-empty
	TextBody string
	// HTMLBody is the message body to be sent as text/html. Either this
	// or TextBody must be non-empty
	HTMLBody string
	// Additional email Headers. Might be nil.
	Headers Headers
	// Attachments to add to the email. See Attachment and NewAttachment.
	Attachments []*Attachment
	// Context is used interally by Gondola and should not be altered by users.
	Context interface{}
}

Message describes an email to be sent. The fields that are mapped to headers (e.g From, Subject, To, etc...) overwrite any headers set in the Headers field when they're non-empty.