Documentation ¶
Overview ¶
Yet another SMTP client!
Simple Usage
oCfg := SMTPClientConfig{ Server: "mx.test.com", Port: 587, Username: "test@test.com", Password: "...", Mode: ModeSTARTTLS, // SMTPLog: "-", // note: uncomment to log SMTP session to STDOUT } oEmail := NewEmail() oEmail.From = "test@test.com" oEmail.To = []string{"test_receiver@eggplant.pro"} oEmail.Subject = "Test Message" oEmail.Text = []byte("Whoomp there it is!") E := oCfg.SimpleSend(oEmail) if E != nil { return E }
Advanced Usage
See implementation of SMTPClientConfig.SimpleSend()
Index ¶
- Constants
- Variables
- func TLSConfig(hostName string) *tls.Config
- type Attachment
- type Auth
- type Client
- func (c *Client) Auth(a Auth) error
- func (c *Client) Close() error
- func (c *Client) Data() (io.WriteCloser, error)
- func (c *Client) Extension(ext string) (bool, string)
- func (c *Client) Hello(localName string) error
- func (c *Client) IsTLS() bool
- func (c *Client) Mail(from string) error
- func (c *Client) Noop() error
- func (c *Client) Quit() error
- func (c *Client) Rcpt(to string) error
- func (c *Client) Reset() error
- func (c *Client) Send(e *Email) (E error)
- func (c *Client) StartTLS(config *tls.Config) error
- type CreateTextprotoConnFn
- type Email
- func (e *Email) Attach(r io.Reader, filename string, contentType string) (a *Attachment, E error)
- func (e *Email) AttachFile(filename string) (a *Attachment, E error)
- func (e *Email) Bytes() ([]byte, error)
- func (MSG *Email) ParseSender() (sender mail.Address, E error)
- func (e *Email) ParseToFromAddrs() ([]*mail.Address, error)
- type SMTPClientConfig
- type SMTPClientMode
- type ServerInfo
- type TextProtoConn
Constants ¶
const ( ANSI_RESET = "\u001b[0m" ANSI_COLOR_RQ_CMD = "\u001b[38;5;11m" // yellow ANSI_COLOR_RQ_BODY = "\u001b[38;5;14m" // cyan ANSI_COLOR_RSP_OK = "\u001b[38;5;10m" // green ANSI_COLOR_RSP_ERR = "\u001b[38;5;9m" // red MODE_SEND = "C>" MODE_RECV = "<S" )
const (
MaxLineLength = 76 // MaxLineLength is the maximum line length per RFC 2045
)
Variables ¶
var ( ErrMissingToOrFrom = errors.New("Must specify at least one From address and one To address") ErrMissingBoundary = errors.New("No boundary found for multipart entity") ErrMissingContentType = errors.New("No Content-Type found for MIME entity") ErrSTARTTLSNotOffered = errors.New("STARTTLS not offered by server") )
Functions ¶
Types ¶
type Attachment ¶
type Attachment struct { Filename string Header textproto.MIMEHeader Content []byte }
Attachment is a struct representing an email attachment. Based on the mime/multipart.FileHeader struct, Attachment contains the name, MIMEHeader, and content of the attachment in question.
type Auth ¶
type Auth interface { // Start begins an authentication with a server. // It returns the name of the authentication protocol // and optionally data to include in the initial AUTH message // sent to the server. It can return proto == "" to indicate // that the authentication should be skipped. // If it returns a non-nil error, the SMTP client aborts // the authentication attempt and closes the connection. Start(server *ServerInfo) (proto string, toServer []byte, err error) // Next continues the authentication. The server has just sent // the fromServer data. If more is true, the server expects a // response, which Next should return as toServer; otherwise // Next should return toServer == nil. // If Next returns a non-nil error, the SMTP client aborts // the authentication attempt and closes the connection. Next(fromServer []byte, more bool) (toServer []byte, err error) }
Auth is implemented by an SMTP authentication mechanism.
func CRAMMD5Auth ¶
CRAMMD5Auth returns an Auth that implements the CRAM-MD5 authentication mechanism as defined in RFC 2195. The returned Auth uses the given username and secret to authenticate to the server using the challenge-response mechanism.
func LoginAuth ¶
Returns an Auth interface implementing the LOGIN authentication mechanism as defined in RFC 4616.
NOTE: method used by Office 365 circa 2020.
NOTE: pieced together from:
func PlainAuth ¶
PlainAuth returns an Auth that implements the PLAIN authentication mechanism as defined in RFC 4616. The returned Auth uses the given username and password to authenticate to host and act as identity. Usually identity should be the empty string, to act as username.
PlainAuth will only send the credentials if the connection is using TLS or is connected to localhost. Otherwise authentication will fail with an error, without sending the credentials.
type Client ¶
type Client struct { // This is the TextProtoConn interface used by the Client. // It is exported to allow for clients to add extensions. Text TextProtoConn // contains filtered or unexported fields }
Implements the Simple Mail Transfer Protocol as defined in RFC 5321. It also implements the following extensions:
8BITMIME RFC 1652 AUTH RFC 2554 STARTTLS RFC 3207
Additional extensions may be handled by clients.
func NewClient ¶
func NewClient( iConn net.Conn, iAuth Auth, serverName string, pSTARTTLSCfg *tls.Config, fnNewTextproto CreateTextprotoConnFn, ) (c *Client, E error)
NewClient creates an SMTP Client from an existing connection and a server hostname, then attempts to establish an active SMTP session with it.
Attempts STARTTLS negotiation if `pSTARTTLSCfg` is provided, and the server provides the STARTTLS extension. Skips STARTTLS negotiation if nil.
`fnNewTextproto` creates a TextProtoConn interface from a net.Conn interface. This allows us to inject textproto.Conn wrappers that insert/remove/capture SMTP traffic before it hits the wire.
If fnNewTextproto is left nil, the underlying textproto will come from textproto.NewConn().
Close with .Quit() method to end session.
func (*Client) Auth ¶
Auth authenticates a client using the provided authentication mechanism. A failed authentication closes the connection. Only servers that advertise the AUTH extension support this function.
func (*Client) Data ¶
func (c *Client) Data() (io.WriteCloser, error)
Data issues a DATA command to the server and returns a writer that can be used to write the mail headers and body. The caller should close the writer before calling any more methods on c. A call to Data must be preceded by one or more calls to Rcpt.
func (*Client) Extension ¶
Extension reports whether an extension is support by the server. The extension name is case-insensitive. If the extension is supported, Extension also returns a string that contains any parameters the server specifies for the extension.
func (*Client) Hello ¶
Hello sends a HELO or EHLO to the server as the given host name. Calling this method is only necessary if the client needs control over the host name used. The client will introduce itself as "localhost" automatically otherwise. If Hello is called, it must be called before any of the other methods.
func (*Client) Mail ¶
Mail issues a MAIL command to the server using the provided email address. If the server supports the 8BITMIME extension, Mail adds the BODY=8BITMIME parameter. This initiates a mail transaction and is followed by one or more Rcpt calls.
func (*Client) Noop ¶
Noop sends the NOOP command to the server. It does nothing but check that the connection to the server is okay.
func (*Client) Rcpt ¶
Rcpt issues a RCPT command to the server using the provided email address. A call to Rcpt must be preceded by a call to Mail and may be followed by a Data call or another Rcpt call.
func (*Client) Reset ¶
Reset sends the RSET command to the server, aborting the current mail transaction.
type CreateTextprotoConnFn ¶
type CreateTextprotoConnFn func(net.Conn) TextProtoConn
func TextprotoLogged ¶
func TextprotoLogged(pLog *log.Logger, bColors bool) CreateTextprotoConnFn
Can be used as a substitute CreateTextprotoConnFn to log the SMTP conversation to a specified logger.
Example
// create target logger pLog := log.New(os.Stdout, "", log.Ltime | log.Lmicroseconds) // establilsh connection to server HOST := "smtp.office365.com" iConn, _ = net.Dial("tcp4", HOST + ":587",) // create new session email.NewClient( iConn, email.LoginAuth("user name", "password"), HOST, email.TLSConfig(HOST), email.TextprotoLogged(pLog, true), // true for ANSI colors, false for no colors )
type Email ¶
type Email struct { ReplyTo []string From string To []string Bcc []string Cc []string Subject string Text []byte // Plaintext message (optional) HTML []byte // Html message (optional) Sender string // override From as SMTP envelope sender (optional) Headers textproto.MIMEHeader Attachments []*Attachment ReadReceipt []string }
func NewEmailFromReader ¶
Reads a stream of bytes from an io.Reader, and returns an email struct containing the parsed data. This function expects the data in RFC 5322 format.
func (*Email) Attach ¶
Attaches content from an io.Reader to the email. The function will return the created Attachment for reference.
func (*Email) AttachFile ¶
func (e *Email) AttachFile(filename string) (a *Attachment, E error)
Attaches content to the email via filesystem. It attempts to open the file referenced by filename and, if successful, creates an Attachment. This Attachment is then appended to the slice of Email.Attachments. The function will then return the Attachment for reference.
func (*Email) Bytes ¶
Converts the Email object to a []byte representation--including all needed MIMEHeaders, boundaries, etc.
func (*Email) ParseSender ¶
Select and parse an SMTP envelope sender address. Choose Email.Sender if set, or fallback to Email.From.
type SMTPClientConfig ¶
type SMTPClientConfig struct { Server string Port uint16 Username string Password string Mode SMTPClientMode TimeoutMsec uint32 Proto string // dial protocol: `tcp`, `tcp4`, or `tcp6`; defaults to `tcp` SMTPLog string // path to SMTP log: complete filepath, "-" for STDOUT, or empty to disable SMTP logging }
func (SMTPClientConfig) SimpleSend ¶
func (CFG SMTPClientConfig) SimpleSend(MSG ...*Email) (E error)
Example
oCfg := SMTPClientConfig{ Server: "mx.test.com", Port: 587, Username: "test@test.com", Password: "...", Mode: ModeSTARTTLS, // SMTPLog: "-", // note: uncomment to log SMTP session to STDOUT } oEmail := NewEmail() oEmail.From = "test@test.com" oEmail.To = []string{"test_receiver@eggplant.pro"} oEmail.Subject = "Test Message" oEmail.Text = []byte("Whoomp there it is!") E := oCfg.SimpleSend(oEmail) if E != nil { return E }
type SMTPClientMode ¶
type SMTPClientMode uint8
const ( ModeUNENCRYPTED SMTPClientMode = 0 ModeSTARTTLS SMTPClientMode = 1 ModeFORCETLS SMTPClientMode = 2 )
func (*SMTPClientMode) UnmarshalJSON ¶
func (MODE *SMTPClientMode) UnmarshalJSON(V []byte) (E error)
type ServerInfo ¶
type ServerInfo struct { Name string // SMTP server name TLS bool // using TLS, with valid certificate for Name Auth []string // advertised authentication mechanisms }
ServerInfo records information about an SMTP server.
type TextProtoConn ¶
type TextProtoConn interface { StartResponse(id uint) EndResponse(id uint) Cmd(format string, args ...interface{}) (id uint, err error) ReadResponse(expectCode int) (code int, message string, err error) DotWriter() io.WriteCloser Close() error }
This interface implements all textproto actions used by the SMTP Client.
Communication hits textproto before crypto and the wire, so this is useful for inserting/removing/capturing commands before they are encrypted and sent down the wire.