smtp.go

     1  // Copyright 2010 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  // Package smtp implements the Simple Mail Transfer Protocol as defined in RFC 5321.
     6  // It also implements the following extensions:
     7  //	8BITMIME  RFC 1652
     8  //	AUTH      RFC 2554
     9  //	STARTTLS  RFC 3207
    10  // Additional extensions may be handled by clients.
    11  //
    12  // The smtp package is frozen and is not accepting new features.
    13  // Some external packages provide more functionality. See:
    14  //
    15  //   https://godoc.org/?q=smtp
    16  package smtp
    17  
    18  import (
    19  	"crypto/tls"
    20  	"encoding/base64"
    21  	"errors"
    22  	"fmt"
    23  	"io"
    24  	"net"
    25  	"net/textproto"
    26  	"strings"
    27  )
    28  
    29  // A Client represents a client connection to an SMTP server.
    30  type Client struct {
    31  	// Text is the textproto.Conn used by the Client. It is exported to allow for
    32  	// clients to add extensions.
    33  	Text *textproto.Conn
    34  	// keep a reference to the connection so it can be used to create a TLS
    35  	// connection later
    36  	conn net.Conn
    37  	// whether the Client is using TLS
    38  	tls        bool
    39  	serverName string
    40  	// map of supported extensions
    41  	ext map[string]string
    42  	// supported auth mechanisms
    43  	auth       []string
    44  	localName  string // the name to use in HELO/EHLO
    45  	didHello   bool   // whether we've said HELO/EHLO
    46  	helloError error  // the error from the hello
    47  }
    48  
    49  // Dial returns a new Client connected to an SMTP server at addr.
    50  // The addr must include a port, as in "mail.example.com:smtp".
    51  func Dial(addr string) (*Client, error) {
    52  	conn, err := net.Dial("tcp", addr)
    53  	if err != nil {
    54  		return nil, err
    55  	}
    56  	host, _, _ := net.SplitHostPort(addr)
    57  	return NewClient(conn, host)
    58  }
    59  
    60  // NewClient returns a new Client using an existing connection and host as a
    61  // server name to be used when authenticating.
    62  func NewClient(conn net.Conn, host string) (*Client, error) {
    63  	text := textproto.NewConn(conn)
    64  	_, _, err := text.ReadResponse(220)
    65  	if err != nil {
    66  		text.Close()
    67  		return nil, err
    68  	}
    69  	c := &Client{Text: text, conn: conn, serverName: host, localName: "localhost"}
    70  	_, c.tls = conn.(*tls.Conn)
    71  	return c, nil
    72  }
    73  
    74  // Close closes the connection.
    75  func (c *Client) Close() error {
    76  	return c.Text.Close()
    77  }
    78  
    79  // hello runs a hello exchange if needed.
    80  func (c *Client) hello() error {
    81  	if !c.didHello {
    82  		c.didHello = true
    83  		err := c.ehlo()
    84  		if err != nil {
    85  			c.helloError = c.helo()
    86  		}
    87  	}
    88  	return c.helloError
    89  }
    90  
    91  // Hello sends a HELO or EHLO to the server as the given host name.
    92  // Calling this method is only necessary if the client needs control
    93  // over the host name used. The client will introduce itself as "localhost"
    94  // automatically otherwise. If Hello is called, it must be called before
    95  // any of the other methods.
    96  func (c *Client) Hello(localName string) error {
    97  	if err := validateLine(localName); err != nil {
    98  		return err
    99  	}
   100  	if c.didHello {
   101  		return errors.New("smtp: Hello called after other methods")
   102  	}
   103  	c.localName = localName
   104  	return c.hello()
   105  }
   106  
   107  // cmd is a convenience function that sends a command and returns the response
   108  func (c *Client) cmd(expectCode int, format string, args ...any) (int, string, error) {
   109  	id, err := c.Text.Cmd(format, args...)
   110  	if err != nil {
   111  		return 0, "", err
   112  	}
   113  	c.Text.StartResponse(id)
   114  	defer c.Text.EndResponse(id)
   115  	code, msg, err := c.Text.ReadResponse(expectCode)
   116  	return code, msg, err
   117  }
   118  
   119  // helo sends the HELO greeting to the server. It should be used only when the
   120  // server does not support ehlo.
   121  func (c *Client) helo() error {
   122  	c.ext = nil
   123  	_, _, err := c.cmd(250, "HELO %s", c.localName)
   124  	return err
   125  }
   126  
   127  // ehlo sends the EHLO (extended hello) greeting to the server. It
   128  // should be the preferred greeting for servers that support it.
   129  func (c *Client) ehlo() error {
   130  	_, msg, err := c.cmd(250, "EHLO %s", c.localName)
   131  	if err != nil {
   132  		return err
   133  	}
   134  	ext := make(map[string]string)
   135  	extList := strings.Split(msg, "\n")
   136  	if len(extList) > 1 {
   137  		extList = extList[1:]
   138  		for _, line := range extList {
   139  			k, v, _ := strings.Cut(line, " ")
   140  			ext[k] = v
   141  		}
   142  	}
   143  	if mechs, ok := ext["AUTH"]; ok {
   144  		c.auth = strings.Split(mechs, " ")
   145  	}
   146  	c.ext = ext
   147  	return err
   148  }
   149  
   150  // StartTLS sends the STARTTLS command and encrypts all further communication.
   151  // Only servers that advertise the STARTTLS extension support this function.
   152  func (c *Client) StartTLS(config *tls.Config) error {
   153  	if err := c.hello(); err != nil {
   154  		return err
   155  	}
   156  	_, _, err := c.cmd(220, "STARTTLS")
   157  	if err != nil {
   158  		return err
   159  	}
   160  	c.conn = tls.Client(c.conn, config)
   161  	c.Text = textproto.NewConn(c.conn)
   162  	c.tls = true
   163  	return c.ehlo()
   164  }
   165  
   166  // TLSConnectionState returns the client's TLS connection state.
   167  // The return values are their zero values if StartTLS did
   168  // not succeed.
   169  func (c *Client) TLSConnectionState() (state tls.ConnectionState, ok bool) {
   170  	tc, ok := c.conn.(*tls.Conn)
   171  	if !ok {
   172  		return
   173  	}
   174  	return tc.ConnectionState(), true
   175  }
   176  
   177  // Verify checks the validity of an email address on the server.
   178  // If Verify returns nil, the address is valid. A non-nil return
   179  // does not necessarily indicate an invalid address. Many servers
   180  // will not verify addresses for security reasons.
   181  func (c *Client) Verify(addr string) error {
   182  	if err := validateLine(addr); err != nil {
   183  		return err
   184  	}
   185  	if err := c.hello(); err != nil {
   186  		return err
   187  	}
   188  	_, _, err := c.cmd(250, "VRFY %s", addr)
   189  	return err
   190  }
   191  
   192  // Auth authenticates a client using the provided authentication mechanism.
   193  // A failed authentication closes the connection.
   194  // Only servers that advertise the AUTH extension support this function.
   195  func (c *Client) Auth(a Auth) error {
   196  	if err := c.hello(); err != nil {
   197  		return err
   198  	}
   199  	encoding := base64.StdEncoding
   200  	mech, resp, err := a.Start(&ServerInfo{c.serverName, c.tls, c.auth})
   201  	if err != nil {
   202  		c.Quit()
   203  		return err
   204  	}
   205  	resp64 := make([]byte, encoding.EncodedLen(len(resp)))
   206  	encoding.Encode(resp64, resp)
   207  	code, msg64, err := c.cmd(0, strings.TrimSpace(fmt.Sprintf("AUTH %s %s", mech, resp64)))
   208  	for err == nil {
   209  		var msg []byte
   210  		switch code {
   211  		case 334:
   212  			msg, err = encoding.DecodeString(msg64)
   213  		case 235:
   214  			// the last message isn't base64 because it isn't a challenge
   215  			msg = []byte(msg64)
   216  		default:
   217  			err = &textproto.Error{Code: code, Msg: msg64}
   218  		}
   219  		if err == nil {
   220  			resp, err = a.Next(msg, code == 334)
   221  		}
   222  		if err != nil {
   223  			// abort the AUTH
   224  			c.cmd(501, "*")
   225  			c.Quit()
   226  			break
   227  		}
   228  		if resp == nil {
   229  			break
   230  		}
   231  		resp64 = make([]byte, encoding.EncodedLen(len(resp)))
   232  		encoding.Encode(resp64, resp)
   233  		code, msg64, err = c.cmd(0, string(resp64))
   234  	}
   235  	return err
   236  }
   237  
   238  // Mail issues a MAIL command to the server using the provided email address.
   239  // If the server supports the 8BITMIME extension, Mail adds the BODY=8BITMIME
   240  // parameter. If the server supports the SMTPUTF8 extension, Mail adds the
   241  // SMTPUTF8 parameter.
   242  // This initiates a mail transaction and is followed by one or more Rcpt calls.
   243  func (c *Client) Mail(from string) error {
   244  	if err := validateLine(from); err != nil {
   245  		return err
   246  	}
   247  	if err := c.hello(); err != nil {
   248  		return err
   249  	}
   250  	cmdStr := "MAIL FROM:<%s>"
   251  	if c.ext != nil {
   252  		if _, ok := c.ext["8BITMIME"]; ok {
   253  			cmdStr += " BODY=8BITMIME"
   254  		}
   255  		if _, ok := c.ext["SMTPUTF8"]; ok {
   256  			cmdStr += " SMTPUTF8"
   257  		}
   258  	}
   259  	_, _, err := c.cmd(250, cmdStr, from)
   260  	return err
   261  }
   262  
   263  // Rcpt issues a RCPT command to the server using the provided email address.
   264  // A call to Rcpt must be preceded by a call to Mail and may be followed by
   265  // a Data call or another Rcpt call.
   266  func (c *Client) Rcpt(to string) error {
   267  	if err := validateLine(to); err != nil {
   268  		return err
   269  	}
   270  	_, _, err := c.cmd(25, "RCPT TO:<%s>", to)
   271  	return err
   272  }
   273  
   274  type dataCloser struct {
   275  	c *Client
   276  	io.WriteCloser
   277  }
   278  
   279  func (d *dataCloser) Close() error {
   280  	d.WriteCloser.Close()
   281  	_, _, err := d.c.Text.ReadResponse(250)
   282  	return err
   283  }
   284  
   285  // Data issues a DATA command to the server and returns a writer that
   286  // can be used to write the mail headers and body. The caller should
   287  // close the writer before calling any more methods on c. A call to
   288  // Data must be preceded by one or more calls to Rcpt.
   289  func (c *Client) Data() (io.WriteCloser, error) {
   290  	_, _, err := c.cmd(354, "DATA")
   291  	if err != nil {
   292  		return nil, err
   293  	}
   294  	return &dataCloser{c, c.Text.DotWriter()}, nil
   295  }
   296  
   297  var testHookStartTLS func(*tls.Config) // nil, except for tests
   298  
   299  // SendMail connects to the server at addr, switches to TLS if
   300  // possible, authenticates with the optional mechanism a if possible,
   301  // and then sends an email from address from, to addresses to, with
   302  // message msg.
   303  // The addr must include a port, as in "mail.example.com:smtp".
   304  //
   305  // The addresses in the to parameter are the SMTP RCPT addresses.
   306  //
   307  // The msg parameter should be an RFC 822-style email with headers
   308  // first, a blank line, and then the message body. The lines of msg
   309  // should be CRLF terminated. The msg headers should usually include
   310  // fields such as "From", "To", "Subject", and "Cc".  Sending "Bcc"
   311  // messages is accomplished by including an email address in the to
   312  // parameter but not including it in the msg headers.
   313  //
   314  // The SendMail function and the net/smtp package are low-level
   315  // mechanisms and provide no support for DKIM signing, MIME
   316  // attachments (see the mime/multipart package), or other mail
   317  // functionality. Higher-level packages exist outside of the standard
   318  // library.
   319  func SendMail(addr string, a Auth, from string, to []string, msg []byte) error {
   320  	if err := validateLine(from); err != nil {
   321  		return err
   322  	}
   323  	for _, recp := range to {
   324  		if err := validateLine(recp); err != nil {
   325  			return err
   326  		}
   327  	}
   328  	c, err := Dial(addr)
   329  	if err != nil {
   330  		return err
   331  	}
   332  	defer c.Close()
   333  	if err = c.hello(); err != nil {
   334  		return err
   335  	}
   336  	if ok, _ := c.Extension("STARTTLS"); ok {
   337  		config := &tls.Config{ServerName: c.serverName}
   338  		if testHookStartTLS != nil {
   339  			testHookStartTLS(config)
   340  		}
   341  		if err = c.StartTLS(config); err != nil {
   342  			return err
   343  		}
   344  	}
   345  	if a != nil && c.ext != nil {
   346  		if _, ok := c.ext["AUTH"]; !ok {
   347  			return errors.New("smtp: server doesn't support AUTH")
   348  		}
   349  		if err = c.Auth(a); err != nil {
   350  			return err
   351  		}
   352  	}
   353  	if err = c.Mail(from); err != nil {
   354  		return err
   355  	}
   356  	for _, addr := range to {
   357  		if err = c.Rcpt(addr); err != nil {
   358  			return err
   359  		}
   360  	}
   361  	w, err := c.Data()
   362  	if err != nil {
   363  		return err
   364  	}
   365  	_, err = w.Write(msg)
   366  	if err != nil {
   367  		return err
   368  	}
   369  	err = w.Close()
   370  	if err != nil {
   371  		return err
   372  	}
   373  	return c.Quit()
   374  }
   375  
   376  // Extension reports whether an extension is support by the server.
   377  // The extension name is case-insensitive. If the extension is supported,
   378  // Extension also returns a string that contains any parameters the
   379  // server specifies for the extension.
   380  func (c *Client) Extension(ext string) (bool, string) {
   381  	if err := c.hello(); err != nil {
   382  		return false, ""
   383  	}
   384  	if c.ext == nil {
   385  		return false, ""
   386  	}
   387  	ext = strings.ToUpper(ext)
   388  	param, ok := c.ext[ext]
   389  	return ok, param
   390  }
   391  
   392  // Reset sends the RSET command to the server, aborting the current mail
   393  // transaction.
   394  func (c *Client) Reset() error {
   395  	if err := c.hello(); err != nil {
   396  		return err
   397  	}
   398  	_, _, err := c.cmd(250, "RSET")
   399  	return err
   400  }
   401  
   402  // Noop sends the NOOP command to the server. It does nothing but check
   403  // that the connection to the server is okay.
   404  func (c *Client) Noop() error {
   405  	if err := c.hello(); err != nil {
   406  		return err
   407  	}
   408  	_, _, err := c.cmd(250, "NOOP")
   409  	return err
   410  }
   411  
   412  // Quit sends the QUIT command and closes the connection to the server.
   413  func (c *Client) Quit() error {
   414  	if err := c.hello(); err != nil {
   415  		return err
   416  	}
   417  	_, _, err := c.cmd(221, "QUIT")
   418  	if err != nil {
   419  		return err
   420  	}
   421  	return c.Text.Close()
   422  }
   423  
   424  // validateLine checks to see if a line has CR or LF as per RFC 5321
   425  func validateLine(line string) error {
   426  	if strings.ContainsAny(line, "\n\r") {
   427  		return errors.New("smtp: A line must not contain CR or LF")
   428  	}
   429  	return nil
   430  }
   431
View as plain text