smtpd

README

Go smtpd

Package smtpd implements an SMTP server in golang. This is a fork of bitbucket.org/chrj/smtpd

Features

• STARTTLS (using crypto/tls)
• Authentication (PLAIN/LOGIN, only after STARTTLS)
• XCLIENT (for running behind a proxy)
• Connection, HELO, sender and recipient checks for rejecting e-mails using callbacks
• Configurable limits for: connection count, message size and recipient count
• Hands incoming e-mail off to a configured callback function

Documentation

Overview

Package smtpd implements an SMTP server with support for STARTTLS, authentication (PLAIN/LOGIN), XCLIENT and optional restrictions on the different stages of the SMTP session.

Index

• type Envelope
  • func (env *Envelope) AddReceivedLine(peer Peer)
• type Error
  • func NewError(code StatusCode, message string) Error
  • func (e Error) Error() string
• type Peer
• type Protocol
• type Server
  • func (srv *Server) ListenAndServe(addr string) error
  • func (srv *Server) Serve(l net.Listener) error
• type StatusCode

Types

type Envelope

type Envelope struct {
	Sender     string
	Recipients []string
	Data       []byte
}

Envelope holds a message

func (*Envelope) AddReceivedLine

func (env *Envelope) AddReceivedLine(peer Peer)

AddReceivedLine prepends a Received header to the Data

type Error

type Error struct {
	Code    StatusCode // The integer error (status) code
	Message string     // The error message
}

Error represents an Error reported in the SMTP session.

func NewError

func NewError(code StatusCode, message string) Error

NewError provides a helper for creating new Error instances.

func (Error) Error

func (e Error) Error() string

Error returns a string representation of the SMTP error

type Peer

type Peer struct {
	// Server name used in HELO/EHLO command
	HeloName string
	// Username from authentication, if authenticated
	Username string
	// Password from authentication, if authenticated
	Password string
	// Protocol used, SMTP or ESMTP
	Protocol Protocol
	// A copy of Server.Hostname
	ServerName string
	// Network address
	Addr net.Addr
	// TLS Connection details, if on TLS
	TLS *tls.ConnectionState
}

Peer represents the client connecting to the server

type Protocol

type Protocol string

Protocol represents the protocol used in the SMTP session

const (
	// SMTP protocol name
	SMTP Protocol = "SMTP"
	// ESMTP protocol name
	ESMTP = "ESMTP"
)

type Server

type Server struct {
	// Server hostname. (default: "localhost.localdomain")
	Hostname string
	// Initial server banner. (default: "<hostname> ESMTP ready.")
	WelcomeMessage string

	// Socket timeout for read operations. (default: 60s)
	ReadTimeout time.Duration
	// Socket timeout for write operations. (default: 60s)
	WriteTimeout time.Duration
	// Socket timeout for DATA command (default: 5m)
	DataTimeout time.Duration

	// Max concurrent connections, use -1 to disable. (default: 100)
	MaxConnections int
	// Max message size in bytes. (default: 10240000)
	MaxMessageSize int64
	// Max RCPT TO calls for each envelope. (default: 100)
	MaxRecipients int

	// New e-mails are handed off to this function.
	// Can be left empty for a NOOP server.
	// If an error is returned, it will be reported in the SMTP session.
	Handler func(peer Peer, env Envelope) error

	// Enable various checks during the SMTP session.
	// Can be left empty for no restrictions.
	// If an error is returned, it will be reported in the SMTP session.
	// Use the Error struct for access to error codes.
	ConnectionChecker func(peer Peer) error              // Called upon new connection.
	HeloChecker       func(peer Peer, name string) error // Called after HELO/EHLO.
	SenderChecker     func(peer Peer, addr string) error // Called after MAIL FROM.
	RecipientChecker  func(peer Peer, addr string) error // Called after each RCPT TO.

	// Enable PLAIN/LOGIN authentication, only available after STARTTLS.
	// Can be left empty for no authentication support.
	Authenticator func(peer Peer, username, password string) error

	// BlackHole is an optimization that allows quietly sending all the
	// incoming message to the big /dev/null in the sky while still
	// maintaining a polite conversation with the client. This behaviour is
	// triggered when the function is set and returns true. In that case the
	// Handler function is not invoked at all. Please note that the
	// Envelope at this stage has its Data field empty.
	BlackHole func(peer Peer, env Envelope) bool

	EnableXCLIENT bool // Enable XCLIENT support (default: false)

	TLSConfig *tls.Config // Enable STARTTLS support.
	ForceTLS  bool        // Force STARTTLS usage.
}

Server defines the parameters for running the SMTP server

func (*Server) ListenAndServe

func (srv *Server) ListenAndServe(addr string) error

ListenAndServe starts the SMTP server and listens on the address provided

func (*Server) Serve

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

Serve starts the SMTP server and listens on the Listener provided

type StatusCode

type StatusCode int

StatusCode represents SMTP status code

const (
	StatusSuccess              StatusCode = 200
	StatusSystem               StatusCode = 211
	StatusHelpMessage          StatusCode = 214
	StatusServiceReady         StatusCode = 220
	StatusServiceClosing       StatusCode = 221
	StatusAuthenticated        StatusCode = 235
	StatusOK                   StatusCode = 250
	StatusNotLocalWillForward  StatusCode = 251
	StatusCantVerifyWillAccept StatusCode = 252

	StatusProvideCredentials StatusCode = 334
	StatusStartMailInput     StatusCode = 354

	StatusServiceNotAvailable           StatusCode = 421
	StatusMailboxTemporarilyUnavailable StatusCode = 450
	StatusLocalError                    StatusCode = 451
	StatusInsufficientStorage           StatusCode = 452

	StatusCommandUnrecognized           StatusCode = 500
	StatusSyntaxError                   StatusCode = 501
	StatusCommandNotImplemented         StatusCode = 502
	StatusBadSequence                   StatusCode = 503
	StatusParameterNotImplemented       StatusCode = 504
	StatusDoesNotAcceptMail             StatusCode = 521
	StatusAccessDenied                  StatusCode = 530
	StatusMailboxPermanentlyUnavailable StatusCode = 550
	StatusUserNotLocal                  StatusCode = 551
	StatusExceededStorageAllocation     StatusCode = 552
	StatusMailboxNameNotAllowed         StatusCode = 553
	StatusTransactionFailed             StatusCode = 554
)

SMTP Status codes