dsn

Documentation

Overview

Package dsn parses and composes Delivery Status Notification messages, see RFC 3464 and RFC 6533.

Index

• type Action
• type Message
  • func Decode(r io.Reader, utf8 bool) (*Message, error)
  • func Parse(elog *slog.Logger, r io.ReaderAt) (*Message, *message.Part, error)
  • func (m *Message) Compose(log mlog.Log, smtputf8 bool) ([]byte, error)
• type NameIP
  • func (n NameIP) IsZero() bool
• type Recipient

Types

type Action

type Action string

Action is a field in a DSN.

const (
	Failed    Action = "failed"
	Delayed   Action = "delayed"
	Delivered Action = "delivered"
	Relayed   Action = "relayed"
	Expanded  Action = "expanded"
)

type Message

type Message struct {
	SMTPUTF8 bool // Whether the original was received with smtputf8.

	// DSN message From header. E.g. postmaster@ourdomain.example. NOTE:
	// DSNs should be sent with a null reverse path to prevent mail loops.
	// ../rfc/3464:421
	From smtp.Path

	// "To" header, and also SMTP RCP TO to deliver DSN to. Should be taken
	// from original SMTP transaction MAIL FROM.
	// ../rfc/3464:415
	To smtp.Path

	// Message subject header, e.g. describing mail delivery failure.
	Subject string

	MessageID string

	// References header, with Message-ID of original message this DSN is about. So
	// mail user-agents will thread the DSN with the original message.
	References string

	// For message submitted with FUTURERELEASE SMTP extension. Value is either "for;"
	// plus original interval in seconds or "until;" plus original UTC RFC3339
	// date-time.
	FutureReleaseRequest string

	// Human-readable text explaining the failure. Line endings should be
	// bare newlines, not \r\n. They are converted to \r\n when composing.
	TextBody string

	// Per-message fields.
	OriginalEnvelopeID string
	ReportingMTA       string // Required.
	DSNGateway         string
	ReceivedFromMTA    smtp.Ehlo // Host from which message was received.
	ArrivalDate        time.Time

	// All per-message fields, including extensions. Only used for parsing,
	// not composing.
	MessageHeader textproto.MIMEHeader

	// One or more per-recipient fields.
	// ../rfc/3464:436
	Recipients []Recipient

	// Original message or headers to include in DSN as third MIME part.
	// Optional. Only used for generating DSNs, not set for parsed DNSs.
	Original []byte
}

Message represents a DSN message, with basic message headers, human-readable text, machine-parsable data, and optional original message/headers.

A DSN represents a delayed, failed or successful delivery. Failing incoming deliveries over SMTP, and failing outgoing deliveries from the message queue, can result in a DSN being sent.

func Decode

func Decode(r io.Reader, utf8 bool) (*Message, error)

Decode parses the (global) delivery-status part of a DSN.

utf8 indicates if UTF-8 is allowed for this message, if used by the media subtype of the message parts.

func Parse

func Parse(elog *slog.Logger, r io.ReaderAt) (*Message, *message.Part, error)

Parse reads a DSN message.

A DSN is a multipart internet mail message with 2 or 3 parts: human-readable text, machine-parsable text, and optional original message or headers.

The first return value is the machine-parsed DSN message. The second value is the entire MIME multipart message. Use its Parts field to access the human-readable text and optional original message/headers.

func (*Message) Compose

func (m *Message) Compose(log mlog.Log, smtputf8 bool) ([]byte, error)

Compose returns a DSN message.

smtputf8 indicates whether the remote MTA that is receiving the DSN supports smtputf8. This influences the message media (sub)types used for the DSN.

Called may want to add DKIM-Signature headers.

type NameIP

type NameIP struct {
	Name string
	IP   net.IP
}

NameIP represents a name and possibly IP, e.g. representing a connection destination.

func (NameIP) IsZero

func (n NameIP) IsZero() bool

type Recipient

type Recipient struct {
	// Required fields.
	FinalRecipient smtp.Path // Final recipient of message.
	Action         Action

	// Enhanced status code. First digit indicates permanent or temporary
	// error.
	Status string
	// For additional details, included in comment.
	StatusComment string

	// Optional fields.
	// Original intended recipient of message. Used with the DSN extensions ORCPT
	// parameter.
	// ../rfc/3464:1197
	OriginalRecipient smtp.Path

	// Remote host that returned an error code. Can also be empty for
	// deliveries.
	RemoteMTA NameIP

	// DiagnosticCodeSMTP are the full SMTP response lines, space separated. The marshaled
	// form starts with "smtp; ", this value does not.
	DiagnosticCodeSMTP string

	LastAttemptDate time.Time
	FinalLogID      string

	// For delayed deliveries, deliveries may be retried until this time.
	WillRetryUntil *time.Time

	// All fields, including extensions. Only used for parsing, not
	// composing.
	Header textproto.MIMEHeader
}

Recipient holds the per-recipient delivery-status lines in a DSN.