imap package - github.com/emersion/go-imap/v2 - Go Packages (original) (raw)

Package imap implements IMAP4rev2.

IMAP4rev2 is defined in RFC 9051.

This package contains types and functions common to both the client and server. See the imapclient and imapserver sub-packages.

View Source

const (

RightLookup     = [Right](#Right)('l') 
RightRead       = [Right](#Right)('r') 
RightSeen       = [Right](#Right)('s') 
RightWrite      = [Right](#Right)('w') 
RightInsert     = [Right](#Right)('i') 
RightPost       = [Right](#Right)('p') 
RightCreate     = [Right](#Right)('c') 
RightDelete     = [Right](#Right)('d') 
RightAdminister = [Right](#Right)('a')

)

View Source

const ( RightModificationReplace = RightModification(0) RightModificationAdd = RightModification('+') RightModificationRemove = RightModification('-') )

RightsIdentifierAnyone is the universal identity (matches everyone).

RightSetAll contains all standard rights.

func IsSearchRes(numSet NumSet) bool

IsSearchRes checks whether a sequence set is a reference to the last SEARCH result. See SearchRes.

Address represents a sender or recipient of a message.

Addr returns the e-mail address in the form "foo@example.org".

If the address is a start or end of group, the empty string is returned.

func (addr *Address) IsGroupEnd() bool

IsGroupEnd returns true if this address is a end of group marker.

func (addr *Address) IsGroupStart() bool

IsGroupStart returns true if this address is a start of group marker.

In that case, Mailbox contains the group name phrase.

type AppendData struct {

UID         [UID](#UID)
UIDValidity [uint32](/builtin#uint32)

}

AppendData is the data returned by an APPEND command.

type AppendOptions struct { Flags []Flag Time time.Time }

AppendOptions contains options for the APPEND command.

type BodyStructure

type BodyStructure interface {

MediaType() [string](/builtin#string)


Walk(f [BodyStructureWalkFunc](#BodyStructureWalkFunc))

Disposition() *[BodyStructureDisposition](#BodyStructureDisposition)

}

BodyStructure describes the body structure of a message.

A BodyStructure value is either a *BodyStructureSinglePart or a *BodyStructureMultiPart.

type BodyStructureDisposition

BodyStructureDisposition describes the content disposition of a part (specified in the Content-Disposition header field).

type BodyStructureMessageRFC822

type BodyStructureMessageRFC822 struct { Envelope *Envelope BodyStructure BodyStructure NumLines int64 }

BodyStructureMessageRFC822 contains metadata specific to RFC 822 parts for BodyStructureSinglePart.

type BodyStructureMultiPart

type BodyStructureMultiPart struct { Children []BodyStructure Subtype string

Extended *[BodyStructureMultiPartExt](#BodyStructureMultiPartExt)

}

BodyStructureMultiPart is a body structure with multiple parts.

func (*BodyStructureMultiPart) Walk

type BodyStructureSinglePart

BodyStructureSinglePart is a body structure with a single part.

func (*BodyStructureSinglePart) Filename

Filename decodes the body structure's filename, if any.

func (*BodyStructureSinglePart) Walk

type BodyStructureSinglePartExt

type BodyStructureSinglePartExt struct { Disposition *BodyStructureDisposition Language []string Location string }

BodyStructureSinglePartExt contains extended body structure data for BodyStructureSinglePart.

type BodyStructureText

type BodyStructureText struct { NumLines int64 }

BodyStructureText contains metadata specific to text parts for BodyStructureSinglePart.

type BodyStructureWalkFunc

type BodyStructureWalkFunc func(path []int, part BodyStructure) (walkChildren bool)

BodyStructureWalkFunc is a function called for each body structure visited by BodyStructure.Walk.

The path argument contains the IMAP part path.

The function should return true to visit all of the part's children or false to skip them.

Cap represents an IMAP capability.

const ( CapIMAP4rev1 Cap = "IMAP4rev1" CapIMAP4rev2 Cap = "IMAP4rev2" 

CapStartTLS      [Cap](#Cap) = "STARTTLS"
CapLoginDisabled [Cap](#Cap) = "LOGINDISABLED"


CapNamespace    [Cap](#Cap) = "NAMESPACE"     
CapUnselect     [Cap](#Cap) = "UNSELECT"      
CapUIDPlus      [Cap](#Cap) = "UIDPLUS"       
CapESearch      [Cap](#Cap) = "ESEARCH"       
CapSearchRes    [Cap](#Cap) = "SEARCHRES"     
CapEnable       [Cap](#Cap) = "ENABLE"        
CapIdle         [Cap](#Cap) = "IDLE"          
CapSASLIR       [Cap](#Cap) = "SASL-IR"       
CapListExtended [Cap](#Cap) = "LIST-EXTENDED" 
CapListStatus   [Cap](#Cap) = "LIST-STATUS"   
CapMove         [Cap](#Cap) = "MOVE"          
CapLiteralMinus [Cap](#Cap) = "LITERAL-"      
CapStatusSize   [Cap](#Cap) = "STATUS=SIZE"   
CapChildren     [Cap](#Cap) = "CHILDREN"      

CapACL              [Cap](#Cap) = "ACL"                
CapAppendLimit      [Cap](#Cap) = "APPENDLIMIT"        
CapBinary           [Cap](#Cap) = "BINARY"             
CapCatenate         [Cap](#Cap) = "CATENATE"           
CapCondStore        [Cap](#Cap) = "CONDSTORE"          
CapConvert          [Cap](#Cap) = "CONVERT"            
CapCreateSpecialUse [Cap](#Cap) = "CREATE-SPECIAL-USE" 
CapESort            [Cap](#Cap) = "ESORT"              
CapFilters          [Cap](#Cap) = "FILTERS"            
CapID               [Cap](#Cap) = "ID"                 
CapLanguage         [Cap](#Cap) = "LANGUAGE"           
CapListMyRights     [Cap](#Cap) = "LIST-MYRIGHTS"      
CapLiteralPlus      [Cap](#Cap) = "LITERAL+"           
CapLoginReferrals   [Cap](#Cap) = "LOGIN-REFERRALS"    
CapMailboxReferrals [Cap](#Cap) = "MAILBOX-REFERRALS"  
CapMetadata         [Cap](#Cap) = "METADATA"           
CapMetadataServer   [Cap](#Cap) = "METADATA-SERVER"    
CapMultiAppend      [Cap](#Cap) = "MULTIAPPEND"        
CapMultiSearch      [Cap](#Cap) = "MULTISEARCH"        
CapNotify           [Cap](#Cap) = "NOTIFY"             
CapObjectID         [Cap](#Cap) = "OBJECTID"           
CapPreview          [Cap](#Cap) = "PREVIEW"            
CapQResync          [Cap](#Cap) = "QRESYNC"            
CapQuota            [Cap](#Cap) = "QUOTA"              
CapQuotaSet         [Cap](#Cap) = "QUOTASET"           
CapReplace          [Cap](#Cap) = "REPLACE"            
CapSaveDate         [Cap](#Cap) = "SAVEDATE"           
CapSearchFuzzy      [Cap](#Cap) = "SEARCH=FUZZY"       
CapSort             [Cap](#Cap) = "SORT"               
CapSortDisplay      [Cap](#Cap) = "SORT=DISPLAY"       
CapSpecialUse       [Cap](#Cap) = "SPECIAL-USE"        
CapUnauthenticate   [Cap](#Cap) = "UNAUTHENTICATE"     
CapURLPartial       [Cap](#Cap) = "URL-PARTIAL"        
CapURLAuth          [Cap](#Cap) = "URLAUTH"            
CapUTF8Accept       [Cap](#Cap) = "UTF8=ACCEPT"        
CapUTF8Only         [Cap](#Cap) = "UTF8=ONLY"          
CapWithin           [Cap](#Cap) = "WITHIN"             
CapUIDOnly          [Cap](#Cap) = "UIDONLY"            
CapListMetadata     [Cap](#Cap) = "LIST-METADATA"      
CapInProgress       [Cap](#Cap) = "INPROGRESS"

)

Registered capabilities.

See: https://www.iana.org/assignments/imap-capabilities/

AuthCap returns the capability name for an SASL authentication mechanism.

type CapSet map[Cap]struct{}

CapSet is a set of capabilities.

AppendLimit checks the APPENDLIMIT capability.

If the server supports APPENDLIMIT, ok is true. If the server doesn't have the same upload limit for all mailboxes, limit is nil and per-mailbox limits must be queried via STATUS.

func (set CapSet) AuthMechanisms() []string

AuthMechanisms returns the list of supported SASL mechanisms for authentication.

func (set CapSet) Copy() CapSet

Has checks whether a capability is supported.

Some capabilities are implied by others, as such Has may return true even if the capability is not in the map.

func (set CapSet) QuotaResourceTypes() []QuotaResourceType

QuotaResourceTypes returns the list of supported QUOTA resource types.

func (set CapSet) ThreadAlgorithms() []ThreadAlgorithm

ThreadAlgorithms returns the list of supported threading algorithms.

ConnState describes the connection state.

See RFC 9051 section 3.

const ( ConnStateNone ConnState = iota ConnStateNotAuthenticated ConnStateAuthenticated ConnStateSelected ConnStateLogout )

String implements fmt.Stringer.

type CopyData struct {

UIDValidity [uint32](/builtin#uint32)
SourceUIDs  [UIDSet](#UIDSet)
DestUIDs    [UIDSet](#UIDSet)

}

CopyData is the data returned by a COPY command.

type CreateOptions struct { SpecialUse []MailboxAttr }

CreateOptions contains options for the CREATE command.

Envelope is the envelope structure of a message.

The subject and addresses are UTF-8 (ie, not in their encoded form). The In-Reply-To and Message-ID values contain message identifiers without angle brackets.

type Error StatusResponse

Error is an IMAP error caused by a status response.

Error implements the error interface.

type FetchItemBinarySection struct { Part []int Partial *SectionPartial Peek bool }

FetchItemBinarySection is a FETCH BINARY[] data item.

type FetchItemBinarySectionSize struct { Part []int }

FetchItemBinarySectionSize is a FETCH BINARY.SIZE[] data item.

type FetchItemBodySection

type FetchItemBodySection struct { Specifier PartSpecifier Part []int HeaderFields []string HeaderFieldsNot []string Partial *SectionPartial Peek bool }

FetchItemBodySection is a FETCH BODY[] data item.

To fetch the whole body of a message, use the zero FetchItemBodySection:

imap.FetchItemBodySection{}

To fetch only a specific part, use the Part field:

imap.FetchItemBodySection{Part: []int{1, 2, 3}}

To fetch only the header of the message, use the Specifier field:

imap.FetchItemBodySection{Specifier: imap.PartSpecifierHeader}

type FetchItemBodyStructure

type FetchItemBodyStructure struct { Extended bool }

FetchItemBodyStructure contains FETCH options for the body structure.

type FetchOptions struct {

BodyStructure     *[FetchItemBodyStructure](#FetchItemBodyStructure)
Envelope          [bool](/builtin#bool)
Flags             [bool](/builtin#bool)
InternalDate      [bool](/builtin#bool)
RFC822Size        [bool](/builtin#bool)
UID               [bool](/builtin#bool)
BodySection       []*[FetchItemBodySection](#FetchItemBodySection)
BinarySection     []*[FetchItemBinarySection](#FetchItemBinarySection)     
BinarySectionSize []*[FetchItemBinarySectionSize](#FetchItemBinarySectionSize) 
ModSeq            [bool](/builtin#bool)                          

ChangedSince [uint64](/builtin#uint64)

}

FetchOptions contains options for the FETCH command.

Flag is a message flag.

Message flags are defined in RFC 9051 section 2.3.2.

const (

FlagSeen     [Flag](#Flag) = "\\Seen"
FlagAnswered [Flag](#Flag) = "\\Answered"
FlagFlagged  [Flag](#Flag) = "\\Flagged"
FlagDeleted  [Flag](#Flag) = "\\Deleted"
FlagDraft    [Flag](#Flag) = "\\Draft"


FlagForwarded [Flag](#Flag) = "$Forwarded"
FlagMDNSent   [Flag](#Flag) = "$MDNSent" 
FlagJunk      [Flag](#Flag) = "$Junk"
FlagNotJunk   [Flag](#Flag) = "$NotJunk"
FlagPhishing  [Flag](#Flag) = "$Phishing"
FlagImportant [Flag](#Flag) = "$Important" 


FlagWildcard [Flag](#Flag) = "\\*"

)

ListData is the mailbox data returned by a LIST command.

type ListDataChildInfo struct { Subscribed bool }

type ListOptions struct { SelectSubscribed bool SelectRemote bool SelectRecursiveMatch bool SelectSpecialUse bool 

ReturnSubscribed [bool](/builtin#bool)
ReturnChildren   [bool](/builtin#bool)
ReturnStatus     *[StatusOptions](#StatusOptions) 
ReturnSpecialUse [bool](/builtin#bool)

}

ListOptions contains options for the LIST command.

LiteralReader is a reader for IMAP literals.

MailboxAttr is a mailbox attribute.

Mailbox attributes are defined in RFC 9051 section 7.3.1.

const (

MailboxAttrNonExistent   [MailboxAttr](#MailboxAttr) = "\\NonExistent"
MailboxAttrNoInferiors   [MailboxAttr](#MailboxAttr) = "\\Noinferiors"
MailboxAttrNoSelect      [MailboxAttr](#MailboxAttr) = "\\Noselect"
MailboxAttrHasChildren   [MailboxAttr](#MailboxAttr) = "\\HasChildren"
MailboxAttrHasNoChildren [MailboxAttr](#MailboxAttr) = "\\HasNoChildren"
MailboxAttrMarked        [MailboxAttr](#MailboxAttr) = "\\Marked"
MailboxAttrUnmarked      [MailboxAttr](#MailboxAttr) = "\\Unmarked"
MailboxAttrSubscribed    [MailboxAttr](#MailboxAttr) = "\\Subscribed"
MailboxAttrRemote        [MailboxAttr](#MailboxAttr) = "\\Remote"


MailboxAttrAll       [MailboxAttr](#MailboxAttr) = "\\All"
MailboxAttrArchive   [MailboxAttr](#MailboxAttr) = "\\Archive"
MailboxAttrDrafts    [MailboxAttr](#MailboxAttr) = "\\Drafts"
MailboxAttrFlagged   [MailboxAttr](#MailboxAttr) = "\\Flagged"
MailboxAttrJunk      [MailboxAttr](#MailboxAttr) = "\\Junk"
MailboxAttrSent      [MailboxAttr](#MailboxAttr) = "\\Sent"
MailboxAttrTrash     [MailboxAttr](#MailboxAttr) = "\\Trash"
MailboxAttrImportant [MailboxAttr](#MailboxAttr) = "\\Important"

)

type NamespaceData struct { Personal []NamespaceDescriptor Other []NamespaceDescriptor Shared []NamespaceDescriptor }

NamespaceData is the data returned by the NAMESPACE command.

type NamespaceDescriptor struct { Prefix string Delim rune }

NamespaceDescriptor describes a namespace.

type NumSet interface {

String() [string](/builtin#string)


Dynamic() [bool](/builtin#bool)

}

NumSet is a set of numbers identifying messages. NumSet is either a SeqSet or a UIDSet.

PartSpecifier describes whether to fetch a part's header, body, or both.

const ( PartSpecifierNone PartSpecifier = "" PartSpecifierMIME PartSpecifier = "MIME" PartSpecifierText PartSpecifier = "TEXT" )

QuotaResourceType is a QUOTA resource type.

See RFC 9208 section 5.

const ( QuotaResourceStorage QuotaResourceType = "STORAGE" QuotaResourceMessage QuotaResourceType = "MESSAGE" QuotaResourceMailbox QuotaResourceType = "MAILBOX" QuotaResourceAnnotationStorage QuotaResourceType = "ANNOTATION-STORAGE" )

type RenameOptions struct{}

RenameOptions contains options for the RENAME command.

ResponseCode is a response code.

const ( ResponseCodeAlert ResponseCode = "ALERT" ResponseCodeAlreadyExists ResponseCode = "ALREADYEXISTS" ResponseCodeAuthenticationFailed ResponseCode = "AUTHENTICATIONFAILED" ResponseCodeBadCharset ResponseCode = "BADCHARSET" ResponseCodeCannot ResponseCode = "CANNOT" ResponseCodeClientBug ResponseCode = "CLIENTBUG" ResponseCodeContactAdmin ResponseCode = "CONTACTADMIN" ResponseCodeCorruption ResponseCode = "CORRUPTION" ResponseCodeExpired ResponseCode = "EXPIRED" ResponseCodeHasChildren ResponseCode = "HASCHILDREN" ResponseCodeInUse ResponseCode = "INUSE" ResponseCodeLimit ResponseCode = "LIMIT" ResponseCodeNonExistent ResponseCode = "NONEXISTENT" ResponseCodeNoPerm ResponseCode = "NOPERM" ResponseCodeOverQuota ResponseCode = "OVERQUOTA" ResponseCodeParse ResponseCode = "PARSE" ResponseCodePrivacyRequired ResponseCode = "PRIVACYREQUIRED" ResponseCodeServerBug ResponseCode = "SERVERBUG" ResponseCodeTryCreate ResponseCode = "TRYCREATE" ResponseCodeUnavailable ResponseCode = "UNAVAILABLE" ResponseCodeUnknownCTE ResponseCode = "UNKNOWN-CTE"

ResponseCodeTooMany   [ResponseCode](#ResponseCode) = "TOOMANY"
ResponseCodeNoPrivate [ResponseCode](#ResponseCode) = "NOPRIVATE"


ResponseCodeTooBig [ResponseCode](#ResponseCode) = "TOOBIG"

)

Right describes a set of operations controlled by the IMAP ACL extension.

type RightModification byte

RightModification indicates how to mutate a right set.

A RightSet is a set of rights.

func (r RightSet) Add(rights RightSet) RightSet

Add returns a new right set containing rights from both sets.

func (rs1 RightSet) Equal(rs2 RightSet) bool

Equal returns true if both right sets contain exactly the same rights.

func (r RightSet) Remove(rights RightSet) RightSet

Remove returns a new right set containing all rights in r except these in the provided set.

String returns a string representation of the right set.

RightsIdentifier is an ACL identifier.

NewRightsIdentifierUsername returns a rights identifier referring to a username, checking for reserved values.

SearchCriteria is a criteria for the SEARCH command.

When multiple fields are populated, the result is the intersection ("and" function) of all messages that match the fields.

And, Not and Or can be used to combine multiple criteria together. For instance, the following criteria matches messages not containing "hello":

SearchCriteria{Not: []SearchCriteria{{ Body: []string{"hello"}, }}}

The following criteria matches messages containing either "hello" or "world":

SearchCriteria{Or: [][2]SearchCriteria{{ {Body: []string{"hello"}}, {Body: []string{"world"}}, }}}

func (*SearchCriteria) And

func (criteria *SearchCriteria) And(other *SearchCriteria)

And intersects two search criteria.

type SearchCriteriaHeaderField struct {

type SearchCriteriaMetadataType string

const ( SearchCriteriaMetadataAll SearchCriteriaMetadataType = "all" SearchCriteriaMetadataPrivate SearchCriteriaMetadataType = "priv" SearchCriteriaMetadataShared SearchCriteriaMetadataType = "shared" )

type SearchCriteriaModSeq struct { ModSeq uint64 MetadataName string MetadataType SearchCriteriaMetadataType }

SearchData is the data returned by a SEARCH command.

func (data *SearchData) AllSeqNums() []uint32

AllSeqNums returns All as a slice of sequence numbers.

func (data *SearchData) AllUIDs() []UID

AllUIDs returns All as a slice of UIDs.

type SearchOptions struct {

ReturnMin   [bool](/builtin#bool)
ReturnMax   [bool](/builtin#bool)
ReturnAll   [bool](/builtin#bool)
ReturnCount [bool](/builtin#bool)

ReturnSave [bool](/builtin#bool)

}

SearchOptions contains options for the SEARCH command.

type SectionPartial struct { Offset, Size int64 }

SectionPartial describes a byte range when fetching a message's payload.

type SelectData struct {

Flags [][Flag](#Flag)

PermanentFlags [][Flag](#Flag)

NumMessages [uint32](/builtin#uint32)


FirstUnseenSeqNum [uint32](/builtin#uint32)


NumRecent   [uint32](/builtin#uint32)
UIDNext     [UID](#UID)
UIDValidity [uint32](/builtin#uint32)

List *[ListData](#ListData) 

HighestModSeq [uint64](/builtin#uint64)

}

SelectData is the data returned by a SELECT command.

In the old RFC 2060, PermanentFlags, UIDNext and UIDValidity are optional.

type SelectOptions struct { ReadOnly bool CondStore bool }

SelectOptions contains options for the SELECT or EXAMINE command.

type SeqRange struct { Start, Stop uint32 }

SeqRange is a range of message sequence numbers.

SeqSet is a set of message sequence numbers.

SeqSetNum returns a new SeqSet containing the specified sequence numbers.

func (s *SeqSet) AddNum(nums ...uint32)

AddNum inserts new sequence numbers into the set. The value 0 represents "*".

func (s *SeqSet) AddRange(start, stop uint32)

AddRange inserts a new range into the set.

func (s *SeqSet) AddSet(other SeqSet)

AddSet inserts all sequence numbers from other into s.

Contains returns true if the non-zero sequence number num is contained in the set.

func (s SeqSet) Dynamic() bool

Nums returns a slice of all sequence numbers contained in the set.

StatusData is the data returned by a STATUS command.

The mailbox name is always populated. The remaining fields are optional.

StatusOptions contains options for the STATUS command.

type StatusResponseType string

StatusResponseType is a generic status response type.

const ( StatusResponseTypeOK StatusResponseType = "OK" StatusResponseTypeNo StatusResponseType = "NO" StatusResponseTypeBad StatusResponseType = "BAD" StatusResponseTypePreAuth StatusResponseType = "PREAUTH" StatusResponseTypeBye StatusResponseType = "BYE" )

type StoreFlags struct { Op StoreFlagsOp Silent bool Flags []Flag }

StoreFlags alters message flags.

StoreFlagsOp is a flag operation: set, add or delete.

const ( StoreFlagsSet StoreFlagsOp = iota StoreFlagsAdd StoreFlagsDel )

type StoreOptions struct { UnchangedSince uint64 }

StoreOptions contains options for the STORE command.

ThreadAlgorithm is a threading algorithm.

const ( ThreadOrderedSubject ThreadAlgorithm = "ORDEREDSUBJECT" ThreadReferences ThreadAlgorithm = "REFERENCES" )

UID is a message unique identifier.

type UIDRange struct { Start, Stop UID }

UIDRange is a range of message UIDs.

UIDSet is a set of message UIDs.

SearchRes returns a special marker which can be used instead of a UIDSet to reference the last SEARCH result. On the wire, it's encoded as '$'.

It requires IMAP4rev2 or the SEARCHRES extension.

func UIDSetNum(uids ...UID) UIDSet

UIDSetNum returns a new UIDSet containing the specified UIDs.

func (s *UIDSet) AddNum(uids ...UID)

AddNum inserts new UIDs into the set. The value 0 represents "*".

func (s *UIDSet) AddRange(start, stop UID)

AddRange inserts a new range into the set.

func (s *UIDSet) AddSet(other UIDSet)

AddSet inserts all UIDs from other into s.

func (s UIDSet) Contains(uid UID) bool

Contains returns true if the non-zero UID uid is contained in the set.

func (s UIDSet) Dynamic() bool

func (s UIDSet) Nums() ([]UID, bool)

Nums returns a slice of all UIDs contained in the set.