imapclient

package
v0.0.10 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 9, 2024 License: MIT Imports: 12 Imported by: 1

Documentation

Overview

Package imapclient provides an IMAP4 client, primarily for testing the IMAP4 server.

Commands can be sent to the server free-form, but responses are parsed strictly. Behaviour that may not be required by the IMAP4 specification may be expected by this client.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Address 

type Address struct {
	Name, Adl, Mailbox, Host string
}

Address is an address field in an email message, e.g. To.

type BodyFields 

type BodyFields struct {
	Params                       [][2]string
	ContentID, ContentDescr, CTE string
	Octets                       int32
}

BodyFields is part of a FETCH BODY[] response.

type BodyTypeBasic 

type BodyTypeBasic struct {
	// ../rfc/9051:6407
	MediaType, MediaSubtype string
	BodyFields              BodyFields
}

BodyTypeBasic represents basic information about a part, used in a FETCH response.

type BodyTypeMpart 

type BodyTypeMpart struct {
	// ../rfc/9051:6411
	Bodies       []any // BodyTypeBasic, BodyTypeMsg, BodyTypeText
	MediaSubtype string
}

BodyTypeMpart represents the body structure a multipart message, with subparts and the multipart media subtype. Used in a FETCH response.

type BodyTypeMsg 

type BodyTypeMsg struct {
	// ../rfc/9051:6415
	MediaType, MediaSubtype string
	BodyFields              BodyFields
	Envelope                Envelope
	Bodystructure           any // One of the BodyType*
	Lines                   int64
}

BodyTypeMsg represents an email message as a body structure, used in a FETCH response.

type BodyTypeText 

type BodyTypeText struct {
	// ../rfc/9051:6418
	MediaType, MediaSubtype string
	BodyFields              BodyFields
	Lines                   int64
}

BodyTypeText represents a text part as a body structure, used in a FETCH response.

type Capability 

type Capability string

Capability is a known string for with the ENABLED and CAPABILITY command. 

const (
	CapIMAP4rev1     Capability = "IMAP4rev1"
	CapIMAP4rev2     Capability = "IMAP4rev2"
	CapLoginDisabled Capability = "LOGINDISABLED"
	CapStarttls      Capability = "STARTTLS"
	CapAuthPlain     Capability = "AUTH=PLAIN"
	CapLiteralPlus   Capability = "LITERAL+"
	CapLiteralMinus  Capability = "LITERAL-"
	CapIdle          Capability = "IDLE"
	CapNamespace     Capability = "NAMESPACE"
	CapBinary        Capability = "BINARY"
	CapUnselect      Capability = "UNSELECT"
	CapUidplus       Capability = "UIDPLUS"
	CapEsearch       Capability = "ESEARCH"
	CapEnable        Capability = "ENABLE"
	CapSave          Capability = "SAVE"
	CapListExtended  Capability = "LIST-EXTENDED"
	CapSpecialUse    Capability = "SPECIAL-USE"
	CapMove          Capability = "MOVE"
	CapUTF8Only      Capability = "UTF8=ONLY"
	CapUTF8Accept    Capability = "UTF8=ACCEPT"
	CapID            Capability = "ID" // ../rfc/2971:80
)

type CodeAppendUID 

type CodeAppendUID struct {
	UIDValidity uint32
	UID         uint32
}

"APPENDUID" response code.

func (CodeAppendUID) CodeString 

func (c CodeAppendUID) CodeString() string

type CodeArg 

type CodeArg interface {
	CodeString() string
}

CodeArg represents a response code with arguments, i.e. the data between [] in the response line.

type CodeCopyUID 

type CodeCopyUID struct {
	DestUIDValidity uint32
	From            []NumRange
	To              []NumRange
}

"COPYUID" response code.

func (CodeCopyUID) CodeString 

func (c CodeCopyUID) CodeString() string

type CodeHighestModSeq added in v0.0.6 

type CodeHighestModSeq int64

For CONDSTORE.

