README
¶
smtp
Go library that improves and extends net/smtp.
The SMTP client in net/smtp already supports a number of features:
- Support for PLAIN authentication.
- Support for CRAM-MD5 authentication.
- Support for STARTTLS encryption.
But it also misses some features which limit it's application to simple forwarding scenarios.
This library adds the following features:
- Support binding to specific local IP.
- Use port 25 if no port specified instead of always requiring port.
- Use os.Hostname as default EHLO name instead of using "localhost" as default.
- Disable TLS domain verification, unless serverName is specified.
- Provide Session() and Transaction() members as intermediate level API.
- Support for PIPELINING extension.
- Send DATA if at least one RCPT is accepted instead of returning after the first failed recipient.
- Context information in SMTP errors showing the stage of the transaction.
TODOS:
- Do not send HELO after EHLO with 4XX error.
- Command-response timeouts according to RFC.
- Issue RSET before next transaction if last transaction failed.
- Less picky about response codes, the first digit is conclusive.
Usage
Forward one message
To connect to an MX, forward a message, and disconnect:
err = smtp.SendMail(mx, sender, recipients, message, nil)
Bulk email delivery
To connect to an MX from a specific local IP address:
client, err := smtp.DialFrom("gmail-smtp-in.l.google.com", net.ParseIP("1.2.3.4"))
To initiate a session, using "opportunistic" TLS and no authentication:
err := client.Session("mail.example.com", "", nil)
To start a transaction, using pipelining if available:
wc, err := client.Transaction(sender, recipients)
If multiple recipients are specified, some can be rejected and some can be accepted. If the transaction succeeds and at least one recipient was accepted a non-nil io.WriteCloser is returned. A non-nil err indicates that the transaction failed, or that at least one recipient was rejected.
To send the message from an io.Reader:
_, err := io.Copy(wc, reader)
if err != nil {
return err
}
err = wc.Close()
Then another transaction can be started or the session can be terminated:
client.Quit()
License
MIT
Documentation
¶
Overview ¶
Package smtp is a replacement for net/smtp with improvements and additions.
Index ¶
- Variables
- func CRAMMD5Auth(username, secret string) smtp.Auth
- func IsPermanent(err error) bool
- func MergeError(prevErr error, newErr error) error
- func PlainAuth(identity, username, password, host string) smtp.Auth
- func SendMail(addr string, auth smtp.Auth, from string, to []string, msg []byte) error
- type Client
- type MultiError
Constants ¶
This section is empty.
Variables ¶
var ( // ConnectTimeout is shortened in some mtas, the OS may also impose shorter timeouts ConnectTimeout = 5 * time.Minute GreetingTimeout = 5 * time.Minute )
Functions ¶
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 IsPermanent ¶
IsPermanent returns true if err is a reply with 5XX status code
func MergeError ¶
MergeError merges a new error with a previous error. If there was a previous error, this will be returned. Otherwise the new error is returned. If the error is a MultiError, the same rule is applied for each individual error.
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 on TLS connections to host and act as identity. Usually identity will be left blank to act as username.
Types ¶
type Client ¶
Client embeds a smtp.Client and provides additional member functions
func Dial ¶
Dial connects to addr from the default IP, waits for the banner greeting and returns a new Client.
func DialFrom ¶
DialFrom connects to addr from the specified localIP, waits for the banner greeting and returns a new Client.
func NewClient ¶
NewClient waits for the 220 banner greeting and returns a new Client using an existing connection and host as a server name to be used when authenticating.
func (*Client) Transaction ¶
Transaction starts a new transaction. A transaction can "partially fail" if at least one, but not all recipients failed. If MAIL and at least one RCPT succeeded, the DATA command is sent and io.WriteCloser is returned if DATA succeeded. If at least one recipient has failed, an error is returned. If more than one recipient failed a MultiError is returned.
type MultiError ¶
type MultiError []error
MultiError is returned by batch operations when there are errors with particular elements. Errors will be in a one-to-one correspondence with the input elements; successful elements will have a nil entry.
func (MultiError) Error ¶
func (m MultiError) Error() string
Source Files