net/smtp: document SendMail more

Fixes #9776

Change-Id: I53741fd970244bbfa6874adcb4f1e3d0e7de386b
Reviewed-on: https://go-review.googlesource.com/4162
Reviewed-by: Andrew Gerrand <adg@golang.org>

diff --git a/src/net/smtp/example_test.go b/src/net/smtp/example_test.go
index d551e365a932a6a144bbfc450a259a341844b7bd..16419f42761438626b8dbd051a7c35195dcc68be 100644 (file)
--- a/src/net/smtp/example_test.go
+++ b/src/net/smtp/example_test.go
@@ -46,14 +46,36 @@ func Example() {
        }
 }
 
+// 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 ExamplePlainAuth() {
+       // hostname is used by PlainAuth to validate the TLS certificate.
+       hostname := "mail.example.com"
+       auth := smtp.PlainAuth("", "user@example.com", "password", hostname)
+
+       err := smtp.SendMail(hostname+":25", auth, from, recipients, msg)
+       if err != nil {
+               log.Fatal(err)
+       }
+}
+
+func ExampleSendMail() {
        // Set up authentication information.
        auth := smtp.PlainAuth("", "user@example.com", "password", "mail.example.com")
 
        // 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("This is the email body.")
+       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)

diff --git a/src/net/smtp/smtp.go b/src/net/smtp/smtp.go
index c9b3c07aa8c50fc2b2fea73196fca239c7c846db..81f3c0bd62ab0e5d160620c7ba6c86fb1300e133 100644 (file)
--- a/src/net/smtp/smtp.go
+++ b/src/net/smtp/smtp.go
@@ -264,9 +264,9 @@ func (d *dataCloser) Close() error {
 }
 
 // Data issues a DATA command to the server and returns a writer that
-// can be used to write the data. 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.
+// 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 (c *Client) Data() (io.WriteCloser, error) {
        _, _, err := c.cmd(354, "DATA")
        if err != nil {
@@ -281,6 +281,21 @@ var testHookStartTLS func(*tls.Config) // nil, except for tests
 // possible, authenticates with the optional mechanism a if possible,
 // and then sends an email from address from, to addresses to, with
 // message msg.
+//
+// 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 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.
 func SendMail(addr string, a Auth, from string, to []string, msg []byte) error {
        c, err := Dial(addr)
        if err != nil {