pop3

Documentation

Overview

Package pop3 is a simple POP3 e-mail client library.

Index

• type Client
  • func New(opt Opt) *Client
  • func (c *Client) NewConn() (*Conn, error)
• type Conn
  • func (c *Conn) Auth(user, password string) error
  • func (c *Conn) CAPA() (map[string]string, error)
  • func (c *Conn) ChallengeCmd(cmd string, args ...interface{}) (buf *bytes.Buffer, isChallenge bool, err error)
  • func (c *Conn) Cmd(cmd string, isMulti bool, args ...interface{}) (*bytes.Buffer, error)
  • func (c *Conn) Dele(msgID ...int) error
  • func (c *Conn) List(msgID int) ([]MessageID, error)
  • func (c *Conn) Noop() error
  • func (c *Conn) Pass(s string) error
  • func (c *Conn) Quit() error
  • func (c *Conn) ReadAll() (*bytes.Buffer, error)
  • func (c *Conn) ReadOne() ([]byte, error)
  • func (c *Conn) ReadOneWithChallenge() ([]byte, bool, error)
  • func (c *Conn) Retr(msgID int) (*message.Entity, error)
  • func (c *Conn) RetrRaw(msgID int) (*bytes.Buffer, error)
  • func (c *Conn) Rset() error
  • func (c *Conn) SASLAuth(a smtp.Auth) error
  • func (c *Conn) Send(b string) error
  • func (c *Conn) StartTLS(cfg *tls.Config) error
  • func (c *Conn) Stat() (int, int, error)
  • func (c *Conn) Top(msgID int, numLines int) (*message.Entity, error)
  • func (c *Conn) Uidl(msgID int) ([]MessageID, error)
  • func (c *Conn) User(s string) error
• type Dialer
• type MessageID
• type Opt

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client implements a Client e-mail client.

func New

func New(opt Opt) *Client

New returns a new client object using an existing connection.

func (*Client) NewConn

func (c *Client) NewConn() (*Conn, error)

NewConn creates and returns live POP3 server connection.

type Conn

type Conn struct {
	// contains filtered or unexported fields
}

Conn is a stateful connection with the POP3 server/

func (*Conn) Auth

func (c *Conn) Auth(user, password string) error

Auth authenticates the given credentials with the server.

func (*Conn) CAPA

func (c *Conn) CAPA() (map[string]string, error)

CAPA returns the capabilities of the server.

func (*Conn) ChallengeCmd

func (c *Conn) ChallengeCmd(cmd string, args ...interface{}) (buf *bytes.Buffer, isChallenge bool, err error)

func (*Conn) Cmd

func (c *Conn) Cmd(cmd string, isMulti bool, args ...interface{}) (*bytes.Buffer, error)

Cmd sends a command to the server. POP3 responses are either single line or multi-line. The first line always with -ERR in case of an error or +OK in case of a successful operation. OK+ is always followed by a response on the same line which is either the actual response data in case of single line responses, or a help message followed by multiple lines of actual response data in case of multiline responses. See https://www.shellhacks.com/retrieve-email-pop3-server-command-line/ for examples.

func (*Conn) Dele

func (c *Conn) Dele(msgID ...int) error

Dele deletes one or more messages. The server only executes the deletions after a successful Quit().

func (*Conn) List

func (c *Conn) List(msgID int) ([]MessageID, error)

List returns a list of (message ID, message Size) pairs. If the optional msgID > 0, then only that particular message is listed. The message IDs are sequential, 1 to N.

func (*Conn) Noop

func (c *Conn) Noop() error

Noop issues a do-nothing NOOP command to the server. This is useful for prolonging open connections.

func (*Conn) Pass

func (c *Conn) Pass(s string) error

Pass sends the password to the server.

func (*Conn) Quit

func (c *Conn) Quit() error

Quit sends the QUIT command to server and gracefully closes the connection. Message deletions (DELE command) are only excuted by the server on a graceful quit and close.

func (*Conn) ReadAll

func (c *Conn) ReadAll() (*bytes.Buffer, error)

ReadAll reads all lines from the connection until the POP3 multiline terminator "." is encountered and returns a bytes.Buffer of all the read lines.

func (*Conn) ReadOne

func (c *Conn) ReadOne() ([]byte, error)

ReadOne reads a single line response from the conn.

func (*Conn) ReadOneWithChallenge

func (c *Conn) ReadOneWithChallenge() ([]byte, bool, error)

ReadOne reads a single line response from the conn.

func (*Conn) Retr

func (c *Conn) Retr(msgID int) (*message.Entity, error)

Retr downloads a message by the given msgID, parses it and returns it as a emersion/go-message.message.Entity object.

func (*Conn) RetrRaw

func (c *Conn) RetrRaw(msgID int) (*bytes.Buffer, error)

RetrRaw downloads a message by the given msgID and returns the raw []byte of the entire message.

func (*Conn) Rset

func (c *Conn) Rset() error

Rset clears the messages marked for deletion in the current session.

func (*Conn) SASLAuth

func (c *Conn) SASLAuth(a smtp.Auth) error

SASLAuth authenticates a client using the provided authentication mechanism. A failed authentication closes the connection. Only servers that advertise the SASL capability can be authenticated using this method.

func (*Conn) Send

func (c *Conn) Send(b string) error

Send sends a POP3 command to the server. The given comand is suffixed with "\r\n".

func (*Conn) StartTLS

func (c *Conn) StartTLS(cfg *tls.Config) error

func (*Conn) Stat

func (c *Conn) Stat() (int, int, error)

Stat returns the number of messages and their total size in bytes in the inbox.

func (*Conn) Top

func (c *Conn) Top(msgID int, numLines int) (*message.Entity, error)

Top retrieves a message by its ID with full headers and numLines lines of the body.

func (*Conn) Uidl

func (c *Conn) Uidl(msgID int) ([]MessageID, error)

Uidl returns a list of (message ID, message UID) pairs. If the optional msgID is > 0, then only that particular message is listed. It works like Top() but only works on servers that support the UIDL command. Messages size field is not available in the UIDL response.

func (*Conn) User

func (c *Conn) User(s string) error

User sends the username to the server.

type Dialer

type Dialer interface {
	Dial(network, address string) (net.Conn, error)
}

type MessageID

type MessageID struct {
	// ID is the numerical index (non-unique) of the message.
	ID   int
	Size int

	// UID is only present if the response is to the UIDL command.
	UID string
}

MessageID contains the ID and size of an individual message.

type Opt

type Opt struct {
	Host string `json:"host"`
	Port int    `json:"port"`

	// Default is 3 seconds.
	DialTimeout time.Duration `json:"dial_timeout"`
	Dialer      Dialer        `json:"-"`

	TLSEnabled    bool `json:"tls_enabled"`
	TLSSkipVerify bool `json:"tls_skip_verify"`
}

Opt represents the client configuration.