smtp

package
v0.5.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 6, 2024 License: MIT, BSD-3-Clause Imports: 22 Imported by: 1

Documentation

Overview

Package smtp implements the Simple Mail Transfer Protocol as defined in RFC 5321. It also implements the following extensions: 

8BITMIME  RFC 1652
AUTH      RFC 2554
STARTTLS  RFC 3207
DSN       RFC 1891
Example 
package main

import (
	"fmt"
	"log"

	"github.com/wneessen/go-mail/smtp"
)

func main() {
	// Connect to the remote SMTP server.
	c, err := smtp.Dial("mail.example.com:25")
	if err != nil {
		log.Fatal(err)
	}

	// Set the sender and recipient first
	if err := c.Mail("sender@example.org"); err != nil {
		log.Fatal(err)
	}
	if err := c.Rcpt("recipient@example.net"); err != nil {
		log.Fatal(err)
	}

	// Send the email body.
	wc, err := c.Data()
	if err != nil {
		log.Fatal(err)
	}
	_, err = fmt.Fprintf(wc, "This is the email body")
	if err != nil {
		log.Fatal(err)
	}
	err = wc.Close()
	if err != nil {
		log.Fatal(err)
	}

	// Send the QUIT command and close the connection.
	err = c.Quit()
	if err != nil {
		log.Fatal(err)
	}
}

Output:

Index

Examples

Constants

This section is empty.

Variables

View Source 
var (
	// ErrUnencrypted is an error indicating that the connection is not encrypted.
	ErrUnencrypted = errors.New("unencrypted connection")
	// ErrUnexpectedServerChallange is an error indicating that the server issued an unexpected challenge.
	ErrUnexpectedServerChallange = errors.New("unexpected server challenge")
	// ErrUnexpectedServerResponse is an error indicating that the server issued an unexpected response.
	ErrUnexpectedServerResponse = errors.New("unexpected server response")
	// ErrWrongHostname is an error indicating that the provided hostname does not match the expected value.
	ErrWrongHostname = errors.New("wrong host name")
)
View Source 
var (

	// ErrNonTLSConnection is returned when an attempt is made to retrieve TLS state on a non-TLS connection.
	ErrNonTLSConnection = errors.New("connection is not using TLS")

	// ErrNoConnection is returned when attempting to perform an operation that requires an established
	// connection but none exists.
	ErrNoConnection = errors.New("connection is not established")
)

Functions

func SendMail 

func SendMail(addr string, a Auth, from string, to []string, msg []byte) error

SendMail connects to the server at addr, switches to TLS if possible, authenticates with the optional mechanism a if possible, and then sends an email from address from, to addresses to, with message msg. The addr must include a port, as in "mail.example.com:smtp".

The addresses in the to parameter are the SMTP RCPT addresses.

The msg parameter should be an RFC 822-style email with headers first, a blank line, and then the message body. The lines of msg should be CRLF terminated. The msg headers should usually include fields such as "From", "To", "Subject", and "Cc". Sending "Bcc" messages is accomplished by including an email address in the to parameter but not including it in the msg headers.

The SendMail function and the net/smtp package are low-level mechanisms and provide no support for DKIM signing, MIME attachments (see the mime/multipart package), or other mail functionality. Higher-level packages exist outside of the standard library.

Example 
package main

import (
	"log"

	"github.com/wneessen/go-mail/smtp"
)

func main() {
	// Set up authentication information.
	auth := smtp.PlainAuth("", "user@example.com", "password", "mail.example.com", false)

	// Connect to the server, authenticate, set the sender and recipient,
	// and send the email all in one step.
	to := []string{"recipient@example.net"}
	msg := []byte("To: recipient@example.net\r\n" +
		"Subject: discount Gophers!\r\n" +
		"\r\n" +
		"This is the email body.\r\n")
	err := smtp.SendMail("mail.example.com:25", auth, "sender@example.org", to, msg)
	if err != nil {
		log.Fatal(err)
	}
}

Output:

Types

type Auth 

type Auth interface {
	// Start begins an authentication with a server.
	// It returns the name of the authentication protocol
	// and optionally data to include in the initial AUTH message
	// sent to the server.
	// If it returns a non-nil error, the SMTP client aborts
	// the authentication attempt and closes the connection.
	Start(server *ServerInfo) (proto string, toServer []byte, err error)

	// Next continues the authentication. The server has just sent
	// the fromServer data. If more is true, the server expects a
	// response, which Next should return as toServer; otherwise
	// Next should return toServer == nil.
	// If Next returns a non-nil error, the SMTP client aborts
	// the authentication attempt and closes the connection.
	Next(fromServer []byte, more bool) (toServer []byte, err error)
}