func (CodeHighestModSeq) CodeString added in v0.0.6 

func (c CodeHighestModSeq) CodeString() string

type CodeList 

type CodeList struct {
	Code string
	Args []string // If nil, no list was present. List can also be empty.
}

CodeList is a code with a list with space-separated strings as parameters. E.g. BADCHARSET, PERMANENTFLAGS.

func (CodeList) CodeString 

func (c CodeList) CodeString() string

type CodeModified added in v0.0.6 

type CodeModified NumSet

For CONDSTORE.

func (CodeModified) CodeString added in v0.0.6 

func (c CodeModified) CodeString() string

type CodeOther 

type CodeOther struct {
	Code string
	Args []string
}

CodeOther is a valid but unrecognized response code.

func (CodeOther) CodeString 

func (c CodeOther) CodeString() string

type CodeUint 

type CodeUint struct {
	Code string
	Num  uint32
}

CodeUint is a code with a uint32 parameter, e.g. UIDNEXT and UIDVALIDITY.

func (CodeUint) CodeString 

func (c CodeUint) CodeString() string

type CodeWords 

type CodeWords struct {
	Code string
	Args []string
}

CodeWords is a code with space-separated string parameters. E.g. CAPABILITY.

func (CodeWords) CodeString 

func (c CodeWords) CodeString() string

type Conn 

type Conn struct {
	LastTag      string
	CapAvailable map[Capability]struct{} // Capabilities available at server, from CAPABILITY command or response code.
	CapEnabled   map[Capability]struct{} // Capabilities enabled through ENABLE command.
	// contains filtered or unexported fields
}

Conn is an IMAP connection to a server.

func New 

func New(conn net.Conn, xpanic bool) (client *Conn, rerr error)

New creates a new client on conn.

If xpanic is true, functions that would return an error instead panic. For parse errors, the resulting stack traces show typically show what was being parsed.

The initial untagged greeting response is read and must be "OK".

func (*Conn) Append 

func (c *Conn) Append(mailbox string, flags []string, received *time.Time, message []byte) (untagged []Untagged, result Result, rerr error)

Append adds message to mailbox with flags and optional receive time.

func (*Conn) AuthenticatePlain 

func (c *Conn) AuthenticatePlain(username, password string) (untagged []Untagged, result Result, rerr error)

Authenticate with plaintext password using AUTHENTICATE PLAIN.

func (*Conn) AuthenticateSCRAM 

func (c *Conn) AuthenticateSCRAM(method string, h func() hash.Hash, username, password string) (untagged []Untagged, result Result, rerr error)

Authenticate with SCRAM-SHA-256(-PLUS) or SCRAM-SHA-1(-PLUS). With SCRAM, the password is not exchanged in plaintext form, but only derived hashes are exchanged by both parties as proof of knowledge of password.

The PLUS variants bind the authentication exchange to the TLS connection, detecting MitM attacks.

func (*Conn) Capability 

func (c *Conn) Capability() (untagged []Untagged, result Result, rerr error)

Capability requests a list of capabilities from the server. They are returned in an UntaggedCapability response. The server also sends capabilities in initial server greeting, in the response code.

func (*Conn) Close 

func (c *Conn) Close() error

Close closes the connection without writing anything to the server. You may want to call Logout. Closing a connection with a mailbox with deleted message not yet expunged will not expunge those messages.

func (*Conn) CloseMailbox 

func (c *Conn) CloseMailbox() (untagged []Untagged, result Result, rerr error)

CloseMailbox closes the currently selected/active mailbox, permanently removing any messages marked with \Deleted.

func (*Conn) Commandf 

func (c *Conn) Commandf(tag string, format string, args ...any) (rerr error)

Commandf writes a free-form IMAP command to the server. If tag is empty, a next unique tag is assigned.

func (*Conn) Copy 

func (c *Conn) Copy(seqSet NumSet, dstMailbox string) (untagged []Untagged, result Result, rerr error)

