go-milter: github.com/emersion/go-milter Index | Files

package milter

import "github.com/emersion/go-milter"

Package milter provides an interface to implement milter mail filters


Package Files

client.go cstrings.go message.go milter.go modifier.go response.go server.go session.go


const (
    RespAccept   = SimpleResponse(ActAccept)
    RespContinue = SimpleResponse(ActContinue)
    RespDiscard  = SimpleResponse(ActDiscard)
    RespReject   = SimpleResponse(ActReject)
    RespTempFail = SimpleResponse(ActTempFail)

Define standard responses with no data

const MaxBodyChunk = 65535


var ErrServerClosed = errors.New("milter: server closed")

ErrServerClosed is returned by the Server's Serve method after a call to Close.

type Action Uses

type Action struct {
    Code ActionCode

    // SMTP code if Code == ActReplyCode.
    SMTPCode int
    // Reply text if Code == ActReplyCode.
    SMTPText string

type ActionCode Uses

type ActionCode byte
const (
    ActAccept    ActionCode = 'a'
    ActContinue  ActionCode = 'c'
    ActDiscard   ActionCode = 'd'
    ActReject    ActionCode = 'r'
    ActTempFail  ActionCode = 't'
    ActReplyCode ActionCode = 'y'
    ActSkip      ActionCode = 's'

type Client Uses

type Client struct {
    // contains filtered or unexported fields

Client is a wrapper for managing milter connections.

Currently it just creates new connections using provided Dialer.

func NewClientWithOptions Uses

func NewClientWithOptions(network, address string, opts ClientOptions) *Client

NewClientWithOptions creates a new Client object using provided options.

You generally want to use options to restrict ActionMask to what your code supports and ProtocolMask to what you intend to submit.

If opts.Dialer is not set, empty net.Dialer object will be used.

func NewDefaultClient Uses

func NewDefaultClient(network, address string) *Client

NewDefaultClient creates a new Client object using default options.

It uses 10 seconds for connection/read/write timeouts and allows milter to send any actions supported by library.

func (*Client) Close Uses

func (c *Client) Close() error

func (*Client) Session Uses

func (c *Client) Session() (*ClientSession, error)

type ClientOptions Uses

type ClientOptions struct {
    Dialer       Dialer
    ReadTimeout  time.Duration
    WriteTimeout time.Duration
    ActionMask   OptAction
    ProtocolMask OptProtocol

type ClientSession Uses

type ClientSession struct {

    // Bitmask of negotiated action options.
    ActionOpts OptAction

    // Bitmask of negotiated protocol options.
    ProtocolOpts OptProtocol
    // contains filtered or unexported fields

func (*ClientSession) ActionOption Uses

func (s *ClientSession) ActionOption(opt OptAction) bool

ActionOption checks whether the option is set in negotiated options, that is, requested by both sides.

func (*ClientSession) BodyChunk Uses

func (s *ClientSession) BodyChunk(chunk []byte) (*Action, error)

BodyChunk sends a single body chunk to the milter.

It is callers responsibility to ensure every chunk is not bigger than MaxBodyChunk.

If OptSkip was specified during negotiation, caller should be ready to handle return ActSkip and stop sending body chunks if it is returned.

func (*ClientSession) BodyReadFrom Uses

func (s *ClientSession) BodyReadFrom(r io.Reader) ([]ModifyAction, *Action, error)

BodyReadFrom is a helper function that calls BodyChunk repeately to transmit entire body from io.Reader and then calls End.

See documentation for these functions for details.

func (*ClientSession) Close Uses

func (s *ClientSession) Close() error

Close releases resources associated with the session.

If there a milter sequence in progress - it is aborted.

func (*ClientSession) Conn Uses

func (s *ClientSession) Conn(hostname string, family ProtoFamily, port uint16, addr string) (*Action, error)

Conn sends the connection information to the milter.

It should be called once per milter session (from Session to Close).

func (*ClientSession) End Uses

func (s *ClientSession) End() ([]ModifyAction, *Action, error)

End sends the EOB message and resets session back to the state before Mail call. The same ClientSession can be used to check another message arrived within the same SMTP connection (Helo and Conn information is preserved).

Close should be called to conclude session.

func (*ClientSession) Header Uses

func (s *ClientSession) Header(hdr textproto.Header) (*Action, error)

Header sends each field from textproto.Header followed by EOH unless header messages are disabled during negotiation.

func (*ClientSession) HeaderEnd Uses

func (s *ClientSession) HeaderEnd() (*Action, error)

HeaderEnd send the EOH (End-Of-Header) message to the milter.

No HeaderField calls are allowed after this point.

func (*ClientSession) HeaderField Uses

func (s *ClientSession) HeaderField(key, value string) (*Action, error)

HeaderField sends a single header field to the milter.

Value should be the original field value without any unfolding applied.

HeaderEnd() must be called after the last field.

func (*ClientSession) Helo Uses

func (s *ClientSession) Helo(helo string) (*Action, error)

Helo sends the HELO hostname to the milter.

It should be called once per milter session (from Session to Close).

func (*ClientSession) Macros Uses

func (s *ClientSession) Macros(code Code, kv ...string) error

func (*ClientSession) Mail Uses

func (s *ClientSession) Mail(sender string, esmtpArgs []string) (*Action, error)

func (*ClientSession) ProtocolOption Uses

func (s *ClientSession) ProtocolOption(opt OptProtocol) bool

ProtocolOption checks whether the option is set in negotiated options, that is, requested by both sides.

func (*ClientSession) Rcpt Uses

func (s *ClientSession) Rcpt(rcpt string, esmtpArgs []string) (*Action, error)

type Code Uses

type Code byte
const (
    CodeOptNeg Code = 'O' // SMFIC_OPTNEG
    CodeMacro  Code = 'D' // SMFIC_MACRO
    CodeConn   Code = 'C' // SMFIC_CONNECT
    CodeQuit   Code = 'Q' // SMFIC_QUIT
    CodeHelo   Code = 'H' // SMFIC_HELO
    CodeMail   Code = 'M' // SMFIC_MAIL
    CodeRcpt   Code = 'R' // SMFIC_RCPT
    CodeHeader Code = 'L' // SMFIC_HEADER
    CodeEOH    Code = 'N' // SMFIC_EOH
    CodeBody   Code = 'B' // SMFIC_BODY
    CodeEOB    Code = 'E' // SMFIC_BODYEOB
    CodeAbort  Code = 'A' // SMFIC_ABORT

type CustomResponse Uses

type CustomResponse struct {
    // contains filtered or unexported fields

CustomResponse is a response instance used by callback handlers to indicate how the milter should continue processing of current message

func NewResponse Uses

func NewResponse(code byte, data []byte) *CustomResponse

NewResponse generates a new CustomResponse suitable for WritePacket

func NewResponseStr Uses

func NewResponseStr(code byte, data string) *CustomResponse

NewResponseStr generates a new CustomResponse with string payload

func (*CustomResponse) Continue Uses

func (c *CustomResponse) Continue() bool

Continue returns false if milter chain should be stopped, true otherwise

func (*CustomResponse) Response Uses

func (c *CustomResponse) Response() *Message

Response returns message instance with data

type Dialer Uses

type Dialer interface {
    Dial(network string, addr string) (net.Conn, error)

type Message Uses

type Message struct {
    Code byte
    Data []byte

Message represents a command sent from milter client

type Milter Uses

type Milter interface {
    // Connect is called to provide SMTP connection data for incoming message.
    // Suppress with OptNoConnect.
    Connect(host string, family string, port uint16, addr net.IP, m *Modifier) (Response, error)

    // Helo is called to process any HELO/EHLO related filters. Suppress with
    // OptNoHelo.
    Helo(name string, m *Modifier) (Response, error)

    // MailFrom is called to process filters on envelope FROM address. Suppress
    // with OptNoMailFrom.
    MailFrom(from string, m *Modifier) (Response, error)

    // RcptTo is called to process filters on envelope TO address. Suppress with
    // OptNoRcptTo.
    RcptTo(rcptTo string, m *Modifier) (Response, error)

    // Header is called once for each header in incoming message. Suppress with
    // OptNoHeaders.
    Header(name string, value string, m *Modifier) (Response, error)

    // Headers is called when all message headers have been processed. Suppress
    // with OptNoEOH.
    Headers(h textproto.MIMEHeader, m *Modifier) (Response, error)

    // BodyChunk is called to process next message body chunk data (up to 64KB
    // in size). Suppress with OptNoBody.
    BodyChunk(chunk []byte, m *Modifier) (Response, error)

    // Body is called at the end of each message. All changes to message's
    // content & attributes must be done here.
    Body(m *Modifier) (Response, error)

Milter is an interface for milter callback handlers.

type Modifier Uses

type Modifier struct {
    Macros  map[string]string
    Headers textproto.MIMEHeader
    // contains filtered or unexported fields

Modifier provides access to Macros, Headers and Body data to callback handlers. It also defines a number of functions that can be used by callback handlers to modify processing of the email message

func (*Modifier) AddHeader Uses

func (m *Modifier) AddHeader(name, value string) error

AddHeader appends a new email message header the message

func (*Modifier) AddRecipient Uses

func (m *Modifier) AddRecipient(r string) error

AddRecipient appends a new envelope recipient for current message

func (*Modifier) ChangeFrom Uses

func (m *Modifier) ChangeFrom(value string) error

ChangeFrom replaces the FROM envelope header with a new one

func (*Modifier) ChangeHeader Uses

func (m *Modifier) ChangeHeader(index int, name, value string) error

ChangeHeader replaces the header at the specified position with a new one. The index is per name.

func (*Modifier) DeleteRecipient Uses

func (m *Modifier) DeleteRecipient(r string) error

DeleteRecipient removes an envelope recipient address from message

func (*Modifier) InsertHeader Uses

func (m *Modifier) InsertHeader(index int, name, value string) error

InsertHeader inserts the header at the specified position

func (*Modifier) Quarantine Uses

func (m *Modifier) Quarantine(reason string) error

Quarantine a message by giving a reason to hold it

func (*Modifier) ReplaceBody Uses

func (m *Modifier) ReplaceBody(body []byte) error

ReplaceBody substitutes message body with provided body

type ModifyActCode Uses

type ModifyActCode byte
const (
    ActAddRcpt      ModifyActCode = '+'
    ActDelRcpt      ModifyActCode = '-'
    ActReplBody     ModifyActCode = 'b'
    ActAddHeader    ModifyActCode = 'h'
    ActChangeHeader ModifyActCode = 'm'
    ActInsertHeader ModifyActCode = 'i'
    ActChangeFrom   ModifyActCode = 'e'
    ActQuarantine   ModifyActCode = 'q'

type ModifyAction Uses

type ModifyAction struct {
    Code ModifyActCode

    // Recipient to add/remove if Code == ActAddRcpt or ActDelRcpt.
    Rcpt string

    // New envelope sender if Code = ActChangeFrom.
    From string

    // ESMTP arguments for envelope sender if Code = ActChangeFrom.
    FromArgs []string

    // Portion of body to be replaced if Code == ActReplBody.
    Body []byte

    // Index of the header field to be changed if Code = ActChangeHeader or Code = ActInsertHeader.
    // Index is 1-based and is per value of HdrName.
    // E.g. HeaderIndex = 3 and HdrName = "DKIM-Signature" mean "change third
    // DKIM-Signature field". Order is the same as of HeaderField calls.
    HeaderIndex uint32

    // Header field name to be added/changed if Code == ActAddHeader or
    // ActChangeHeader or ActInsertHeader.
    HeaderName string

    // Header field value to be added/changed if Code == ActAddHeader or
    // ActChangeHeader or ActInsertHeader. If set to empty string - the field
    // should be removed.
    HeaderValue string

    // Quarantine reason if Code == ActQuarantine.
    Reason string

type OptAction Uses

type OptAction uint32

OptAction sets which actions the milter wants to perform. Multiple options can be set using a bitmask.

const (
    OptAddHeader    OptAction = 0x01
    OptChangeBody   OptAction = 0x02
    OptAddRcpt      OptAction = 0x04
    OptRemoveRcpt   OptAction = 0x08
    OptChangeHeader OptAction = 0x10
    OptQuarantine   OptAction = 0x20
    OptChangeFrom   OptAction = 0x40

set which actions the milter wants to perform

type OptProtocol Uses

type OptProtocol uint32

OptProtocol masks out unwanted parts of the SMTP transaction. Multiple options can be set using a bitmask.

const (
    OptNoConnect  OptProtocol = 0x01
    OptNoHelo     OptProtocol = 0x02
    OptNoMailFrom OptProtocol = 0x04
    OptNoRcptTo   OptProtocol = 0x08
    OptNoBody     OptProtocol = 0x10
    OptNoHeaders  OptProtocol = 0x20
    OptNoEOH      OptProtocol = 0x40

    // [v6] MTA supports ActSkip.
    OptSkip OptProtocol = 0x400

    // [v6] milter will not send action response for following MTA messages.
    OptNoHeaderReply  OptProtocol = 0x80
    OptNoConnReply    OptProtocol = 0x1000
    OptNoHeloReply    OptProtocol = 0x2000
    OptNoMailReply    OptProtocol = 0x4000
    OptNoRcptReply    OptProtocol = 0x8000
    OptNoDataReply    OptProtocol = 0x10000
    OptNoUnknownReply OptProtocol = 0x20000
    OptNoEOHReply     OptProtocol = 0x40000
    OptNoBodyReply    OptProtocol = 0x80000

type ProtoFamily Uses

type ProtoFamily byte
const (
    FamilyUnknown ProtoFamily = 'U' // SMFIA_UNKNOWN
    FamilyUnix    ProtoFamily = 'L' // SMFIA_UNIX
    FamilyInet    ProtoFamily = '4' // SMFIA_INET
    FamilyInet6   ProtoFamily = '6' // SMFIA_INET6

type Response Uses

type Response interface {
    Response() *Message
    Continue() bool

Response represents a response structure returned by callback handlers to indicate how the milter server should proceed

type Server Uses

type Server struct {
    NewMilter func() Milter
    Actions   OptAction
    Protocol  OptProtocol
    // contains filtered or unexported fields

Server is a milter server.

func (*Server) Close Uses

func (s *Server) Close() error

func (*Server) Serve Uses

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

Serve starts the server.

type SimpleResponse Uses

type SimpleResponse byte

SimpleResponse type to define list of pre-defined responses

func (SimpleResponse) Continue Uses

func (r SimpleResponse) Continue() bool

Continue to process milter messages only if current code is Continue

func (SimpleResponse) Response Uses

func (r SimpleResponse) Response() *Message

Response returns a Message object reference

Package milter imports 13 packages (graph) and is imported by 1 packages. Updated 2020-12-03. Refresh now. Tools for package owners.