smtp

README

SMTP

This is a really simple SMTP server implementation in Go. You can use it to build basic SMTP servers.

Check the examples/basic package.

License

Copyright © 2021 Stojan Dimitrovski, some rights reserved.

Licensed under the MIT license. You can get a copy of it in LICENSE.

Documentation

Index

• Constants
• type CommitAction
• type Config
• type DataAction
• type Envelope
• type FromAction
• type Server
  • func NewServer(config Config) *Server
  • func (srv *Server) Accept(ctx context.Context, conn net.Conn, ...)
  • func (srv *Server) Wait()
• type Session
  • func (sess *Session) Domain() []byte
  • func (sess *Session) ViaTLS() bool
• type SizeAction
• type ToAction

Constants

const (
	AcceptFROM            FromAction = iota
	RejectFROMTemporarily            = iota
	RejectFROMPermanently            = iota
)

const (
	AcceptTO            ToAction = iota
	RejectTOTemporarily          = iota
	RejectTOPermanently          = iota
)

const (
	AcceptSIZE            SizeAction = iota
	RejectSIZETemporarily            = iota
	RejectSIZEPermanently            = iota
)

const (
	AcceptCommit                           CommitAction = iota
	RejectCommitTemporarily                             = iota
	RejectCommitPermanently                             = iota
	RejectCommitForTooManyRecipients                    = iota
	RejectCommitTemporarilyForSizeExceeded              = iota
	RejectCommitPermanentlyForSizeExceeded              = iota
)

Types

type CommitAction

type CommitAction = int

type Config

type Config struct {
	// SMTP service's domain. This should be the same domain advertised in the
	// recipient's MX records, as well as the same CN of the TLS certificate.
	// If you don't specify this the ServerName from TLS will be used, and if
	// that's not available "example.com" will be used.
	Domain string

	// Size of the buffer per connection. Avoid setting this below 538 bytes,
	// as that is the standard line length of SMTP (512 + 26 for SIZE). If
	// unspecified will use 4 pages.
	BufferSize uint

	// TLS config for the server.
	TLS *tls.Config

	// Whether this SMTP server requires STARTTLS. Does not make sense if TLS is nil.
	TLSRequired bool

	// Callback for creating a new envelope.
	NewEnvelope func(ctx context.Context, sess *Session) (Envelope, error)

	// Logger for the server. If you do not specify this NewExample() from Zap will be used.
	Logger *zap.Logger
}

A SMTP server configuration.

type DataAction

type DataAction = int

const (
	AcceptDATA DataAction = iota
	RejectDATA            = iota
)

type Envelope

type Envelope interface {
	// Add the reverse path to the envelope. Returning an error will terminate
	// the connection.
	From(ctx context.Context, addr []byte) (FromAction, error)

	// Add a size hint to the envelope. Returning an error will terminate the
	// connection. Size hint of 0 may mean an advertised data length of 0 or
	// none advertised.
	Size(ctx context.Context, size uint64) (SizeAction, error)

	// Add a recipient to the envelope. Returning an error will terminate the
	// connection.
	To(ctx context.Context, addr []byte) (ToAction, error)

	// Open the envelope for writing data. Ideally report any errors from From,
	// Size or To in this step, or from the context cancellation, as an error
	// here does not terminate the connection.
	Open(ctx context.Context) (DataAction, error)

	// Write a line to the envelope. Returning an error will terminate the
	// connection.
	Write(ctx context.Context, line []byte) error

	// Commit the data. If you accept the commit, the SMTP client expects the
	// mail to be delivered. If you return an error the transaction will be
	// cancelled.
	Commit(ctx context.Context) (CommitAction, error)

	// Discard this envelope. Returning an error does not affect the
	// connection.
	Discard(ctx context.Context) error
}

Describes a SMTP mail envelope.

type FromAction

type FromAction = int

type Server

type Server struct {
	Config *Config
	// contains filtered or unexported fields
}

An SMTP Server, use NewServer to create one.

func NewServer

func NewServer(config Config) *Server

Creates a new Server with the provided Config.

func (*Server) Accept

func (srv *Server) Accept(ctx context.Context, conn net.Conn, sessionFn func(ctx context.Context, srv *Server, sess *Session, init bool))

Accept a new SMTP connection. The sessionFn callback will be called from within the goroutine handling the dialog twice: at the initialization of the session and once the dialog has finished. Use Wait to wait all goroutines started with this to finish. Cancelling the context will close all dialogs in an orderly fashion.

func (*Server) Wait

func (srv *Server) Wait()

Waits for all goroutines started from within Accept to finish orderly.

type Session

type Session struct {
	// Unique ID of this session.
	ID string

	// Address of the SMTP client.
	Addr string
	// contains filtered or unexported fields
}

An SMTP session with a client.

func (*Session) Domain

func (sess *Session) Domain() []byte

Domain reported by the SMTP client in the EHLO/HELO command. Will be nil if such a command has not been received.

func (*Session) ViaTLS

func (sess *Session) ViaTLS() bool

Whether the session is over a TLS connection.

type SizeAction

type SizeAction = int

type ToAction

type ToAction = int