Copy adds messages from the sequences in seqSet in the currently selected/active mailbox to dstMailbox.

func (*Conn) Create 

func (c *Conn) Create(mailbox string) (untagged []Untagged, result Result, rerr error)

Create makes a new mailbox on the server.

func (*Conn) Delete 

func (c *Conn) Delete(mailbox string) (untagged []Untagged, result Result, rerr error)

Delete removes an entire mailbox and its messages.

func (*Conn) Enable 

func (c *Conn) Enable(capabilities ...string) (untagged []Untagged, result Result, rerr error)

Enable enables capabilities for use with the connection, verifying the server has indeed enabled them.

func (*Conn) Examine 

func (c *Conn) Examine(mailbox string) (untagged []Untagged, result Result, rerr error)

Examine opens mailbox as active mailbox read-only.

func (*Conn) Expunge 

func (c *Conn) Expunge() (untagged []Untagged, result Result, rerr error)

Expunge removes messages marked as deleted for the selected mailbox.

func (*Conn) List 

func (c *Conn) List(pattern string) (untagged []Untagged, result Result, rerr error)

List lists mailboxes with the basic LIST syntax. Pattern can contain * (match any) or % (match any except hierarchy delimiter).

func (*Conn) ListFull 

func (c *Conn) ListFull(subscribedOnly bool, patterns ...string) (untagged []Untagged, result Result, rerr error)

ListFull lists mailboxes with the extended LIST syntax requesting all supported data. Pattern can contain * (match any) or % (match any except hierarchy delimiter).

func (*Conn) Login 

func (c *Conn) Login(username, password string) (untagged []Untagged, result Result, rerr error)

Login authenticates with username and password

func (*Conn) Logout 

func (c *Conn) Logout() (untagged []Untagged, result Result, rerr error)

Logout ends the IMAP session by writing a LOGOUT command. Close must still be called on this client to close the socket.

func (*Conn) Move 

func (c *Conn) Move(seqSet NumSet, dstMailbox string) (untagged []Untagged, result Result, rerr error)

Move moves messages from the sequences in seqSet in the currently selected/active mailbox to dstMailbox.

func (*Conn) Namespace 

func (c *Conn) Namespace() (untagged []Untagged, result Result, rerr error)

Namespace returns the hiearchy separator in an UntaggedNamespace response with personal/shared/other namespaces if present.

func (*Conn) Noop 

func (c *Conn) Noop() (untagged []Untagged, result Result, rerr error)

Noop does nothing on its own, but a server will return any pending untagged responses for new message delivery and changes to mailboxes.

func (*Conn) ReadContinuation 

func (c *Conn) ReadContinuation() (line string, untagged []Untagged, result Result, rerr error)

ReadContinuation reads a line. If it is a continuation, i.e. starts with a +, it is returned without leading "+ " and without trailing crlf. Otherwise, a command response is returned. A successfully read continuation can return an empty line. Callers should check rerr and result.Status being empty to check if a continuation was read.

func (*Conn) ReadUntagged 

func (c *Conn) ReadUntagged() (untagged Untagged, rerr error)

ReadUntagged reads a single untagged response line. Useful for reading lines from IDLE.

func (*Conn) Readline 

func (c *Conn) Readline() (line string, rerr error)

Readline reads a line, including CRLF. Used with IDLE and synchronous literals.

func (*Conn) Rename 

func (c *Conn) Rename(omailbox, nmailbox string) (untagged []Untagged, result Result, rerr error)

Rename changes the name of a mailbox and all its child mailboxes.

func (*Conn) Response 

func (c *Conn) Response() (untagged []Untagged, result Result, rerr error)

Response reads from the IMAP server until a tagged response line is found. The tag must be the same as the tag for the last written command. Result holds the status of the command. The caller must check if this the status is OK.

func (*Conn) ResponseOK 

func (c *Conn) ResponseOK() (untagged []Untagged, result Result, rerr error)

func (*Conn) Select 