Auth is implemented by an SMTP authentication mechanism.

func CRAMMD5Auth 

func CRAMMD5Auth(username, secret string) Auth

CRAMMD5Auth returns an Auth that implements the CRAM-MD5 authentication mechanism as defined in RFC 2195. The returned Auth uses the given username and secret to authenticate to the server using the challenge-response mechanism.

func LoginAuth 

func LoginAuth(username, password, host string, allowUnEnc bool) Auth

LoginAuth returns an Auth that implements the LOGIN authentication mechanism as it is used by MS Outlook. The Auth works similar to PLAIN but instead of sending all in one response, the login is handled within 3 steps: - Sending AUTH LOGIN (server might responds with "Username:") - Sending the username (server might responds with "Password:") - Sending the password (server authenticates) This is the common approach as specified by Microsoft in their MS-XLOGIN spec. See: https://msopenspecs.azureedge.net/files/MS-XLOGIN/%5bMS-XLOGIN%5d.pdf Yet, there is also an old IETF draft for SMTP AUTH LOGIN that states for clients: "The contents of both challenges SHOULD be ignored.". See: https://datatracker.ietf.org/doc/html/draft-murchison-sasl-login-00 Since there is no official standard RFC and we've seen different implementations of this mechanism (sending "Username:", "Username", "username", "User name", etc.) we follow the IETF-Draft and ignore any server challenge to allow compatibility with most mail servers/providers.

LoginAuth will only send the credentials if the connection is using TLS or is connected to localhost. Otherwise authentication will fail with an error, without sending the credentials.

func PlainAuth 

func PlainAuth(identity, username, password, host string, allowUnEnc bool) Auth

PlainAuth returns an Auth that implements the PLAIN authentication mechanism as defined in RFC 4616. The returned Auth uses the given username and password to authenticate to host and act as identity. Usually identity should be the empty string, to act as username.

PlainAuth will only send the credentials if the connection is using TLS or is connected to localhost. Otherwise authentication will fail with an error, without sending the credentials.

Example 
package main

import (
	"log"

	"github.com/wneessen/go-mail/smtp"
)

// variables to make ExamplePlainAuth compile, without adding
// unnecessary noise there.
var (
	from       = "gopher@example.net"
	msg        = []byte("dummy message")
	recipients = []string{"foo@example.com"}
)

func main() {
	// hostname is used by PlainAuth to validate the TLS certificate.
	hostname := "mail.example.com"
	auth := smtp.PlainAuth("", "user@example.com", "password", hostname, false)

	err := smtp.SendMail(hostname+":25", auth, from, recipients, msg)
	if err != nil {
		log.Fatal(err)
	}
}

Output:

func ScramSHA1Auth added in v0.5.0 

func ScramSHA1Auth(username, password string) Auth

ScramSHA1Auth creates and returns a new SCRAM-SHA-1 authentication mechanism with the given username and password.

func ScramSHA1PlusAuth added in v0.5.0 

func ScramSHA1PlusAuth(username, password string, tlsConnState *tls.ConnectionState) Auth

ScramSHA1PlusAuth returns an Auth instance configured for SCRAM-SHA-1-PLUS authentication with the provided username, password, and TLS connection state.

func ScramSHA256Auth added in v0.5.0 

func ScramSHA256Auth(username, password string) Auth

ScramSHA256Auth creates and returns a new SCRAM-SHA-256 authentication mechanism with the given username and password.

func ScramSHA256PlusAuth added in v0.5.0 

func ScramSHA256PlusAuth(username, password string, tlsConnState *tls.ConnectionState) Auth

ScramSHA256PlusAuth returns an Auth instance configured for SCRAM-SHA-256-PLUS authentication with the provided username, password, and TLS connection state.

func XOAuth2Auth added in v0.4.0 

func XOAuth2Auth(username, token string) Auth

XOAuth2Auth returns an Auth that implements the XOAuth2 authentication mechanism as defined in the following specs:

https://developers.google.com/gmail/imap/xoauth2-protocol https://learn.microsoft.com/en-us/exchange/client-developer/legacy-protocols/how-to-authenticate-an-imap-pop-smtp-application-by-using-oauth

type Client 

type Client struct {
	// Text is the textproto.Conn used by the Client. It is exported to allow for clients to add extensions.
	Text *textproto.Conn
	// contains filtered or unexported fields
}

A Client represents a client connection to an SMTP server.

func Dial 

func Dial(addr string) (*Client, error)

Dial returns a new Client connected to an SMTP server at addr. The addr must include a port, as in "mail.example.com:smtp".

func NewClient 

func NewClient(conn net.Conn, host string) (*Client, error)

