Overview

Package smtp implements the Simple Mail Transfer Protocol as defined in RFC

  1. It also implements the following extensions:

    8BITMIME RFC 1652
    AUTH RFC 2554
    STARTTLS RFC 3207

Additional extensions may be handled by clients.

The smtp package is frozen and is not accepting new features. Some external
packages provide more functionality. See:


Example:

  1. // Connect to the remote SMTP server.
  2. c, err := smtp.Dial("mail.example.com:25")
  3. if err != nil {
  4.     log.Fatal(err)
  5. }
  7. // Set the sender and recipient first
  8. if err := c.Mail("sender@example.org"); err != nil {
  9.     log.Fatal(err)
  10. }
  11. if err := c.Rcpt("recipient@example.net"); err != nil {
  12.     log.Fatal(err)
  13. }
  15. // Send the email body.
  16. wc, err := c.Data()
  17. if err != nil {
  19. }
  20. _, err = fmt.Fprintf(wc, "This is the email body")
  21. if err != nil {
  22.     log.Fatal(err)
  23. }
  24. err = wc.Close()
  25. if err != nil {
  26.     log.Fatal(err)
  27. }
  29. // Send the QUIT command and close the connection.
  30. err = c.Quit()
  31. if err != nil {
  32.     log.Fatal(err)
  33. }

Package files

smtp.go

func 

  1. func SendMail(addr , a Auth, from , to []string, msg []) 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:

  1. // Set up authentication information.
  2. auth := smtp.PlainAuth("", "user@example.com", "password", "mail.example.com")
  4. // Connect to the server, authenticate, set the sender and recipient,
  5. // and send the email all in one step.
  6. to := []string{"recipient@example.net"}
  7. msg := []byte("To: recipient@example.net\r\n" +
  8.     "Subject: discount Gophers!\r\n" +
  9.     "\r\n" +
  10.     "This is the email body.\r\n")
  11. err := smtp.SendMail("mail.example.com:25", auth, "sender@example.org", to, msg)
  12. if err != nil {
  13.     log.Fatal(err)
  14. }

  1. type Auth interface {
  2.     // Start begins an authentication with a server.
  3.     // and optionally data to include in the initial AUTH message
  4.     // sent to the server. It can return proto == "" to indicate
  5.     // that the authentication should be skipped.
  6.     // If it returns a non-nil error, the SMTP client aborts
  7.     // the authentication attempt and closes the connection.
  8.     Start(server *ServerInfo) (proto , toServer []byte, err )
  9.  
  10.     // Next continues the authentication. The server has just sent
  11.     // the fromServer data. If more is true, the server expects a
  12.     // response, which Next should return as toServer; otherwise
  13.     // Next should return toServer == nil.
  14.     // If Next returns a non-nil error, the SMTP client aborts
  15.     // the authentication attempt and closes the connection.
  16.     Next(fromServer []byte, more ) (toServer []byte, err )
  17. }

Auth is implemented by an SMTP authentication mechanism.

func CRAMMD5Auth

  1. func CRAMMD5Auth(username, secret string)

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 PlainAuth

  1. func PlainAuth(identity, username, password, host string)

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.

  1. // hostname is used by PlainAuth to validate the TLS certificate.
  2. hostname := "mail.example.com"
  3. auth := smtp.PlainAuth("", "user@example.com", "password", hostname)
  5. err := smtp.SendMail(hostname+":25", auth, from, recipients, msg)
  6. if err != nil {
  8. }

type Client

A Client represents a client connection to an SMTP server.

func Dial

  1. func Dial(addr string) (*, 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 

  1. func NewClient(conn .Conn, host ) (*Client, )

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

  1. func (c *Client) Auth(a ) 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) 

  1. func (c *) Close() error

Close closes the connection.

func (*Client) 

  1. func (c *) Data() (io., 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 Rcpt.

func (*Client) 

  1. func (c *) Extension(ext string) (, 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) 

  1. func (c *) Hello(localName string)

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

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. This initiates a mail transaction and is followed by one or more Rcpt
calls.

  1. func (c *Client) Noop()

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

func (*Client) Quit

  1. func (c *Client) Quit()

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

func (*Client) Rcpt

  1. func (c *Client) Rcpt(to ) 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 Mail and may be followed by a Data
call or another Rcpt call.

func (*Client) 

  1. func (c *) Reset() error

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

func (*Client) 

  1. func (c *) StartTLS(config *tls.) error

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

func (*Client) 

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

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

  1. func (c *) Verify(addr string)

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.

ServerInfo records information about an SMTP server.