smtp

package module
v0.0.0-...-a24e94d Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 14, 2023 License: MIT Imports: 19 Imported by: 0

README

go-smtp

godocs.io builds.sr.ht status

An ESMTP client and server library written in Go.

Features

  • ESMTP client & server implementing RFC 5321
  • Support for SMTP AUTH and PIPELINING
  • UTF-8 support for subject and message
  • LMTP support

Usage

Client
package main

import (
	"log"
	"strings"

	"gitee.com/wpkg/smtp/sasl"
	"gitee.com/wpkg/smtp"
)

func main() {
	// Setup authentication information.
	auth := sasl.NewPlainClient("", "user@example.com", "password")

	// Connect to the server, authenticate, set the sender and recipient,
	// and send the email all in one step.
	to := []string{"recipient@example.net"}
	msg := strings.NewReader("To: recipient@example.net\r\n" +
		"Subject: discount Gophers!\r\n" +
		"\r\n" +
		"This is the email body.\r\n")
	err := smtp.SendMail("mail.example.com:25", auth, "sender@example.org", to, msg)
	if err != nil {
		log.Fatal(err)
	}
}

If you need more control, you can use Client instead. For example, if you want to send an email via a server without TLS or auth support, you can do something like this:

package main

import (
	"log"
	"strings"

	"gitee.com/wpkg/smtp"
)

func main() {
	// Setup an unencrypted connection to a local mail server.
	c, err := smtp.Dial("localhost:25")
	if err != nil {
		return err
	}
	defer c.Close()

	// Set the sender and recipient, and send the email all in one step.
	to := []string{"recipient@example.net"}
	msg := strings.NewReader("To: recipient@example.net\r\n" +
		"Subject: discount Gophers!\r\n" +
		"\r\n" +
		"This is the email body.\r\n")
	err := c.SendMail("sender@example.org", to, msg)
	if err != nil {
		log.Fatal(err)
	}
}
Server
package main

import (
	"errors"
	"io"
	"io/ioutil"
	"log"
	"time"

	"gitee.com/wpkg/smtp"
)

// The Backend implements SMTP server methods.
type Backend struct{}

func (bkd *Backend) NewSession(_ *smtp.Conn) (smtp.Session, error) {
	return &Session{}, nil
}

// A Session is returned after EHLO.
type Session struct{}

func (s *Session) AuthPlain(username, password string) error {
	if username != "username" || password != "password" {
		return errors.New("Invalid username or password")
	}
	return nil
}

func (s *Session) Mail(from string, opts *smtp.MailOptions) error {
	log.Println("Mail from:", from)
	return nil
}

func (s *Session) Rcpt(to string) error {
	log.Println("Rcpt to:", to)
	return nil
}

func (s *Session) Data(r io.Reader) error {
	if b, err := ioutil.ReadAll(r); err != nil {
		return err
	} else {
		log.Println("Data:", string(b))
	}
	return nil
}

func (s *Session) Reset() {}

func (s *Session) Logout() error {
	return nil
}

func main() {
	be := &Backend{}

	s := smtp.NewServer(be)

	s.Addr = ":1025"
	s.Domain = "localhost"
	s.ReadTimeout = 10 * time.Second
	s.WriteTimeout = 10 * time.Second
	s.MaxMessageBytes = 1024 * 1024
	s.MaxRecipients = 50
	s.AllowInsecureAuth = true

	log.Println("Starting server at", s.Addr)
	if err := s.ListenAndServe(); err != nil {
		log.Fatal(err)
	}
}

You can use the server manually with telnet:

$ telnet localhost 1025
EHLO localhost
AUTH PLAIN
AHVzZXJuYW1lAHBhc3N3b3Jk
MAIL FROM:<root@nsa.gov>
RCPT TO:<root@gchq.gov.uk>
DATA
Hey <3
.

Relationship with net/smtp

The Go standard library provides a SMTP client implementation in net/smtp. However net/smtp is frozen: it's not getting any new features. go-smtp provides a server implementation and a number of client improvements.

Licence

MIT

Documentation

Overview

Package smtp 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
ENHANCEDSTATUSCODES: RFC 2034
SMTPUTF8: RFC 6531
REQUIRETLS: RFC 8689
CHUNKING: RFC 3030
BINARYMIME: RFC 3030

LMTP (RFC 2033) is also supported.

Additional extensions may be handled by other packages.

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrAuthRequired = &SMTPError{
		Code:         502,
		EnhancedCode: EnhancedCode{5, 7, 0},
		Message:      "Please authenticate first",
	}
	ErrAuthUnsupported = &SMTPError{
		Code:         502,
		EnhancedCode: EnhancedCode{5, 7, 0},
		Message:      "Authentication not supported",
	}
)
View Source 
var EnhancedCodeNotSet = EnhancedCode{0, 0, 0}