NewClient returns a new Client using an existing connection and host as a server name to be used when authenticating.

func (*Client) Auth 

func (c *Client) Auth(a Auth) error

Auth authenticates a client using the provided authentication mechanism. A failed authentication closes the connection. Only servers that advertise the AUTH extension support this function.

func (*Client) Close 

func (c *Client) Close() error

Close closes the connection.

func (*Client) Data 

func (c *Client) Data() (io.WriteCloser, error)

Data issues a DATA command to the server and returns a writer that can be used to write the mail headers and body. The caller should close the writer before calling any more methods on c. A call to Data must be preceded by one or more calls to Client.Rcpt.

func (*Client) Extension 

func (c *Client) Extension(ext string) (bool, string)

Extension reports whether an extension is support by the server. The extension name is case-insensitive. If the extension is supported, Extension also returns a string that contains any parameters the server specifies for the extension.

func (*Client) GetTLSConnectionState added in v0.5.0 

func (c *Client) GetTLSConnectionState() (*tls.ConnectionState, error)

GetTLSConnectionState retrieves the TLS connection state of the client's current connection. Returns an error if the connection is not using TLS or if the connection is not established.

func (*Client) HasConnection added in v0.5.0 

func (c *Client) HasConnection() bool

HasConnection checks if the client has an active connection. Returns true if the `conn` field is not nil, indicating an active connection.

func (*Client) Hello 

func (c *Client) Hello(localName string) error

Hello sends a HELO or EHLO to the server as the given host name. Calling this method is only necessary if the client needs control over the host name used. The client will introduce itself as "localhost" automatically otherwise. If Hello is called, it must be called before any of the other methods.

func (*Client) Mail 

func (c *Client) Mail(from string) error

Mail issues a MAIL command to the server using the provided email address. If the server supports the 8BITMIME extension, Mail adds the BODY=8BITMIME parameter. If the server supports the SMTPUTF8 extension, Mail adds the SMTPUTF8 parameter. This initiates a mail transaction and is followed by one or more Client.Rcpt calls.

func (*Client) Noop 

func (c *Client) Noop() error

Noop sends the NOOP command to the server. It does nothing but check that the connection to the server is okay.

func (*Client) Quit 

func (c *Client) Quit() error

Quit sends the QUIT command and closes the connection to the server.

func (*Client) Rcpt 

func (c *Client) Rcpt(to string) error

Rcpt issues a RCPT command to the server using the provided email address. A call to Rcpt must be preceded by a call to Client.Mail and may be followed by a Client.Data call or another Rcpt call.

func (*Client) Reset 

func (c *Client) Reset() error

Reset sends the RSET command to the server, aborting the current mail transaction.

func (*Client) SetDSNMailReturnOption 

func (c *Client) SetDSNMailReturnOption(d string)

SetDSNMailReturnOption sets the DSN mail return option for the Mail method

func (*Client) SetDSNRcptNotifyOption 

func (c *Client) SetDSNRcptNotifyOption(d string)

SetDSNRcptNotifyOption sets the DSN recipient notify option for the Mail method

func (*Client) SetDebugLog 

func (c *Client) SetDebugLog(v bool)

SetDebugLog enables the debug logging for incoming and outgoing SMTP messages

func (*Client) SetLogAuthData added in v0.5.1 

func (c *Client) SetLogAuthData()

SetLogAuthData enables logging of authentication data in the Client.

func (*Client) SetLogger 

func (c *Client) SetLogger(l log.Logger)

SetLogger overrides the default log.Stdlog for the debug logging with a logger that satisfies the log.Logger interface

func (*Client) StartTLS 

func (c *Client) StartTLS(config *tls.Config) error

StartTLS sends the STARTTLS command and encrypts all further communication. Only servers that advertise the STARTTLS extension support this function.

func (*Client) TLSConnectionState 

func (c *Client) TLSConnectionState() (state tls.ConnectionState, ok bool)

TLSConnectionState returns the client's TLS connection state. The return values are their zero values if Client.StartTLS did not succeed.

func (*Client) UpdateDeadline added in v0.5.0 

func (c *Client) UpdateDeadline(timeout time.Duration) error

UpdateDeadline sets a new deadline on the SMTP connection with the specified timeout duration.

func (*Client) Verify 

func (c *Client) Verify(addr string) error

Verify checks the validity of an email address on the server. If Verify returns nil, the address is valid. A non-nil return does not necessarily indicate an invalid address. Many servers will not verify addresses for security reasons.

type ServerInfo 

type ServerInfo struct {
	Name string   // SMTP server name
	TLS  bool     // using TLS, with valid certificate for Name
	Auth []string // advertised authentication mechanisms
}

ServerInfo records information about an SMTP server.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.