Пакет smtp
Обзор
Пакет smtp реализует простой протокол передачи почты (Simple Mail Transfer Protocol), определённый в RFC 5321. Он также реализует следующие расширения:
8BITMIME RFC 1652 AUTH RFC 2554 STARTTLS RFC 3207
Клиенты могут обрабатывать дополнительные расширения.
Пакет smtp заморожен и не принимает новые функции. Некоторые внешние пакеты предоставляют больше возможностей. См.:
https://godoc.org/?q=smtp
Пример
Код:
// 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)
}
Указатель
Файлы пакета
auth.go smtp.go
func SendMail
func SendMail(addr string, a Auth, from string, to []string, msg []byte) error
SendMail подключается к серверу по адресу addr, при возможности переключается на TLS, при возможности проходит аутентификацию с помощью необязательного механизма a, а затем отправляет электронное письмо с адреса from на адреса to с сообщением msg. Адрес addr должен содержать порт, например "mail.example.com:smtp".
Адреса в параметре to — это адреса SMTP RCPT.
Параметр msg должен представлять собой электронное письмо в формате RFC 822: сначала заголовки, затем пустая строка и тело сообщения. Строки msg должны завершаться CRLF. Заголовки msg обычно должны включать такие поля, как "From", "To", "Subject" и "Cc". Отправка сообщений "Bcc" выполняется путём указания адреса электронной почты в параметре to, но без включения его в заголовки msg.
Функция SendMail и пакет net/smtp — это низкоуровневые средства, не предоставляющие поддержку подписания DKIM, вложений MIME (см. пакет mime/multipart) и других функций для работы с почтой. Существуют пакеты более высокого уровня, не входящие в стандартную библиотеку.
Пример
Код:
// 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)
}
type Auth
Auth реализуется механизмом аутентификации SMTP.
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)
} func CRAMMD5Auth
func CRAMMD5Auth(username, secret string) Auth
CRAMMD5Auth возвращает Auth, реализующий механизм аутентификации CRAM-MD5, определённый в RFC 2195. Возвращаемый Auth использует указанные имя пользователя и секрет для аутентификации на сервере с помощью механизма «запрос-ответ».
func PlainAuth
func PlainAuth(identity, username, password, host string) Auth
PlainAuth возвращает Auth, реализующий механизм аутентификации PLAIN, определённый в RFC 4616. Возвращаемый Auth использует указанные имя пользователя и пароль для аутентификации на host и выступает в роли identity. Обычно identity должно быть пустой строкой, чтобы использовать имя пользователя.
PlainAuth отправляет учётные данные, только если соединение использует TLS или подключено к localhost. В противном случае аутентификация завершится ошибкой, а учётные данные не будут отправлены.
Пример
Код:
// 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)
}
type Client
Client представляет клиентское соединение с SMTP-сервером.
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
}
func Dial
func Dial(addr string) (*Client, error)
Dial возвращает новый Client, подключённый к SMTP-серверу по адресу addr. Адрес addr должен содержать порт, например "mail.example.com:smtp".
func NewClient
func NewClient(conn net.Conn, host string) (*Client, error)
NewClient возвращает новый Client, использующий существующее соединение и имя host в качестве имени сервера для аутентификации.
func (*Client) Auth
func (c *Client) Auth(a Auth) error
Auth выполняет аутентификацию клиента с помощью предоставленного механизма аутентификации. При неудачной аутентификации соединение закрывается. Эту функцию поддерживают только серверы, объявляющие расширение AUTH.
func (*Client) Close 1.2
func (c *Client) Close() error
Close закрывает соединение.
func (*Client) Data
func (c *Client) Data() (io.WriteCloser, error)
Data отправляет серверу команду DATA и возвращает средство записи, которое можно использовать для записи заголовков и тела письма. Вызывающий код должен закрыть средство записи, прежде чем вызывать другие методы для c. Перед вызовом Data необходимо один или несколько раз вызвать Client.Rcpt.
func (*Client) Extension
func (c *Client) Extension(ext string) (bool, string)
Extension сообщает, поддерживается ли расширение сервером. Имя расширения не зависит от регистра. Если расширение поддерживается, Extension также возвращает строку с параметрами, указанными сервером для этого расширения.
func (*Client) Hello 1.1
func (c *Client) Hello(localName string) error
Hello отправляет серверу команду HELO или EHLO с указанным именем хоста. Этот метод необходимо вызывать только в том случае, если клиенту нужно управлять используемым именем хоста. В противном случае клиент автоматически представится как "localhost". Если Hello вызывается, его необходимо вызвать до вызова любых других методов.
func (*Client) Mail
func (c *Client) Mail(from string) error
Mail отправляет серверу команду MAIL с указанным адресом электронной почты. Если сервер поддерживает расширение 8BITMIME, Mail добавляет параметр BODY=8BITMIME. Если сервер поддерживает расширение SMTPUTF8, Mail добавляет параметр SMTPUTF8. Это начинает почтовую транзакцию, после чего необходимо один или несколько раз вызвать Client.Rcpt.
func (*Client) Noop 1.10
func (c *Client) Noop() error
Noop отправляет серверу команду NOOP. Она ничего не делает, кроме проверки того, что соединение с сервером работает.
func (*Client) Quit
func (c *Client) Quit() error
Quit отправляет команду QUIT и закрывает соединение с сервером.
func (*Client) Rcpt
func (c *Client) Rcpt(to string) error
Rcpt отправляет серверу команду RCPT, используя указанный адрес электронной почты. Вызову Rcpt должен предшествовать вызов Client.Mail, после него может следовать вызов Client.Data или другой вызов Rcpt.
func (*Client) Reset
func (c *Client) Reset() error
Reset отправляет серверу команду RSET, прерывая текущую почтовую транзакцию.
func (*Client) StartTLS
func (c *Client) StartTLS(config *tls.Config) error
StartTLS отправляет команду STARTTLS и шифрует всю дальнейшую связь. Эту функцию поддерживают только серверы, объявляющие расширение STARTTLS.
func (*Client) TLSConnectionState 1.5
func (c *Client) TLSConnectionState() (state tls.ConnectionState, ok bool)
TLSConnectionState возвращает состояние TLS-соединения клиента. Если Client.StartTLS завершился неудачно, возвращаются нулевые значения.
func (*Client) Verify
func (c *Client) Verify(addr string) error
Verify проверяет действительность адреса электронной почты на сервере. Если Verify возвращает nil, адрес действителен. Возвращаемое ненулевое значение не обязательно указывает на недействительный адрес. Многие серверы не проверяют адреса по соображениям безопасности.
type ServerInfo
ServerInfo содержит сведения о SMTP-сервере.
type ServerInfo struct {
Name string // SMTP server name
TLS bool // using TLS, with valid certificate for Name
Auth []string // advertised authentication mechanisms
}
© Google, Inc.
Licensed under the Creative Commons Attribution License 3.0.
http://golang.org/pkg/net/smtp/