EnhancedCodeNotSet is a nil value of EnhancedCode field in SMTPError, used to indicate that backend failed to provide enhanced status code. X.0.0 will be used (X is derived from error code).

View Source 
var ErrDataReset = errors.New("smtp: message transmission aborted")

ErrDataReset is returned by Reader pased to Data function if client does not send another BDAT command and instead closes connection or issues RSET command.

View Source 
var ErrDataTooLarge = &SMTPError{
	Code:         552,
	EnhancedCode: EnhancedCode{5, 3, 4},
	Message:      "Maximum message size exceeded",
}
View Source 
var (
	ErrServerClosed = errors.New("smtp: server already closed")
)
View Source 
var ErrTooLongLine = errors.New("smtp: too long a line in input stream")
View Source 
var NoEnhancedCode = EnhancedCode{-1, -1, -1}

NoEnhancedCode is used to indicate that enhanced error code should not be included in response.

Note that RFC 2034 requires an enhanced code to be included in all 2xx, 4xx and 5xx responses. This constant is exported for use by extensions, you should probably use EnhancedCodeNotSet instead.

Functions

func SendMail 

func SendMail(addr string, a sasl.Client, from string, to []string, r io.Reader) error

SendMail connects to the server at addr, switches to TLS, authenticates with the optional SASL client, and then sends an email from address from, to addresses to, with message r. The addr must include a port, as in "mail.example.com:smtp".

The addresses in the to parameter are the SMTP RCPT addresses.

The r parameter should be an RFC 822-style email with headers first, a blank line, and then the message body. The lines of r should be CRLF terminated. The r headers should usually include fields such as "From", "To", "Subject", and "Cc". Sending "Bcc" messages is accomplished by including an email address in the to parameter but not including it in the r headers.

SendMail is intended to be used for very simple use-cases. If you want to customize SendMail's behavior, use a Client instead.

The SendMail function and the go-smtp package are low-level mechanisms and provide no support for DKIM signing (see go-msgauth), MIME attachments (see the mime/multipart package or the go-message package), or other mail functionality.

func SendMailTLS 

func SendMailTLS(addr string, a sasl.Client, from string, to []string, r io.Reader) error

SendMailTLS works like SendMail, but with implicit TLS.

Types

type Backend 

type Backend interface {
	NewSession(c *Conn) (Session, error)
}

A SMTP server backend.

type BodyType 

type BodyType string
const (
	Body7Bit       BodyType = "7BIT"
	Body8BitMIME   BodyType = "8BITMIME"
	BodyBinaryMIME BodyType = "BINARYMIME"
)

type Client 

type Client struct {
	// Text is the textproto.Conn used by the Client. It is exported to allow for
	// clients to add extensions.
	Text *textproto.Conn

	// Time to wait for command responses (this includes 3xx reply to DATA).
	CommandTimeout time.Duration
	// Time to wait for responses after final dot.
	SubmissionTimeout time.Duration

	// Logger for all network activity.
	DebugWriter io.Writer
	// contains filtered or unexported fields
}

A Client represents a client connection to an SMTP server.

func Dial 

func Dial(addr string) (*Client, error)

Dial returns a new Client connected to an SMTP server at addr. The addr must include a port, as in "mail.example.com:smtp".

func DialTLS 

func DialTLS(addr string, tlsConfig *tls.Config) (*Client, error)

DialTLS returns a new Client connected to an SMTP server via TLS at addr. The addr must include a port, as in "mail.example.com:smtps".

A nil tlsConfig is equivalent to a zero tls.Config.

func NewClient 

func NewClient(conn net.Conn, host string) (*Client, error)

NewClient returns a new Client using an existing connection and host as a server name to be used when authenticating.

func NewClientLMTP 

func NewClientLMTP(conn net.Conn, host string) (*Client, error)

NewClientLMTP returns a new LMTP Client (as defined in RFC 2033) using an existing connection and host as a server name to be used when authenticating.

func (*Client) Auth 

func (c *Client) Auth(a sasl.Client) error

Auth authenticates a client using the provided authentication mechanism. Only servers that advertise the AUTH extension support this function.

If server returns an error, it will be of type *SMTPError.

func (*Client) Close 

func (c *Client) Close() error

Close closes the connection.

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.

If server returns an error, it will be of type *SMTPError.

func (*Client) Extension 

func (c *Client) Extension(ext string) (bool, string)

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 

func (c *Client) Hello(localName string) error

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.

If server returns an error, it will be of type *SMTPError.

func (*Client) LMTPData 

func (c *Client) LMTPData(statusCb func(rcpt string, status *SMTPError)) (io.WriteCloser, error)

