README
¶
email.v2
Yet another SMTP client!
Features
This package currently supports the following:
- From, To, Bcc, and Cc fields
- Email addresses in both "test@example.com" and "First Last <test@example.com>" format
- Text and HTML Message Body
- Attachments
- Read Receipts
- Custom Headers
- SMTP Logging
- Integrated Client Settings
Installation
go get github.com/BourgeoisBear/email.v2
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 }
Reasons for Fork
This is a fork of https://github.com/jordan-wright/email
- ripped out connection pooling (sending via long-term connections to SMTP servers has not been reliable)
- condensed multiple Send... methods into NewClient() & Send() to
- provide a more generic way of establishing unauthenticated, SSL, and STARTTLS connections
- send multiple messages from within a single established SMTP session
- make direct use of outside net.Conn interfaces, so as to set dial and I/O deadlines
- added
LoginAuthauthentication interface for use with Office 365 - added
TextprotoLoggedfor full logging of SMTP traffic
Testing
To run unit tests, add the proper credentials to email_test_settings.json for accounts you choose to test with. Examples for O365, GMAIL, & CUSTOM have been provided.
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.
Source Files