pop3

README

go-pop3

A simple Go POP3 client library for connecting and reading mails from POP3 servers. This is a full rewrite of TheCreeper/go-pop3 with bug fixes and new features.

Install

go get -u github.com/knadh/go-pop3

Example

import (
	"fmt"
	"github.com/knadh/go-pop3"
)

func main() {
	// Initialize the client.
	p := pop3.New(pop3.Opt{
		Host: "pop.gmail.com",
		Port: 995,
		TLSEnabled: true,
	})

	// Create a new connection. POP3 connections are stateful and should end
	// with a Quit() once the opreations are done.
	c, err := p.NewConn()
	if err != nil {
		log.Fatal(err)
	}
	defer c.Quit()

	// Authenticate.
	if err := c.Auth("myuser", "mypassword"); err != nil {
		log.Fatal(err)
	}

	// Print the total number of messages and their size.
	count, size, _ := c.Stat()
	fmt.Println("total messages=", count, "size=", size)

	// Pull the list of all message IDs and their sizes.
	msgs, _ := c.List(0)
	for _, m := range msgs {
		fmt.Println("id=", m.ID, "size=", m.Size)
	}

	// Pull all messages on the server. Message IDs go from 1 to N.
	for id := 1; id <= count; id++ {
		m, _ := c.Retr(id)

		fmt.Println(id, "=", m.Header.Get("subject"))

		// To read the multi-part e-mail bodies, see:
		// https://github.com/emersion/go-message/blob/master/example_test.go#L12
	}

	// Delete all the messages. Server only executes deletions after a successful Quit()
	for id := 1; id <= count; id++ {
		c.Dele(id)
	}
}

To-do: tests

Setup a Docker test environment that runs InBucket POP3 + SMTP server to run a dummy POP3 server and test all the commands in the lib.

Licensed under the MIT License.

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) 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) Retr(msgID int) (*message.Entity, error)
  • func (c *Conn) RetrRaw(msgID int) (*bytes.Buffer, error)
  • func (c *Conn) Rset() error
  • func (c *Conn) Send(b string) 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
  • func (c *Conn) XOAuth2(user, access_token string) error
• 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) 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) 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) 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) 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.

func (*Conn) XOAuth2

func (c *Conn) XOAuth2(user, access_token string) error

XOAuth2 sends an authentication request using an user name and OAuth access token.

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"`

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

Opt represents the client configuration.