README
¶
go-smtp
An ESMTP client and server library written in Go.
Features
- ESMTP client & server implementing RFC 5321
- Support for SMTP AUTH and PIPELINING
- UTF-8 support for subject and message
Usage
Client
package main
import (
"log"
"strings"
"github.com/emersion/go-sasl"
"github.com/emersion/go-smtp"
)
func main() {
// Set up authentication information.
auth := sasl.NewPlainClient("", "user@example.com", "password")
// Connect to the server, authenticate, set the sender and recipient,
// and send the email all in one step.
to := []string{"recipient@example.net"}
msg := strings.NewReader("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)
}
}
If you need more control, you can use Client instead.
Server
package main
import (
"errors"
"io/ioutil"
"log"
"github.com/emersion/go-smtp"
)
type Backend struct{}
func (bkd *Backend) Login(username, password string) (smtp.User, error) {
if username != "username" || password != "password" {
return nil, errors.New("Invalid username or password")
}
return &User{}, nil
}
type User struct{}
func (u *User) Send(from string, to []string, r io.Reader) error {
log.Println("Sending message:", from, to)
if b, err := ioutil.ReadAll(r); err != nil {
return err
} else {
log.Println("Data:", string(b))
}
return nil
}
func (u *User) Logout() error {
return nil
}
func main() {
be := &Backend{}
s := smtp.NewServer(be)
s.Addr = ":1025"
s.Domain = "localhost"
s.MaxIdleSeconds = 300
s.MaxMessageBytes = 1024 * 1024
s.MaxRecipients = 50
s.AllowInsecureAuth = true
log.Println("Starting server at", s.Addr)
if err := s.ListenAndServe(); err != nil {
log.Fatal(err)
}
}
You can use the server manually with telnet:
$ telnet localhost 1025
EHLO localhost
AUTH PLAIN
AHVzZXJuYW1lAHBhc3N3b3Jk
MAIL FROM:<root@nsa.gov>
RCPT TO:<root@gchq.gov.uk>
DATA
Hey <3
.
Licence
MIT
Documentation
¶
Overview ¶
Package smtp implements the Simple Mail Transfer Protocol as defined in RFC 5321. It also implements the following extensions:
8BITMIME RFC 1652 AUTH RFC 2554 STARTTLS RFC 3207
Additional extensions may be handled by other packages.
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)
}
Output:
Index ¶
- Variables
- func SendMail(addr string, a sasl.Client, from string, to []string, r io.Reader) error
- type Backend
- type Client
- func (c *Client) Auth(a sasl.Client) error
- func (c *Client) Close() error
- func (c *Client) Data() (io.WriteCloser, error)
- func (c *Client) Extension(ext string) (bool, string)
- func (c *Client) Hello(localName string) error
- func (c *Client) Mail(from string) error
- func (c *Client) Quit() error
- func (c *Client) Rcpt(to string) error
- func (c *Client) Reset() error
- func (c *Client) StartTLS(config *tls.Config) error
- func (c *Client) TLSConnectionState() (state tls.ConnectionState, ok bool)
- func (c *Client) Verify(addr string) error
- type Conn
- type SaslServerFactory
- type Server
- type User
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ErrDataTooLarge = &smtpError{
Code: 552,
Message: "Maximum message size exceeded",
}
Functions ¶
func SendMail ¶
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 r. The addr must include a port, as in "mail.example.com:smtp".
The addresses in the to parameter are the SMTP RCPT addresses.
The r parameter should be an RFC 822-style email with headers first, a blank line, and then the message body. The lines of r should be CRLF terminated. The r 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 r 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.
Example ¶
// Set up authentication information.
auth := sasl.NewPlainClient("", "user@example.com", "password")
// Connect to the server, authenticate, set the sender and recipient,
// and send the email all in one step.
to := []string{"recipient@example.net"}
msg := strings.NewReader("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)
}
Output:
Types ¶
type Client ¶
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
}
A Client represents a client connection to an SMTP server.
func Dial ¶
Dial returns a new Client connected to an SMTP server at addr. The addr must include a port, as in "mail.example.com:smtp".
func NewClient ¶
NewClient returns a new Client using an existing connection and host as a server name to be used when authenticating.
func (*Client) Auth ¶
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.
func (*Client) Data ¶
func (c *Client) Data() (io.WriteCloser, error)
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 Rcpt.
func (*Client) Extension ¶
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.
func (*Client) Hello ¶
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.
func (*Client) Mail ¶
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. This initiates a mail transaction and is followed by one or more Rcpt calls.
func (*Client) Rcpt ¶
Rcpt issues a RCPT command to the server using the provided email address. A call to Rcpt must be preceded by a call to Mail and may be followed by a Data call or another Rcpt call.
func (*Client) Reset ¶
Reset sends the RSET command to the server, aborting the current mail transaction.
func (*Client) StartTLS ¶
StartTLS sends the STARTTLS command and encrypts all further communication. Only servers that advertise the STARTTLS extension support this function.
func (*Client) TLSConnectionState ¶
func (c *Client) TLSConnectionState() (state tls.ConnectionState, ok bool)
TLSConnectionState returns the client's TLS connection state. The return values are their zero values if StartTLS did not succeed.
type Conn ¶
type Conn struct {
// contains filtered or unexported fields
}
func (*Conn) WriteResponse ¶
type SaslServerFactory ¶
type SaslServerFactory func(conn *Conn) sasl.Server
A function that creates SASL servers.
type Server ¶
type Server struct {
// TCP address to listen on.
Addr string
// The server TLS configuration.
TLSConfig *tls.Config
Domain string
MaxRecipients int
MaxIdleSeconds int
MaxMessageBytes int
AllowInsecureAuth bool
Debug io.Writer
// The server backend.
Backend Backend
// contains filtered or unexported fields
}
A SMTP server.
func (*Server) EnableAuth ¶
func (s *Server) EnableAuth(name string, f SaslServerFactory)
EnableAuth enables an authentication mechanism on this server.
This function should not be called directly, it must only be used by libraries implementing extensions of the SMTP protocol.
func (*Server) ForEachConn ¶
ForEachConn iterates through all opened connections.
func (*Server) ListenAndServe ¶
ListenAndServe listens on the TCP network address s.Addr and then calls Serve to handle requests on incoming connections.
If s.Addr is blank, ":smtp" is used.
func (*Server) ListenAndServeTLS ¶
ListenAndServeTLS listens on the TCP network address s.Addr and then calls Serve to handle requests on incoming TLS connections.
If s.Addr is blank, ":smtps" is used.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package backendutil provide utilities to implement SMTP backends.
|
Package backendutil provide utilities to implement SMTP backends. |