1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
|
<h1> Package smtp </h1> <ul id="short-nav">
<li><code>import "net/smtp"</code></li>
<li><a href="#pkg-overview" class="overviewLink">Overview</a></li>
<li><a href="#pkg-index" class="indexLink">Index</a></li>
<li><a href="#pkg-examples" class="examplesLink">Examples</a></li>
</ul> <h2 id="pkg-overview">Overview </h2> <p>Package smtp implements the Simple Mail Transfer Protocol as defined in RFC 5321. It also implements the following extensions: </p>
<pre data-language="go">8BITMIME RFC 1652
AUTH RFC 2554
STARTTLS RFC 3207
</pre> <p>Additional extensions may be handled by clients. </p>
<p>The smtp package is frozen and is not accepting new features. Some external packages provide more functionality. See: </p>
<pre data-language="go">https://godoc.org/?q=smtp
</pre> <h4 id="example_"> <span class="text">Example</span>
</h4> <p>Code:</p> <pre class="code" data-language="go">
// 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)
}
</pre> <h2 id="pkg-index">Index </h2> <ul id="manual-nav">
<li><a href="#SendMail">func SendMail(addr string, a Auth, from string, to []string, msg []byte) error</a></li>
<li><a href="#Auth">type Auth</a></li>
<li> <a href="#CRAMMD5Auth">func CRAMMD5Auth(username, secret string) Auth</a>
</li>
<li> <a href="#PlainAuth">func PlainAuth(identity, username, password, host string) Auth</a>
</li>
<li><a href="#Client">type Client</a></li>
<li> <a href="#Dial">func Dial(addr string) (*Client, error)</a>
</li>
<li> <a href="#NewClient">func NewClient(conn net.Conn, host string) (*Client, error)</a>
</li>
<li> <a href="#Client.Auth">func (c *Client) Auth(a Auth) error</a>
</li>
<li> <a href="#Client.Close">func (c *Client) Close() error</a>
</li>
<li> <a href="#Client.Data">func (c *Client) Data() (io.WriteCloser, error)</a>
</li>
<li> <a href="#Client.Extension">func (c *Client) Extension(ext string) (bool, string)</a>
</li>
<li> <a href="#Client.Hello">func (c *Client) Hello(localName string) error</a>
</li>
<li> <a href="#Client.Mail">func (c *Client) Mail(from string) error</a>
</li>
<li> <a href="#Client.Noop">func (c *Client) Noop() error</a>
</li>
<li> <a href="#Client.Quit">func (c *Client) Quit() error</a>
</li>
<li> <a href="#Client.Rcpt">func (c *Client) Rcpt(to string) error</a>
</li>
<li> <a href="#Client.Reset">func (c *Client) Reset() error</a>
</li>
<li> <a href="#Client.StartTLS">func (c *Client) StartTLS(config *tls.Config) error</a>
</li>
<li> <a href="#Client.TLSConnectionState">func (c *Client) TLSConnectionState() (state tls.ConnectionState, ok bool)</a>
</li>
<li> <a href="#Client.Verify">func (c *Client) Verify(addr string) error</a>
</li>
<li><a href="#ServerInfo">type ServerInfo</a></li>
</ul> <div id="pkg-examples"> <h3>Examples</h3> <dl> <dd><a class="exampleLink" href="#example_">Package</a></dd> <dd><a class="exampleLink" href="#example_PlainAuth">PlainAuth</a></dd> <dd><a class="exampleLink" href="#example_SendMail">SendMail</a></dd> </dl> </div> <h3>Package files</h3> <p> <span>auth.go</span> <span>smtp.go</span> </p> <h2 id="SendMail">func <span>SendMail</span> </h2> <pre data-language="go">func SendMail(addr string, a Auth, from string, to []string, msg []byte) error</pre> <p>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". </p>
<p>The addresses in the to parameter are the SMTP RCPT addresses. </p>
<p>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. </p>
<p>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. </p> <h4 id="example_SendMail"> <span class="text">Example</span>
</h4> <p>Code:</p> <pre class="code" data-language="go">
// 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("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)
}
</pre> <h2 id="Auth">type <span>Auth</span> </h2> <p>Auth is implemented by an SMTP authentication mechanism. </p>
<pre data-language="go">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)
}</pre> <h3 id="CRAMMD5Auth">func <span>CRAMMD5Auth</span> </h3> <pre data-language="go">func CRAMMD5Auth(username, secret string) Auth</pre> <p>CRAMMD5Auth returns an <a href="#Auth">Auth</a> 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. </p>
<h3 id="PlainAuth">func <span>PlainAuth</span> </h3> <pre data-language="go">func PlainAuth(identity, username, password, host string) Auth</pre> <p>PlainAuth returns an <a href="#Auth">Auth</a> 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. </p>
<p>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. </p> <h4 id="example_PlainAuth"> <span class="text">Example</span>
</h4> <p>Code:</p> <pre class="code" data-language="go">
// 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)
}
</pre> <h2 id="Client">type <span>Client</span> </h2> <p>A Client represents a client connection to an SMTP server. </p>
<pre data-language="go">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
}
</pre> <h3 id="Dial">func <span>Dial</span> </h3> <pre data-language="go">func Dial(addr string) (*Client, error)</pre> <p>Dial returns a new <a href="#Client">Client</a> connected to an SMTP server at addr. The addr must include a port, as in "mail.example.com:smtp". </p>
<h3 id="NewClient">func <span>NewClient</span> </h3> <pre data-language="go">func NewClient(conn net.Conn, host string) (*Client, error)</pre> <p>NewClient returns a new <a href="#Client">Client</a> using an existing connection and host as a server name to be used when authenticating. </p>
<h3 id="Client.Auth">func (*Client) <span>Auth</span> </h3> <pre data-language="go">func (c *Client) Auth(a Auth) error</pre> <p>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. </p>
<h3 id="Client.Close">func (*Client) <span>Close</span> <span title="Added in Go 1.2">1.2</span> </h3> <pre data-language="go">func (c *Client) Close() error</pre> <p>Close closes the connection. </p>
<h3 id="Client.Data">func (*Client) <span>Data</span> </h3> <pre data-language="go">func (c *Client) Data() (io.WriteCloser, error)</pre> <p>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 <a href="#Client.Rcpt">Client.Rcpt</a>. </p>
<h3 id="Client.Extension">func (*Client) <span>Extension</span> </h3> <pre data-language="go">func (c *Client) Extension(ext string) (bool, string)</pre> <p>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. </p>
<h3 id="Client.Hello">func (*Client) <span>Hello</span> <span title="Added in Go 1.1">1.1</span> </h3> <pre data-language="go">func (c *Client) Hello(localName string) error</pre> <p>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. </p>
<h3 id="Client.Mail">func (*Client) <span>Mail</span> </h3> <pre data-language="go">func (c *Client) Mail(from string) error</pre> <p>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 <a href="#Client.Rcpt">Client.Rcpt</a> calls. </p>
<h3 id="Client.Noop">func (*Client) <span>Noop</span> <span title="Added in Go 1.10">1.10</span> </h3> <pre data-language="go">func (c *Client) Noop() error</pre> <p>Noop sends the NOOP command to the server. It does nothing but check that the connection to the server is okay. </p>
<h3 id="Client.Quit">func (*Client) <span>Quit</span> </h3> <pre data-language="go">func (c *Client) Quit() error</pre> <p>Quit sends the QUIT command and closes the connection to the server. </p>
<h3 id="Client.Rcpt">func (*Client) <span>Rcpt</span> </h3> <pre data-language="go">func (c *Client) Rcpt(to string) error</pre> <p>Rcpt issues a RCPT command to the server using the provided email address. A call to Rcpt must be preceded by a call to <a href="#Client.Mail">Client.Mail</a> and may be followed by a <a href="#Client.Data">Client.Data</a> call or another Rcpt call. </p>
<h3 id="Client.Reset">func (*Client) <span>Reset</span> </h3> <pre data-language="go">func (c *Client) Reset() error</pre> <p>Reset sends the RSET command to the server, aborting the current mail transaction. </p>
<h3 id="Client.StartTLS">func (*Client) <span>StartTLS</span> </h3> <pre data-language="go">func (c *Client) StartTLS(config *tls.Config) error</pre> <p>StartTLS sends the STARTTLS command and encrypts all further communication. Only servers that advertise the STARTTLS extension support this function. </p>
<h3 id="Client.TLSConnectionState">func (*Client) <span>TLSConnectionState</span> <span title="Added in Go 1.5">1.5</span> </h3> <pre data-language="go">func (c *Client) TLSConnectionState() (state tls.ConnectionState, ok bool)</pre> <p>TLSConnectionState returns the client's TLS connection state. The return values are their zero values if <a href="#Client.StartTLS">Client.StartTLS</a> did not succeed. </p>
<h3 id="Client.Verify">func (*Client) <span>Verify</span> </h3> <pre data-language="go">func (c *Client) Verify(addr string) error</pre> <p>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. </p>
<h2 id="ServerInfo">type <span>ServerInfo</span> </h2> <p>ServerInfo records information about an SMTP server. </p>
<pre data-language="go">type ServerInfo struct {
Name string // SMTP server name
TLS bool // using TLS, with valid certificate for Name
Auth []string // advertised authentication mechanisms
}
</pre><div class="_attribution">
<p class="_attribution-p">
© Google, Inc.<br>Licensed under the Creative Commons Attribution License 3.0.<br>
<a href="http://golang.org/pkg/net/smtp/" class="_attribution-link">http://golang.org/pkg/net/smtp/</a>
</p>
</div>
|
