package smtp · Go 標準庫中文參考

# package smtp `import "net/smtp"` smtp包實現了簡單郵件傳輸協議（SMTP），參見[RFC 5321](http://tools.ietf.org/html/rfc5321)。同時本包還實現了如下擴展： ``` 8BITMIME RFC 1652 AUTH RFC 2554 STARTTLS RFC 3207 ``` 客戶端可以自行管理其他的擴展。 Example ``` // 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) } ``` ## Index * [type ServerInfo](#ServerInfo) * [type Auth](#Auth) * [func CRAMMD5Auth(username, secret string) Auth](#CRAMMD5Auth) * [func PlainAuth(identity, username, password, host string) Auth](#PlainAuth) * [type Client](#Client) * [func Dial(addr string) (\*Client, error)](#Dial) * [func NewClient(conn net.Conn, host string) (\*Client, error)](#NewClient) * [func (c \*Client) Extension(ext string) (bool, string)](#Client.Extension) * [func (c \*Client) Hello(localName string) error](#Client.Hello) * [func (c \*Client) Auth(a Auth) error](#Client.Auth) * [func (c \*Client) Verify(addr string) error](#Client.Verify) * [func (c \*Client) StartTLS(config \*tls.Config) error](#Client.StartTLS) * [func (c \*Client) Mail(from string) error](#Client.Mail) * [func (c \*Client) Rcpt(to string) error](#Client.Rcpt) * [func (c \*Client) Data() (io.WriteCloser, error)](#Client.Data) * [func (c \*Client) Reset() error](#Client.Reset) * [func (c \*Client) Quit() error](#Client.Quit) * [func (c \*Client) Close() error](#Client.Close) * [func SendMail(addr string, a Auth, from string, to []string, msg []byte) error](#SendMail) ### Examples * [PlainAuth](#example-PlainAuth) * [package](#example-package) ## type [ServerInfo](https://github.com/golang/go/blob/master/src/net/smtp/auth.go#L35 "View Source") ``` type ServerInfo struct { Name string // SMTP服務器的名字 TLS bool // Name有合法的證書并使用TLS時為真 Auth []string // 支持的認證機制 } ``` ServerInfo類型記錄一個SMTP服務器的信息。 ## type [Auth](https://github.com/golang/go/blob/master/src/net/smtp/auth.go#L15 "View Source") ``` type Auth interface { // 方法開始和服務端的認證。 // 它返回認證協議的名字和可能有的應發送給服務端的包含初始認證信息的數據。 // 如果返回值proto == ""，表示應跳過認證； // 如果返回一個非nil的錯誤，SMTP客戶端應中斷認證身份的嘗試并關閉連接。 Start(server *ServerInfo) (proto string, toServer []byte, err error) // 方法繼續認證過程。fromServer為服務端剛發送的數據。 // 如果more為真，服務端會期望一個回復，回復內容應被Next返回，即toServer； // 否則返回值toServer應為nil。 // 如果返回一個非nil的錯誤，SMTP客戶端應中斷認證身份的嘗試并關閉連接。 Next(fromServer []byte, more bool) (toServer []byte, err error) } ``` Auth接口應被每一個SMTP認證機制實現。 ### func [CRAMMD5Auth](https://github.com/golang/go/blob/master/src/net/smtp/auth.go#L91 "View Source") ``` func CRAMMD5Auth(username, secret string) Auth ``` 返回一個實現了CRAM-MD5身份認證機制（參見[RFC 2195](http://tools.ietf.org/html/rfc2195)）的Auth接口。返回的接口使用給出的用戶名和密碼，采用響應——回答機制與服務端進行身份認證。 ### func [PlainAuth](https://github.com/golang/go/blob/master/src/net/smtp/auth.go#L51 "View Source") ``` func PlainAuth(identity, username, password, host string) Auth ``` 返回一個實現了PLAIN身份認證機制（參見[RFC 4616](http://tools.ietf.org/html/rfc4616)）的Auth接口。返回的接口使用給出的用戶名和密碼，通過TLS連接到主機認證，采用identity為身份管理和行動（通常應設identity為""，以便使用username為身份）。 Example ``` // 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.") err := smtp.SendMail("mail.example.com:25", auth, "sender@example.org", to, msg) if err != nil { log.Fatal(err) } ``` ## type [Client](https://github.com/golang/go/blob/master/src/net/smtp/smtp.go#L24 "View Source") ``` type Client struct { // 代表被Client使用的textproto.Conn，它可以導出，以便使用者添加擴展。 Text *textproto.Conn // 內含隱藏或非導出字段 } ``` Client代表一個連接到SMTP服務器的客戶端。 ### func [Dial](https://github.com/golang/go/blob/master/src/net/smtp/smtp.go#L45 "View Source") ``` func Dial(addr string) (*Client, error) ``` Dial返回一個連接到地址為addr的SMTP服務器的\*Client；addr必須包含端口號。 ### func [NewClient](https://github.com/golang/go/blob/master/src/net/smtp/smtp.go#L56 "View Source") ``` func NewClient(conn net.Conn, host string) (*Client, error) ``` NewClient使用已經存在的連接conn和作為服務器名的host（用于身份認證）來創建一個\*Client。 ### func (\*Client) [Extension](https://github.com/golang/go/blob/master/src/net/smtp/smtp.go#L325 "View Source") ``` func (c *Client) Extension(ext string) (bool, string) ``` Extension返回服務端是否支持某個擴展，擴展名是大小寫不敏感的。如果擴展被支持，方法還會返回一個包含指定給該擴展的各個參數的字符串。 ### func (\*Client) [Hello](https://github.com/golang/go/blob/master/src/net/smtp/smtp.go#L89 "View Source") ``` func (c *Client) Hello(localName string) error ``` Hello發送給服務端一個HELO或EHLO命令。本方法只有使用者需要控制使用的本地主機名時才應使用，否則程序會將本地主機名設為“localhost”，Hello方法只能在最開始調用。 ### func (\*Client) [Auth](https://github.com/golang/go/blob/master/src/net/smtp/smtp.go#L175 "View Source") ``` func (c *Client) Auth(a Auth) error ``` Auth使用提供的認證機制進行認證。失敗的認證會關閉該連接。只有服務端支持AUTH時，本方法才有效。（但是不支持時，調用會默默的成功） ### func (\*Client) [Verify](https://github.com/golang/go/blob/master/src/net/smtp/smtp.go#L164 "View Source") ``` func (c *Client) Verify(addr string) error ``` Verify檢查一個郵箱地址在其服務器是否合法，如果合法會返回nil；但非nil的返回值并不代表不合法，因為許多服務器出于安全原因不支持這種查詢。 ### func (\*Client) [StartTLS](https://github.com/golang/go/blob/master/src/net/smtp/smtp.go#L146 "View Source") ``` func (c *Client) StartTLS(config *tls.Config) error ``` StartTLS方法發送STARTTLS命令，并將之后的所有數據往來加密。只有服務器附加了STARTTLS擴展，這個方法才有效。 ### func (\*Client) [Mail](https://github.com/golang/go/blob/master/src/net/smtp/smtp.go#L222 "View Source") ``` func (c *Client) Mail(from string) error ``` Mail發送MAIL命令和郵箱地址from到服務器。如果服務端支持8BITMIME擴展，本方法會添加BODY=8BITMIME參數。方法初始化一次郵件傳輸，后應跟1到多個Rcpt方法的調用。 ### func (\*Client) [Rcpt](https://github.com/golang/go/blob/master/src/net/smtp/smtp.go#L239 "View Source") ``` func (c *Client) Rcpt(to string) error ``` Rcpt發送RCPT命令和郵箱地址to到服務器。調用Rcpt方法之前必須調用了Mail方法，之后可以再一次調用Rcpt方法，也可以調用Data方法。 ### func (\*Client) [Data](https://github.com/golang/go/blob/master/src/net/smtp/smtp.go#L259 "View Source") ``` func (c *Client) Data() (io.WriteCloser, error) ``` Data發送DATA指令到服務器并返回一個io.WriteCloser，用于寫入郵件信息。調用者必須在調用c的下一個方法之前關閉這個io.WriteCloser。方法必須在一次或多次Rcpt方法之后調用。 ### func (\*Client) [Reset](https://github.com/golang/go/blob/master/src/net/smtp/smtp.go#L339 "View Source") ``` func (c *Client) Reset() error ``` Reset向服務端發送REST命令，中斷當前的郵件傳輸。 ### func (\*Client) [Quit](https://github.com/golang/go/blob/master/src/net/smtp/smtp.go#L348 "View Source") ``` func (c *Client) Quit() error ``` Quit發送QUIT命令并關閉到服務端的連接。 ### func (\*Client) [Close](https://github.com/golang/go/blob/master/src/net/smtp/smtp.go#L68 "View Source") ``` func (c *Client) Close() error ``` Close關閉連接。 ## func [SendMail](https://github.com/golang/go/blob/master/src/net/smtp/smtp.go#L273 "View Source") ``` func SendMail(addr string, a Auth, from string, to []string, msg []byte) error ``` SendMail連接到addr指定的服務器；如果支持會開啟TLS；如果支持會使用a認證身份；然后以from為郵件源地址發送郵件msg到目標地址to。（可以是多個目標地址：群發）