LMTPData is the LMTP-specific version of the Data method. It accepts a callback that will be called for each status response received from the server.

Status callback will receive a SMTPError argument for each negative server reply and nil for each positive reply. I/O errors will not be reported using callback and instead will be returned by the Close method of io.WriteCloser. Callback will be called for each successfull Rcpt call done before in the same order.

func (*Client) Mail 

func (c *Client) Mail(from string, opts *MailOptions) error

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.

If opts is not nil, MAIL arguments provided in the structure will be added to the command. Handling of unsupported options depends on the extension.

If server returns an error, it will be of type *SMTPError.

func (*Client) Noop 

func (c *Client) Noop() error

Noop sends the NOOP command to the server. It does nothing but check that the connection to the server is okay.

func (*Client) Quit 

func (c *Client) Quit() error

Quit sends the QUIT command and closes the connection to the server.

If Quit fails the connection is not closed, Close should be used in this case.

func (*Client) Rcpt 

func (c *Client) Rcpt(to string) error

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.

If server returns an error, it will be of type *SMTPError.

func (*Client) Reset 

func (c *Client) Reset() error

Reset sends the RSET command to the server, aborting the current mail transaction.

func (*Client) SendMail 

func (c *Client) SendMail(from string, to []string, r io.Reader) error

SendMail will use an existing connection to send an email from address from, to addresses to, with message r.

This function does not start TLS, nor does it perform authentication. Use StartTLS and Auth before-hand if desirable.

The addresses in the to parameter are the SMTP RCPT addresses.

The r parameter should be an RFC 822-style email with headers first, a blank line, and then the message body. The lines of r should be CRLF terminated. The r headers should usually include fields such as "From", "To", "Subject", and "Cc". Sending "Bcc" messages is accomplished by including an email address in the to parameter but not including it in the r headers.

func (*Client) StartTLS 

func (c *Client) StartTLS(config *tls.Config) error

StartTLS sends the STARTTLS command and encrypts all further communication. Only servers that advertise the STARTTLS extension support this function.

A nil config is equivalent to a zero tls.Config.

If server returns an error, it will be of type *SMTPError.

func (*Client) TLSConnectionState 

func (c *Client) TLSConnectionState() (state tls.ConnectionState, ok bool)

TLSConnectionState returns the client's TLS connection state. The return values are their zero values if StartTLS did not succeed.

func (*Client) Verify 

func (c *Client) Verify(addr string) error

Verify checks the validity of an email address on the server. If Verify returns nil, the address is valid. A non-nil return does not necessarily indicate an invalid address. Many servers will not verify addresses for security reasons.

If server returns an error, it will be of type *SMTPError.

type Conn 

type Conn struct {
	// contains filtered or unexported fields
}

func (*Conn) Close 

func (c *Conn) Close() error

func (*Conn) Conn 

func (c *Conn) Conn() net.Conn

func (*Conn) Hostname 

func (c *Conn) Hostname() string

func (*Conn) Reject 

func (c *Conn) Reject()

func (*Conn) Server 

func (c *Conn) Server() *Server

func (*Conn) Session 

func (c *Conn) Session() Session

func (*Conn) TLSConnectionState 

func (c *Conn) TLSConnectionState() (state tls.ConnectionState, ok bool)

TLSConnectionState returns the connection's TLS connection state. Zero values are returned if the connection doesn't use TLS.

type EnhancedCode 

type EnhancedCode [3]int

type LMTPSession 

type LMTPSession interface {
	// LMTPData is the LMTP-specific version of Data method.
	// It can be optionally implemented by the backend to provide
	// per-recipient status information when it is used over LMTP
	// protocol.
	//
	// LMTPData implementation sets status information using passed
	// StatusCollector by calling SetStatus once per each AddRcpt
	// call, even if AddRcpt was called multiple times with
	// the same argument. SetStatus must not be called after
	// LMTPData returns.
	//
	// Return value of LMTPData itself is used as a status for
	// recipients that got no status set before using StatusCollector.
	LMTPData(r io.Reader, status StatusCollector) error
}

LMTPSession is an add-on interface for Session. It can be implemented by LMTP servers to provide extra functionality.

type Logger 

type Logger interface {
	Printf(format string, v ...interface{})
	Println(v ...interface{})
}

Logger interface is used by Server to report unexpected internal errors.

type MailOptions 

type MailOptions struct {
	// Value of BODY= argument, 7BIT, 8BITMIME or BINARYMIME.
	Body BodyType

	// Size of the body. Can be 0 if not specified by client.
	Size int

	// TLS is required for the message transmission.
	//
	// The message should be rejected if it can't be transmitted
	// with TLS.
	RequireTLS bool

	// The message envelope or message header contains UTF-8-encoded strings.
	// This flag is set by SMTPUTF8-aware (RFC 6531) client.
	UTF8 bool

	// The authorization identity asserted by the message sender in decoded
	// form with angle brackets stripped.
	//
	// nil value indicates missing AUTH, non-nil empty string indicates
	// AUTH=<>.
	//
	// Defined in RFC 4954.
	Auth *string
}