func (c *Conn) Select(mailbox string) (untagged []Untagged, result Result, rerr error)

Select opens mailbox as active mailbox.

func (*Conn) Starttls 

func (c *Conn) Starttls(config *tls.Config) (untagged []Untagged, result Result, rerr error)

Starttls enables TLS on the connection with the STARTTLS command.

func (*Conn) Status 

func (c *Conn) Status(mailbox string) (untagged []Untagged, result Result, rerr error)

Status requests information about a mailbox, such as number of messages, size, etc.

func (*Conn) StoreFlagsAdd 

func (c *Conn) StoreFlagsAdd(seqset string, silent bool, flags ...string) (untagged []Untagged, result Result, rerr error)

StoreFlagsAdd is like StoreFlagsSet, but only adds flags, leaving current flags on the message intact.

func (*Conn) StoreFlagsClear 

func (c *Conn) StoreFlagsClear(seqset string, silent bool, flags ...string) (untagged []Untagged, result Result, rerr error)

StoreFlagsClear is like StoreFlagsSet, but only removes flags, leaving other flags on the message intact.

func (*Conn) StoreFlagsSet 

func (c *Conn) StoreFlagsSet(seqset string, silent bool, flags ...string) (untagged []Untagged, result Result, rerr error)

StoreFlagsSet stores a new set of flags for messages from seqset with the STORE command. If silent, no untagged responses with the updated flags will be sent by the server.

func (*Conn) Subscribe 

func (c *Conn) Subscribe(mailbox string) (untagged []Untagged, result Result, rerr error)

Subscribe marks a mailbox as subscribed. The mailbox does not have to exist. It is not an error if the mailbox is already subscribed.

func (*Conn) TLSConnectionState added in v0.0.9 

func (c *Conn) TLSConnectionState() *tls.ConnectionState

TLSConnectionState returns the TLS connection state if the connection uses TLS.

func (*Conn) Transactf 

func (c *Conn) Transactf(format string, args ...any) (untagged []Untagged, result Result, rerr error)

Transactf writes format and args as an IMAP command, using Commandf with an empty tag. I.e. format must not contain a tag. Transactf then reads a response using ReadResponse and checks the result status is OK.

func (*Conn) UIDCopy 

func (c *Conn) UIDCopy(uidSet NumSet, dstMailbox string) (untagged []Untagged, result Result, rerr error)

UIDCopy is like copy, but operates on UIDs.

func (*Conn) UIDExpunge 

func (c *Conn) UIDExpunge(uidSet NumSet) (untagged []Untagged, result Result, rerr error)

UIDExpunge is like expunge, but only removes messages matching uidSet.

func (*Conn) UIDMove 

func (c *Conn) UIDMove(uidSet NumSet, dstMailbox string) (untagged []Untagged, result Result, rerr error)

UIDMove is like move, but operates on UIDs.

func (*Conn) Unselect 

func (c *Conn) Unselect() (untagged []Untagged, result Result, rerr error)

Unselect closes the currently selected/active mailbox, but unlike CloseMailbox does not permanently remove any messages marked with \Deleted.

func (*Conn) Unsubscribe 

func (c *Conn) Unsubscribe(mailbox string) (untagged []Untagged, result Result, rerr error)

Unsubscribe marks a mailbox as unsubscribed.

func (*Conn) Write 

func (c *Conn) Write(buf []byte) (n int, rerr error)

Write writes directly to the connection. Write errors do take the connections panic mode into account, i.e. Write can panic.

func (*Conn) WriteSyncLiteral 

func (c *Conn) WriteSyncLiteral(s string) (rerr error)

WriteSyncLiteral first writes the synchronous literal size, then read the continuation "+" and finally writes the data.

func (*Conn) Writelinef 

func (c *Conn) Writelinef(format string, args ...any) (rerr error)

Writelinef writes the formatted format and args as a single line, adding CRLF. Used with IDLE and synchronous literals.

type Envelope 

