go-smtp

go-smtp is an ESMTP client and server library written in Go. It implements [RFC 5321] and provides support for several SMTP extensions and protocols, including:

• AUTH (RFC 4954)
• PIPELINING (RFC 2920)
• UTF-8 support for subjects and messages
• LMTP (Local Mail Transfer Protocol, RFC 2033)

The EnhancedCode type is a [3]int used for RFC 6411 enhanced status codes. The library provides two special constants for managing these codes:

• NoEnhancedCode: {-1, -1, -1}. Use this when you want to explicitly indicate that an enhanced code should not be included in a response. Note that RFC 2034 generally requires enhanced codes for 2xx, 4xx, and 5xx responses.
• EnhancedCodeNotSet: {0, 0, 0}. Use this when a backend failed to provide an enhanced status code. In such cases, the server will typically use X.0.0 (where X is derived from the primary error code).

If you need fine-grained control over the SMTP transaction (e.g., custom MAIL options, specific RCPT parameters, or manual DATA handling), use the Client type instead of the package-level SendMail functions.

A typical manual transaction follows this sequence:

1. Mail(from string, opts *MailOptions)
2. One or more Rcpt(to string, opts *RcptOptions) calls.
3. Data() to get a DataCommand writer.
4. Close() the DataCommand writer to finish the transmission.

The smtp package provides several ways to establish a connection to an SMTP server depending on the required security level:

• Plaintext: Use Dial(addr) to connect via a standard TCP connection. This does not enable TLS.
• Implicit TLS: Use DialTLS(addr, tlsConfig) to connect to a server that expects TLS from the start (e.g., SMTPS on port 465).
• STARTTLS: Use DialStartTLS(addr, tlsConfig) to connect via plaintext and then upgrade the connection to TLS using the STARTTLS command.

All addr strings must include a port (e.g., mail.example.com:smtp). A nil tlsConfig is treated as an empty tls.Config.

The Client struct provides fields to control network behavior:

• CommandTimeout: The duration to wait for command responses (default is 5 minutes). This includes the 3xx reply to the DATA command.
• SubmissionTimeout: The duration to wait for responses after the final dot in a DATA command (default is 12 minutes).
• DebugWriter: An io.Writer used to log all network activity. Setting this allows you to inspect the raw SMTP traffic.

For simple use cases, use the package-level SendMail or SendMailTLS functions. These functions handle the entire lifecycle: connecting, upgrading to TLS, authenticating (if a SASL client is provided), and sending the message.

Note: The r parameter must be an RFC 822-style email containing headers first, followed by a blank line, and then the message body. All lines must be CRLF terminated. This package does not handle DKIM signing or MIME multipart construction.

For Local Mail Transfer Protocol (LMTP) servers, implement the LMTPSession interface. This extends the standard Session with recipient-specific status reporting.

• LMTPData(r io.Reader, status StatusCollector) error: The LMTP-specific version of the Data method. It uses a StatusCollector to provide per-recipient status information. The backend should call SetStatus once for each AddRcpt call. The return value of LMTPData serves as the status for recipients that did not receive an explicit status via the collector.

type LMTPSession interface {
	Session
	LMTPData(r io.Reader, status StatusCollector) error
}

type StatusCollector interface {
	SetStatus(rcptTo string, err error)
}

Use Client.Extension(ext string) to check if the server supports a specific SMTP extension (e.g., AUTH, STARTTLS, SIZE, 8BITMIME). The method returns a boolean indicating support and a string containing any parameters associated with that extension.

Additionally, use Client.SupportsAuth(mech string) to specifically check if a particular SASL mechanism is supported by the server.