MailOptions contains custom arguments that were passed as an argument to the MAIL command.

type SMTPError 

type SMTPError struct {
	Code         int
	EnhancedCode EnhancedCode
	Message      string
}

SMTPError specifies the error code, enhanced error code (if any) and message returned by the server.

func (*SMTPError) Error 

func (err *SMTPError) Error() string

func (*SMTPError) Temporary 

func (err *SMTPError) Temporary() bool

type SaslServerFactory 

type SaslServerFactory func(conn *Conn) sasl.Server

A function that creates SASL servers.

type Server 

type Server struct {
	// TCP or Unix address to listen on.
	Addr string
	// The server TLS configuration.
	TLSConfig *tls.Config
	// Enable LMTP mode, as defined in RFC 2033. LMTP mode cannot be used with a
	// TCP listener.
	LMTP bool

	Domain            string
	MaxRecipients     int
	MaxMessageBytes   int
	MaxLineLength     int
	AllowInsecureAuth bool
	Strict            bool
	Debug             io.Writer
	ErrorLog          Logger
	ReadTimeout       time.Duration
	WriteTimeout      time.Duration

	// Advertise SMTPUTF8 (RFC 6531) capability.
	// Should be used only if backend supports it.
	EnableSMTPUTF8 bool

	// Advertise REQUIRETLS (RFC 8689) capability.
	// Should be used only if backend supports it.
	EnableREQUIRETLS bool

	// Advertise BINARYMIME (RFC 3030) capability.
	// Should be used only if backend supports it.
	EnableBINARYMIME bool

	// If set, the AUTH command will not be advertised and authentication
	// attempts will be rejected. This setting overrides AllowInsecureAuth.
	AuthDisabled bool

	// The server backend.
	Backend Backend
	// contains filtered or unexported fields
}

A SMTP server.

func NewServer 

func NewServer(be Backend) *Server

New creates a new SMTP server.

func (*Server) Close 

func (s *Server) Close() error

Close immediately closes all active listeners and connections.

Close returns any error returned from closing the server's underlying listener(s).

func (*Server) EnableAuth 

func (s *Server) EnableAuth(name string, f SaslServerFactory)

EnableAuth enables an authentication mechanism on this server.

This function should not be called directly, it must only be used by libraries implementing extensions of the SMTP protocol.

func (*Server) ForEachConn 

func (s *Server) ForEachConn(f func(*Conn))

ForEachConn iterates through all opened connections.

func (*Server) ListenAndServe 

func (s *Server) ListenAndServe() error

ListenAndServe listens on the network address s.Addr and then calls Serve to handle requests on incoming connections.

If s.Addr is blank and LMTP is disabled, ":smtp" is used.

func (*Server) ListenAndServeTLS 

func (s *Server) ListenAndServeTLS() error

ListenAndServeTLS listens on the TCP network address s.Addr and then calls Serve to handle requests on incoming TLS connections.

If s.Addr is blank, ":smtps" is used.

func (*Server) Serve 

func (s *Server) Serve(l net.Listener) error

Serve accepts incoming connections on the Listener l.

func (*Server) Shutdown 

func (s *Server) Shutdown(ctx context.Context) error

Shutdown gracefully shuts down the server without interrupting any active connections. Shutdown works by first closing all open listeners and then waiting indefinitely for connections to return to idle and then shut down. If the provided context expires before the shutdown is complete, Shutdown returns the context's error, otherwise it returns any error returned from closing the Server's underlying Listener(s).

type Session 

type Session interface {
	// Discard currently processed message.
	Reset()

	// Free all resources associated with session.
	Logout() error

	// Authenticate the user using SASL PLAIN.
	AuthPlain(username, password string) error

	// Set return path for currently processed message.
	Mail(from string, opts *MailOptions) error
	// Add recipient for currently processed message.
	Rcpt(to string) error
	// Set currently processed message contents and send it.
	//
	// r must be consumed before Data returns.
	Data(r io.Reader) error
}

Session is used by servers to respond to an SMTP client.

The methods are called when the remote client issues the matching command.

type StatusCollector 

type StatusCollector interface {
	SetStatus(rcptTo string, err error)
}

StatusCollector allows a backend to provide per-recipient status information.

Source Files

View all Source files

Directories

Path Synopsis
Library for Simple Authentication and Security Layer (SASL) defined in RFC 4422.
 Library for Simple Authentication and Security Layer (SASL) defined in RFC 4422.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.