type Envelope struct {
	Date                               string
	Subject                            string
	From, Sender, ReplyTo, To, CC, BCC []Address
	InReplyTo, MessageID               string
}

Envelope holds the basic email message fields.

type Error 

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

Error is a parse or other protocol error.

func (Error) Error 

func (e Error) Error() string

func (Error) Unwrap 

func (e Error) Unwrap() error

type EsearchDataExt 

type EsearchDataExt struct {
	Tag   string
	Value TaggedExtVal
}

Extended data in an ESEARCH response.

type FetchAttr 

type FetchAttr interface {
	Attr() string // Name of attribute.
}

FetchAttr represents a FETCH response attribute.

type FetchBinary 

type FetchBinary struct {
	RespAttr string
	Parts    []uint32 // Can be nil.
	Data     string
}

"BINARY" fetch response.

func (FetchBinary) Attr 

func (f FetchBinary) Attr() string

type FetchBinarySize 

type FetchBinarySize struct {
	RespAttr string
	Parts    []uint32
	Size     int64
}

"BINARY.SIZE" fetch response.

func (FetchBinarySize) Attr 

func (f FetchBinarySize) Attr() string

type FetchBody 

type FetchBody struct {
	// ../rfc/9051:6756 ../rfc/9051:6985
	RespAttr string
	Section  string // todo: parse more ../rfc/9051:6985
	Offset   int32
	Body     string
}

"BODY" fetch response.

func (FetchBody) Attr 

func (f FetchBody) Attr() string

type FetchBodystructure 

type FetchBodystructure struct {
	// ../rfc/9051:6355
	RespAttr string
	Body     any // BodyType*
}

"BODYSTRUCTURE" fetch response.

func (FetchBodystructure) Attr 

func (f FetchBodystructure) Attr() string

type FetchEnvelope 

type FetchEnvelope Envelope

"ENVELOPE" fetch response.

func (FetchEnvelope) Attr 

func (f FetchEnvelope) Attr() string

type FetchFlags 

type FetchFlags []string

"FLAGS" fetch response.

func (FetchFlags) Attr 

func (f FetchFlags) Attr() string

type FetchInternalDate 

type FetchInternalDate string // todo: parsed time

"INTERNALDATE" fetch response.

func (FetchInternalDate) Attr 

func (f FetchInternalDate) Attr() string

type FetchModSeq added in v0.0.6 

type FetchModSeq int64

"MODSEQ" fetch response.

func (FetchModSeq) Attr added in v0.0.6 

func (f FetchModSeq) Attr() string

type FetchRFC822 

type FetchRFC822 string

"RFC822" fetch response.

func (FetchRFC822) Attr 

func (f FetchRFC822) Attr() string

type FetchRFC822Header 

type FetchRFC822Header string

"RFC822.HEADER" fetch response.

func (FetchRFC822Header) Attr 

func (f FetchRFC822Header) Attr() string

type FetchRFC822Size 

type FetchRFC822Size int64

"RFC822.SIZE" fetch response.

func (FetchRFC822Size) Attr 

func (f FetchRFC822Size) Attr() string

type FetchRFC822Text 

type FetchRFC822Text string

"RFC82.TEXT" fetch response.

func (FetchRFC822Text) Attr 

func (f FetchRFC822Text) Attr() string

type FetchUID 

type FetchUID uint32

"UID" fetch response.

func (FetchUID) Attr 

func (f FetchUID) Attr() string

type MboxListExtendedItem 

type MboxListExtendedItem struct {
	// ../rfc/9051:6699
	Tag string
	Val TaggedExtVal
}

type NamespaceDescr 

type NamespaceDescr struct {
	// ../rfc/9051:6769
	Prefix    string
	Separator byte // If 0 then separator was absent.
	Exts      []NamespaceExtension
}

type NamespaceExtension 

type NamespaceExtension struct {
	// ../rfc/9051:6773
	Key    string
	Values []string
}

type NumRange 

