blackmailzgo.at/blackmail/smtp Index | Examples | Files

package smtp

import "zgo.at/blackmail/smtp"

Package smtp implements a SMTP client as defined in RFC 5321.

It also implements the following extensions:

8BITMIME             RFC 1652
AUTH                 RFC 2554
STARTTLS             RFC 3207
ENHANCEDSTATUSCODES  RFC 2034
SMTPUTF8             RFC 6531
REQUIRETLS           draft-ietf-uta-smtp-require-tls-09

Index

Examples

Variables

var (
	ErrUnexpectedAuthResponse    = errors.New("sasl: unexpected client response")
	ErrUnexpectedServerChallenge = errors.New("sasl: unexpected server challenge")
)

Common SASL errors.

Functions

func SendMail

func SendMail(addr string, a Auth, from string, to []string, r io.Reader) error

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 5322-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.

TODO: this should accept some options.

Example

Code:play 

package main

import (
	"log"
	"strings"

	"zgo.at/blackmail/smtp"
)

func main() {
	// Set up authentication information.
	auth := smtp.PlainAuth("", "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)
	}
}

Types

type Auth

type Auth interface {
	// Begins SASL authentication with the server. It returns the
	// authentication mechanism name and "initial response" data (if required by
	// the selected mechanism). A non-nil error causes the client to abort the
	// authentication attempt.
	//
	// A nil ir value is different from a zero-length value. The nil value
	// indicates that the selected mechanism does not use an initial response,
	// while a zero-length value indicates an empty initial response, which must
	// be sent to the server.
	Start() (mech string, ir []byte, err error)

	// Continues challenge-response authentication. A non-nil error causes
	// the client to abort the authentication attempt.
	Next(challenge []byte) (response []byte, err error)
}

Auth interface to perform challenge-response authentication.

func CramMD5Auth

func CramMD5Auth(username, secret string) Auth

CramMD5Auth implements the CRAM-MD5 authentication mechanism, as described in RFC 2195.

The returned Auth uses the given username and secret to authenticate to the server using the challenge-response mechanism.

func LoginAuth

func LoginAuth(username, password string) Auth

LoginAuth implements of the LOGIN authentication mechanism as described in http://www.iana.org/go/draft-murchison-sasl-login

func PlainAuth

func PlainAuth(identity, username, password string) Auth

PlainAuth implements the PLAIN authentication mechanism as described in RFC 4616. Authorization identity may be left blank to indicate that it is the same as the username.

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

func Dial(addr string) (*Client, error)

Dial returns a new Client connected to an SMTP server at addr. The addr must include a port, as in "mail.example.com:smtp".

Example

Code:play 

package main

import (
	"fmt"
	"log"

	"zgo.at/blackmail/smtp"
)

func main() {
	// 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", nil); 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)
	}
}

func DialTLS

func DialTLS(addr string, tlsConfig *tls.Config) (*Client, error)

DialTLS returns a new Client connected to an SMTP server via TLS at addr. The addr must include a port, as in "mail.example.com:smtps".

func NewClient

func NewClient(conn net.Conn, host string) (*Client, error)

NewClient returns a new Client using an existing connection and host as a server name to be used when authenticating.

func (*Client) Auth

func (c *Client) Auth(a Auth) error

Auth authenticates a client using the provided authentication mechanism. Only servers that advertise the AUTH extension support this function.

If server returns an error, it will be of type *SMTPError.

func (*Client) Close

func (c *Client) Close() error

Close closes the connection.

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.

If server returns an error, it will be of type *SMTPError.

func (*Client) Extension

func (c *Client) Extension(ext string) (bool, string)

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

func (c *Client) Hello(localName string) error

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.

If server returns an error, it will be of type *SMTPError.

func (*Client) Mail

func (c *Client) Mail(from string, opts *MailOptions) error

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.

If opts is not nil, MAIL arguments provided in the structure will be added to the command. Handling of unsupported options depends on the extension.

If server returns an error, it will be of type *SMTPError.

func (*Client) Noop

func (c *Client) Noop() error

Noop sends the NOOP command to the server. It does nothing but check that the connection to the server is okay.

func (*Client) Quit

func (c *Client) Quit() error

Quit sends the QUIT command and closes the connection to the server.

If Quit fails the connection is not closed, Close should be used in this case.

func (*Client) Rcpt

func (c *Client) Rcpt(to string) error

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.

If server returns an error, it will be of type *SMTPError.

func (*Client) Reset

func (c *Client) Reset() error

Reset sends the RSET command to the server, aborting the current mail transaction.

func (*Client) StartTLS

func (c *Client) StartTLS(config *tls.Config) error

StartTLS sends the STARTTLS command and encrypts all further communication. Only servers that advertise the STARTTLS extension support this function.

If server returns an error, it will be of type *SMTPError.

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.

func (*Client) Verify

func (c *Client) Verify(addr string) error

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.

If server returns an error, it will be of type *SMTPError.

type EnhancedCode

type EnhancedCode [3]int

type MailOptions

type MailOptions struct {
	// Size of the body. Can be 0 if not specified by client.
	Size int

	// TLS is required for the message transmission.
	//
	// The message should be rejected if it can't be transmitted
	// with TLS.
	RequireTLS bool

	// The message envelope or message header contains UTF-8-encoded strings.
	// This flag is set by SMTPUTF8-aware (RFC 6531) client.
	UTF8 bool

	// The authorization identity asserted by the message sender in decoded
	// form with angle brackets stripped.
	//
	// nil value indicates missing AUTH, non-nil empty string indicates
	// AUTH=<>.
	//
	// Defined in RFC 4954.
	Auth *string
}

MailOptions contains custom arguments that were passed as an argument to the MAIL command.

type SMTPError

type SMTPError struct {
	Code         int
	EnhancedCode EnhancedCode
	Message      string
}

SMTPError specifies the error code, enhanced error code (if any) and message returned by the server.

func (*SMTPError) Error

func (err *SMTPError) Error() string

func (*SMTPError) Temporary

func (err *SMTPError) Temporary() bool

Source Files

auth.go smtp.go smtp_aux.go

Version
v0.0.0-20221021025740-b3fdfc32a1aa (latest)
Published
Oct 21, 2022
Platform
linux/amd64
Imports
12 packages
Last checked
1 month ago

Tools for package owners.