maildir

README

The maildir package provides an interface to mailboxes in the Maildir format.

Documentation can be found online here:
https://pkg.go.dev/github.com/luksen/maildir

This is what I used as a reference:
- https://en.wikipedia.org/wiki/Maildir
- http://www.qmail.org/qmail-manual-html/man5/maildir.html
- http://cr.yp.to/proto/maildir.html

Documentation

Overview

The maildir package provides an interface to mailboxes in the Maildir format.

Index

• Constants
• Variables
• func Key() (string, error)
• type Delivery
  • func (d *Delivery) Abort() error
  • func (d *Delivery) Close() error
  • func (d *Delivery) Write(p []byte) (int, error)
• type Dir
  • func (d Dir) Clean() error
  • func (d Dir) Create() error
  • func (d Dir) Filename(key string) (string, error)
  • func (d Dir) Flags(key string) (string, error)
  • func (d Dir) Header(key string) (header mail.Header, err error)
  • func (d Dir) Keys() ([]string, error)
  • func (d Dir) Message(key string) (*mail.Message, error)
  • func (d Dir) Move(target Dir, key string) error
  • func (d Dir) NewDelivery() (*Delivery, error)
  • func (d Dir) Purge(key string) error
  • func (d Dir) SetFlags(key string, flags string) error
  • func (d Dir) SetInfo(key, info string) error
  • func (d Dir) Unseen() ([]string, error)
  • func (d Dir) UnseenCount() (int, error)
• type FlagError
  • func (e *FlagError) Error() string
• type KeyError
  • func (e *KeyError) Error() string

Constants

const CreateMode = 0700

CreateMode holds the permissions used when creating a directory.

Variables

var Separator rune = ':'

The Separator separates a messages unique key from its flags in the filename. This should only be changed on operating systems where the colon isn't allowed in filenames.

Functions

func Key

func Key() (string, error)

Key exposes the internal unique key generation. This function is deprecated.

Types

type Delivery

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

Delivery represents an ongoing message delivery to the mailbox. It implements the WriteCloser interface. On closing the underlying file is moved/relinked to new.

func (*Delivery) Abort

func (d *Delivery) Abort() error

Abort closes the underlying file and removes it completely.

func (*Delivery) Close

func (d *Delivery) Close() error

Close closes the underlying file and moves it to new.

func (*Delivery) Write

func (d *Delivery) Write(p []byte) (int, error)

type Dir

type Dir string

A Dir represents a single directory in a Maildir mailbox.

func (Dir) Clean

func (d Dir) Clean() error

Clean removes old files from tmp and should be run periodically. This does not use access time but modification time for portability reasons.

func (Dir) Create

func (d Dir) Create() error

Create creates the directory structure for a Maildir. If the main directory already exists, it tries to create the subdirectories in there. If an error occurs while creating one of the subdirectories, this function may leave a partially created directory structure.

func (Dir) Filename

func (d Dir) Filename(key string) (string, error)

Filename returns the path to the file corresponding to the key.

func (Dir) Flags

func (d Dir) Flags(key string) (string, error)

Flags returns the flags for a message sorted in ascending order. See the documentation of SetFlags for details.

func (Dir) Header

func (d Dir) Header(key string) (header mail.Header, err error)

Header returns the corresponding mail header to a key.

func (Dir) Keys

func (d Dir) Keys() ([]string, error)

Keys returns a slice of valid keys to access messages by. This only returns keys for messages in cur. Use Unseen to access messages in new. All keys, whether returned here or by Unseen, point to messages in cur.

func (Dir) Message

func (d Dir) Message(key string) (*mail.Message, error)

Message returns a Message by key.

func (Dir) Move

func (d Dir) Move(target Dir, key string) error

Move moves a message from this Maildir to another.

func (Dir) NewDelivery

func (d Dir) NewDelivery() (*Delivery, error)

NewDelivery creates a new Delivery.

func (Dir) Purge

func (d Dir) Purge(key string) error

Purge removes the actual file behind this message.

func (Dir) SetFlags

func (d Dir) SetFlags(key string, flags string) error

SetFlags appends an info section to the filename according to the given flags. This function removes duplicates and sorts the flags, but doesn't check whether they conform with the Maildir specification.

The following flags are listed in the specification (http://cr.yp.to/proto/maildir.html):

Flag "P" (passed): the user has resent/forwarded/bounced this message to someone else.
Flag "R" (replied): the user has replied to this message.
Flag "S" (seen): the user has viewed this message, though perhaps he didn't read all the way through it.
Flag "T" (trashed): the user has moved this message to the trash; the trash will be emptied by a later user action.
Flag "D" (draft): the user considers this message a draft; toggled at user discretion.
Flag "F" (flagged): user-defined flag; toggled at user discretion.

Using only these standard flags will improve message retrieval speed.

func (Dir) SetInfo

func (d Dir) SetInfo(key, info string) error

Set the info part of the filename. Only use this if you plan on using a non-standard info part.

func (Dir) Unseen

func (d Dir) Unseen() ([]string, error)

Unseen moves messages from new to cur and returns their keys. This means the messages are now known to the application. To find out whether a user has seen a message, use Flags().

func (Dir) UnseenCount

func (d Dir) UnseenCount() (int, error)

UnseenCount returns the number of messages in new without looking at them.

type FlagError

type FlagError struct {
	Info         string // the encountered info section
	Experimental bool   // info section starts with 1
}

A FlagError occurs when a non-standard info section is encountered.

func (*FlagError) Error

func (e *FlagError) Error() string

type KeyError

type KeyError struct {
	Key string // the (invalid) key
	N   int    // number of matches (!= 1)
}

A KeyError occurs when a key matches more or less than one message.

func (*KeyError) Error

func (e *KeyError) Error() string