type NumRange struct {
	First uint32  // 0 for "*".
	Last  *uint32 // Nil if absent, 0 for "*".
}

NumRange is a single number or range.

func (NumRange) String 

func (nr NumRange) String() string

type NumSet 

type NumSet struct {
	SearchResult bool // True if "$", in which case Ranges is irrelevant.
	Ranges       []NumRange
}

func ParseNumSet added in v0.0.6 

func ParseNumSet(s string) (ns NumSet, rerr error)

func (NumSet) IsZero 

func (ns NumSet) IsZero() bool

func (NumSet) String 

func (ns NumSet) String() string

type RespText 

type RespText struct {
	Code    string  // The first word between [] after the status.
	CodeArg CodeArg // Set if code has a parameter.
	More    string  // Any remaining text.
}

RespText represents a response line minus the leading tag.

type Result 

type Result struct {
	Status Status
	RespText
}

Result is the final response for a command, indicating success or failure.

type Status 

type Status string

Status is the tagged final result of a command. 

const (
	BAD Status = "BAD" // Syntax error.
	NO  Status = "NO"  // Command failed.
	OK  Status = "OK"  // Command succeeded.
)

type TaggedExtComp 

type TaggedExtComp struct {
	String string
	Comps  []TaggedExtComp // Used for both space-separated and ().
}

type TaggedExtVal 

type TaggedExtVal struct {
	// ../rfc/9051:7111
	Number *int64
	SeqSet *NumSet
	Comp   *TaggedExtComp // If SimpleNumber and SimpleSeqSet is nil, this is a Comp. But Comp is optional and can also be nil. Not great.
}

type Untagged 

type Untagged any

Untagged is a parsed untagged response. See types starting with Untagged. todo: make an interface that the untagged responses implement?

type UntaggedBye 

type UntaggedBye RespText

type UntaggedCapability 

type UntaggedCapability []string

type UntaggedEnabled 

type UntaggedEnabled []string

type UntaggedEsearch 

type UntaggedEsearch struct {
	// ../rfc/9051:6546
	Correlator string
	UID        bool
	Min        uint32
	Max        uint32
	All        NumSet
	Count      *uint32
	ModSeq     int64
	Exts       []EsearchDataExt
}

Fields are optional and zero if absent.

type UntaggedExists 

type UntaggedExists uint32

type UntaggedExpunge 

type UntaggedExpunge uint32

type UntaggedFetch 

type UntaggedFetch struct {
	Seq   uint32
	Attrs []FetchAttr
}

type UntaggedFlags 

type UntaggedFlags []string

type UntaggedID 

type UntaggedID map[string]string

type UntaggedList 

type UntaggedList struct {
	// ../rfc/9051:6690
	Flags     []string
	Separator byte // 0 for NIL
	Mailbox   string
	Extended  []MboxListExtendedItem
	OldName   string // If present, taken out of Extended.
}

type UntaggedLsub 

type UntaggedLsub struct {
	// ../rfc/3501:4833
	Flags     []string
	Separator byte
	Mailbox   string
}

type UntaggedNamespace 

type UntaggedNamespace struct {
	Personal, Other, Shared []NamespaceDescr
}

type UntaggedPreauth 

type UntaggedPreauth RespText

type UntaggedRecent 

type UntaggedRecent uint32

type UntaggedResult 

type UntaggedResult Result

type UntaggedSearch 

type UntaggedSearch []uint32

type UntaggedSearchModSeq added in v0.0.6 

type UntaggedSearchModSeq struct {
	Nums   []uint32
	ModSeq int64
}

../rfc/7162:1101

type UntaggedStatus 

type UntaggedStatus struct {
	Mailbox string
	Attrs   map[string]int64 // Upper case status attributes. ../rfc/9051:7059
}

type UntaggedVanished added in v0.0.6 

type UntaggedVanished struct {
	Earlier bool
	UIDs    NumSet
}

UntaggedVanished is used in QRESYNC to send UIDs that have been removed.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.