smtp

README

go-smtp

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"

	"github.com/emersion/go-sasl"
	"github.com/emersion/go-smtp"
)

func main() {
	// Set up 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.

Server

package main

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

	"github.com/emersion/go-smtp"
)

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

// Login handles a login command with username and password.
func (bkd *Backend) Login(state *smtp.ConnectionState, username, password string) (smtp.Session, error) {
	if username != "username" || password != "password" {
		return nil, errors.New("Invalid username or password")
	}
	return &Session{}, nil
}

// AnonymousLogin requires clients to authenticate using SMTP AUTH before sending emails
func (bkd *Backend) AnonymousLogin(state *smtp.ConnectionState) (smtp.Session, error) {
	return nil, smtp.ErrAuthRequired
}

// A Session is returned after successful login.
type Session struct{}

func (s *Session) Mail(from string) 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
.

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

LMTP (RFC 2033) is also supported.

Additional extensions may be handled by other packages.

Index

• Variables
• func SendMail(addr string, a sasl.Client, from string, to []string, r io.Reader) error
• type Backend
• type Client
  • func Dial(addr string) (*Client, error)
  • func DialTLS(addr string, tlsConfig *tls.Config) (*Client, error)
  • func NewClient(conn net.Conn, host string) (*Client, error)
  • func NewClientLMTP(conn net.Conn, host string) (*Client, error)
  • func (c *Client) Auth(a sasl.Client) 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) 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) StartTLS(config *tls.Config) error
  • func (c *Client) TLSConnectionState() (state tls.ConnectionState, ok bool)
  • func (c *Client) Verify(addr string) error
• type Conn
  • func (c *Conn) Close() error
  • func (c *Conn) ReadLine() (string, error)
  • func (c *Conn) Reject()
  • func (c *Conn) Server() *Server
  • func (c *Conn) Session() Session
  • func (c *Conn) SetSession(session Session)
  • func (c *Conn) State() ConnectionState
  • func (c *Conn) TLSConnectionState() (state tls.ConnectionState, ok bool)
  • func (c *Conn) WriteResponse(code int, enhCode EnhancedCode, text ...string)
• type ConnectionState
• type EnhancedCode
• type Logger
• type SMTPError
  • func (err *SMTPError) Error() string
  • func (err *SMTPError) Temporary() bool
• type SaslServerFactory
• type Server
  • func NewServer(be Backend) *Server
  • func (s *Server) Close()
  • func (s *Server) EnableAuth(name string, f SaslServerFactory)
  • func (s *Server) ForEachConn(f func(*Conn))
  • func (s *Server) ListenAndServe() error
  • func (s *Server) ListenAndServeTLS() error
  • func (s *Server) Serve(l net.Listener) error
• type Session

Examples

• Dial
• NewServer
• SendMail

Variables

var (
	ErrAuthRequired    = errors.New("Please authenticate first")
	ErrAuthUnsupported = errors.New("Authentication not supported")
)

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).

var ErrDataTooLarge = &SMTPError{
	Code:         552,
	EnhancedCode: EnhancedCode{5, 3, 4},
	Message:      "Maximum message size exceeded",
}

var ErrTooLongLine = errors.New("smtp: too longer line in input stream")

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 if possible, authenticates with the optional mechanism a if possible, 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.

The SendMail function and the net/smtp package are low-level mechanisms and provide no support for DKIM signing, MIME attachments (see the mime/multipart package), or other mail functionality. Higher-level packages exist outside of the standard library.

Example

// Set up 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)
}

Types

type Backend

type Backend interface {
	// Authenticate a user. Return smtp.ErrAuthUnsupported if you don't want to
	// support this.
	Login(state *ConnectionState, username, password string) (Session, error)

	// Called if the client attempts to send mail without logging in first.
	// Return smtp.ErrAuthRequired if you don't want to support this.
	AnonymousLogin(state *ConnectionState) (Session, error)
}

A SMTP server backend.

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
	// 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".

Example

// Connect to the remote SMTP server.
c, err := smtp.Dial("mail.example.com:25")
if err != nil {
	log.Fatal(err)
}

// Set the sender and recipient first
if err := c.Mail("sender@example.org"); err != nil {
	log.Fatal(err)
}
if err := c.Rcpt("recipient@example.net"); err != nil {
	log.Fatal(err)
}

// Send the email body.
wc, err := c.Data()
if err != nil {
	log.Fatal(err)
}
_, err = fmt.Fprintf(wc, "This is the email body")
if err != nil {
	log.Fatal(err)
}
err = wc.Close()
if err != nil {
	log.Fatal(err)
}

// Send the QUIT command and close the connection.
err = c.Quit()
if err != nil {
	log.Fatal(err)
}

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".

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 connector 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. A failed authentication closes the connection. 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) Mail

func (c *Client) Mail(from string) 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 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.

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) 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.

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) ReadLine

func (c *Conn) ReadLine() (string, error)

Reads a line of input

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) SetSession

func (c *Conn) SetSession(session Session)

Setting the user resets any message being generated

func (*Conn) State

func (c *Conn) State() ConnectionState

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.

func (*Conn) WriteResponse

func (c *Conn) WriteResponse(code int, enhCode EnhancedCode, text ...string)

type ConnectionState

type ConnectionState struct {
	Hostname   string
	LocalAddr  net.Addr
	RemoteAddr net.Addr
	TLS        tls.ConnectionState
}

type EnhancedCode

type EnhancedCode [3]int

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 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

	// 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.

Example

be := &Backend{}

s := smtp.NewServer(be)

s.Addr = ":1025"
s.Domain = "localhost"
s.WriteTimeout = 10 * time.Second
s.ReadTimeout = 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)
}

func (*Server) Close

func (s *Server) Close()

Close stops the server.

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.

type Session

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

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

	// Set return path for currently processed message.
	Mail(from string) error
	// Add recipient for currently processed message.
	Rcpt(to string) error
	// Set currently processed message contents and send it.
	Data(r io.Reader) error
}