Documentation
¶
Overview ¶
Package imap implements IMAP4rev1 (RFC 3501).
Index ¶
- Constants
- Variables
- func CanonicalFlag(flag string) string
- func CanonicalMailboxName(name string) string
- func FormatAddressList(addrs []*Address) (fields []interface{})
- func FormatParamList(params map[string]string) []interface{}
- func FormatStringList(list []string) (fields []interface{})
- func IsParseError(err error) bool
- func NewDebugWriter(local, remote io.Writer) io.Writer
- func ParseNamedResp(resp Resp) (name string, fields []interface{}, ok bool)
- func ParseNumber(f interface{}) (uint32, error)
- func ParseParamList(fields []interface{}) (map[string]string, error)
- func ParseString(f interface{}) (string, error)
- func ParseStringList(f interface{}) ([]string, error)
- type Address
- type Atom
- type BodyPartName
- type BodySectionName
- type BodyStructure
- type Command
- type Commander
- type Conn
- type ConnState
- type ConnUpgrader
- type ContinuationReq
- type DataResp
- type Date
- type DateTime
- type Envelope
- type ErrBadSeqSet
- type FetchItem
- type FlagsOp
- type Literal
- type Logger
- type MailboxInfo
- type MailboxStatus
- type Message
- type Parser
- type PartSpecifier
- type Quoted
- type Reader
- func (r *Reader) ReadAtom() (interface{}, error)
- func (r *Reader) ReadCrlf() (err error)
- func (r *Reader) ReadFields() (fields []interface{}, err error)
- func (r *Reader) ReadInfo() (info string, err error)
- func (r *Reader) ReadLine() (fields []interface{}, err error)
- func (r *Reader) ReadList() (fields []interface{}, err error)
- func (r *Reader) ReadLiteral() (Literal, error)
- func (r *Reader) ReadQuotedString() (string, error)
- func (r *Reader) ReadRespCode() (code StatusRespCode, fields []interface{}, err error)
- func (r *Reader) ReadSp() error
- type Resp
- type SearchCriteria
- type Seq
- type SeqSet
- func (s *SeqSet) Add(set string) error
- func (s *SeqSet) AddNum(q ...uint32)
- func (s *SeqSet) AddRange(Start, Stop uint32)
- func (s *SeqSet) AddSet(t *SeqSet)
- func (s *SeqSet) Clear()
- func (s SeqSet) Contains(q uint32) bool
- func (s SeqSet) Dynamic() bool
- func (s SeqSet) Empty() bool
- func (s SeqSet) String() string
- type StatusItem
- type StatusResp
- type StatusRespCode
- type StatusRespType
- type StoreItem
- type StringReader
- type Writer
- type WriterTo
Constants ¶
const ( // In the connecting state, the server has not yet sent a greeting and no // command can be issued. ConnectingState = 0 // In the not authenticated state, the client MUST supply // authentication credentials before most commands will be // permitted. This state is entered when a connection starts // unless the connection has been pre-authenticated. NotAuthenticatedState ConnState = 1 << 0 // In the authenticated state, the client is authenticated and MUST // select a mailbox to access before commands that affect messages // will be permitted. This state is entered when a // pre-authenticated connection starts, when acceptable // authentication credentials have been provided, after an error in // selecting a mailbox, or after a successful CLOSE command. AuthenticatedState = 1 << 1 // In a selected state, a mailbox has been selected to access. // This state is entered when a mailbox has been successfully // selected. SelectedState = AuthenticatedState + 1<<2 // In the logout state, the connection is being terminated. This // state can be entered as a result of a client request (via the // LOGOUT command) or by unilateral action on the part of either // the client or server. LogoutState = 1 << 3 // ConnectedState is either NotAuthenticatedState, AuthenticatedState or // SelectedState. ConnectedState = NotAuthenticatedState | AuthenticatedState | SelectedState )
const ( // Defined in RFC 3501 as date-text on page 83. DateLayout = "_2-Jan-2006" // Defined in RFC 3501 as date-time on page 83. DateTimeLayout = "_2-Jan-2006 15:04:05 -0700" )
Date and time layouts. Dovecot adds a leading zero to dates:
https://github.com/dovecot/core/blob/4fbd5c5e113078e72f29465ccc96d44955ceadc2/src/lib-imap/imap-date.c#L166
Cyrus adds a leading space to dates:
https://github.com/cyrusimap/cyrus-imapd/blob/1cb805a3bffbdf829df0964f3b802cdc917e76db/lib/times.c#L543
GMail doesn't support leading spaces in dates used in SEARCH commands.
const ( StatusMessages StatusItem = "MESSAGES" StatusRecent = "RECENT" StatusUidNext = "UIDNEXT" StatusUidValidity = "UIDVALIDITY" StatusUnseen = "UNSEEN" )
const ( // Macros FetchAll FetchItem = "ALL" FetchFast = "FAST" FetchFull = "FULL" // Items FetchBody = "BODY" FetchBodyStructure = "BODYSTRUCTURE" FetchEnvelope = "ENVELOPE" FetchFlags = "FLAGS" FetchInternalDate = "INTERNALDATE" FetchRFC822 = "RFC822" FetchRFC822Header = "RFC822.HEADER" FetchRFC822Size = "RFC822.SIZE" FetchRFC822Text = "RFC822.TEXT" FetchUid = "UID" )
List of items that can be fetched.
const ( // SetFlags replaces existing flags by new ones. SetFlags FlagsOp = "FLAGS" // AddFlags adds new flags. AddFlags = "+FLAGS" // RemoveFlags removes existing flags. RemoveFlags = "-FLAGS" )
const ( // It is not possible for any child levels of hierarchy to exist under this\ // name; no child levels exist now and none can be created in the future. NoInferiorsAttr = "\\Noinferiors" // It is not possible to use this name as a selectable mailbox. NoSelectAttr = "\\Noselect" // The mailbox has been marked "interesting" by the server; the mailbox // probably contains messages that have been added since the last time the // mailbox was selected. MarkedAttr = "\\Marked" // The mailbox does not contain any additional messages since the last time // the mailbox was selected. UnmarkedAttr = "\\Unmarked" )
Mailbox attributes definied in RFC 3501 section 7.2.2.
const ( SeenFlag = "\\Seen" AnsweredFlag = "\\Answered" FlaggedFlag = "\\Flagged" DeletedFlag = "\\Deleted" DraftFlag = "\\Draft" RecentFlag = "\\Recent" )
Message flags, defined in RFC 3501 section 2.3.2.
const ( // Refers to the entire part, including headers. EntireSpecifier PartSpecifier = "" // Refers to the header of the part. Must include the final CRLF delimiting // the header and the body. HeaderSpecifier = "HEADER" // Refers to the text body of the part, omitting the header. TextSpecifier = "TEXT" // Refers to the MIME Internet Message Body header. Must include the final // CRLF delimiting the header and the body. MIMESpecifier = "MIME" )
Part specifiers described in RFC 3501 page 55.
const ( // The OK response indicates an information message from the server. When // tagged, it indicates successful completion of the associated command. // The untagged form indicates an information-only message. StatusRespOk StatusRespType = "OK" // The NO response indicates an operational error message from the // server. When tagged, it indicates unsuccessful completion of the // associated command. The untagged form indicates a warning; the // command can still complete successfully. StatusRespNo = "NO" // The BAD response indicates an error message from the server. When // tagged, it reports a protocol-level error in the client's command; // the tag indicates the command that caused the error. The untagged // form indicates a protocol-level error for which the associated // command can not be determined; it can also indicate an internal // server failure. StatusRespBad = "BAD" // The PREAUTH response is always untagged, and is one of three // possible greetings at connection startup. It indicates that the // connection has already been authenticated by external means; thus // no LOGIN command is needed. StatusRespPreauth = "PREAUTH" // The BYE response is always untagged, and indicates that the server // is about to close the connection. StatusRespBye = "BYE" )
Status response types defined in RFC 3501 section 7.1.
const ( CodeAlert StatusRespCode = "ALERT" CodeBadCharset = "BADCHARSET" CodeCapability = "CAPABILITY" CodeParse = "PARSE" CodePermanentFlags = "PERMANENTFLAGS" CodeReadOnly = "READ-ONLY" CodeReadWrite = "READ-WRITE" CodeTryCreate = "TRYCREATE" CodeUidNext = "UIDNEXT" CodeUidValidity = "UIDVALIDITY" CodeUnseen = "UNSEEN" )
Status response codes defined in RFC 3501 section 7.1.
const InboxName = "INBOX"
The primary mailbox, as defined in RFC 3501 section 5.1.
Variables ¶
CharsetReader, if non-nil, defines a function to generate charset-conversion readers, converting from the provided charset into UTF-8. Charsets are always lower-case. utf-8 and us-ascii charsets are handled by default. One of the the CharsetReader's result values must be non-nil.
Functions ¶
func CanonicalFlag ¶
Returns the canonical form of a flag. Flags are case-insensitive.
If the flag is defined in RFC 3501, it returns the flag with the case of the RFC. Otherwise, it returns the lowercase version of the flag.
func CanonicalMailboxName ¶
Returns the canonical form of a mailbox name. Mailbox names can be case-sensitive or case-insensitive depending on the backend implementation. The special INBOX mailbox is case-insensitive.
func FormatAddressList ¶
func FormatAddressList(addrs []*Address) (fields []interface{})
Format an address list to fields.
func FormatParamList ¶
func FormatStringList ¶
func FormatStringList(list []string) (fields []interface{})
Convert a string list to a field list.
func IsParseError ¶
IsParseError returns true if the provided error is a parse error produced by Reader.
func NewDebugWriter ¶
NewDebugWriter creates a new io.Writer that will write local network activity to local and remote network activity to remote.
func ParseNamedResp ¶
ParseNamedResp attempts to parse a named data response.
func ParseParamList ¶
func ParseString ¶
ParseString parses a string, which is either a literal, a quoted string or an atom.
func ParseStringList ¶
Convert a field list to a string list.
Types ¶
type Address ¶
type Address struct {
// The personal name.
PersonalName string
// The SMTP at-domain-list (source route).
AtDomainList string
// The mailbox name.
MailboxName string
// The host name.
HostName string
}
An address.
func ParseAddressList ¶
func ParseAddressList(fields []interface{}) (addrs []*Address)
Parse an address list from fields.
type BodyPartName ¶
type BodyPartName struct {
// The specifier of the requested part.
Specifier PartSpecifier
// The part path. Parts indexes start at 1.
Path []int
// If Specifier is HEADER, contains header fields that will/won't be returned,
// depending of the value of NotFields.
Fields []string
// If set to true, Fields is a blacklist of fields instead of a whitelist.
NotFields bool
}
A body part name.
func (*BodyPartName) Equal ¶
func (part *BodyPartName) Equal(other *BodyPartName) bool
Equal checks whether two body part names are equal.
type BodySectionName ¶
type BodySectionName struct {
BodyPartName
// If set to true, do not implicitly set the \Seen flag.
Peek bool
// The substring of the section requested. The first value is the position of
// the first desired octet and the second value is the maximum number of
// octets desired.
Partial []int
// contains filtered or unexported fields
}
A body section name. See RFC 3501 page 55.
func ParseBodySectionName ¶
func ParseBodySectionName(s FetchItem) (*BodySectionName, error)
ParseBodySectionName parses a body section name.
func (*BodySectionName) Equal ¶
func (section *BodySectionName) Equal(other *BodySectionName) bool
Equal checks whether two sections are equal.
func (*BodySectionName) ExtractPartial ¶
func (section *BodySectionName) ExtractPartial(b []byte) []byte
ExtractPartial returns a subset of the specified bytes matching the partial requested in the section name.
func (*BodySectionName) FetchItem ¶
func (section *BodySectionName) FetchItem() FetchItem
type BodyStructure ¶
type BodyStructure struct {
// The MIME type.
MIMEType string
// The MIME subtype.
MIMESubType string
// The MIME parameters.
Params map[string]string
// The Content-Id header.
Id string
// The Content-Description header.
Description string
// The Content-Encoding header.
Encoding string
// The Content-Length header.
Size uint32
// The children parts, if multipart.
Parts []*BodyStructure
// The envelope, if message/rfc822.
Envelope *Envelope
// The body structure, if message/rfc822.
BodyStructure *BodyStructure
// The number of lines, if text or message/rfc822.
Lines uint32
// True if the body structure contains extension data.
Extended bool
// The Content-Disposition header field value.
Disposition string
// The Content-Disposition header field parameters.
DispositionParams map[string]string
// The Content-Language header field, if multipart.
Language []string
// The content URI, if multipart.
Location []string
// The MD5 checksum.
MD5 string
}
A body structure. See RFC 3501 page 74.
func (*BodyStructure) Format ¶
func (bs *BodyStructure) Format() (fields []interface{})
func (*BodyStructure) Parse ¶
func (bs *BodyStructure) Parse(fields []interface{}) error
type Command ¶
type Command struct {
// The command tag. It acts as a unique identifier for this command. If empty,
// the command is untagged.
Tag string
// The command name.
Name string
// The command arguments.
Arguments []interface{}
}
A command.
type Commander ¶
type Commander interface {
Command() *Command
}
A value that can be converted to a command.
type Conn ¶
An IMAP connection.
func (*Conn) SetDebug ¶
SetDebug defines an io.Writer to which all network activity will be logged. If nil is provided, network activity will not be logged.
func (*Conn) Upgrade ¶
func (c *Conn) Upgrade(upgrader ConnUpgrader) error
Upgrade a connection, e.g. wrap an unencrypted connection with an encrypted tunnel.
type ConnUpgrader ¶
A function that upgrades a connection.
This should only be used by libraries implementing an IMAP extension (e.g. COMPRESS).
type ContinuationReq ¶
type ContinuationReq struct {
// The info message sent with the continuation request.
Info string
}
ContinuationReq is a continuation request response.
func (*ContinuationReq) WriteTo ¶
func (r *ContinuationReq) WriteTo(w *Writer) error
type DataResp ¶
type DataResp struct {
// The response tag. Can be either "" for untagged responses, "+" for continuation
// requests or a previous command's tag.
Tag string
// The parsed response fields.
Fields []interface{}
}
DataResp is an IMAP response containing data.
func NewUntaggedResp ¶
func NewUntaggedResp(fields []interface{}) *DataResp
NewUntaggedResp creates a new untagged response.
type Envelope ¶
type Envelope struct {
// The message date.
Date time.Time
// The message subject.
Subject string
// The From header addresses.
From []*Address
// The message senders.
Sender []*Address
// The Reply-To header addresses.
ReplyTo []*Address
// The To header addresses.
To []*Address
// The Cc header addresses.
Cc []*Address
// The Bcc header addresses.
Bcc []*Address
// The In-Reply-To header. Contains the parent Message-Id.
InReplyTo string
// The Message-Id header.
MessageId string
}
A message envelope, ie. message metadata from its headers. See RFC 3501 page 77.
type ErrBadSeqSet ¶
type ErrBadSeqSet string
ErrBadSeqSet is used to report problems with the format of a sequence set value.
func (ErrBadSeqSet) Error ¶
func (err ErrBadSeqSet) Error() string
type Literal ¶
A literal, as defined in RFC 3501 section 4.3.
type Logger ¶
type Logger interface {
Printf(format string, v ...interface{})
Println(v ...interface{})
}
Logger is the behaviour used by server/client to report errors for accepting connections and unexpected behavior from handlers.
type MailboxInfo ¶
type MailboxInfo struct {
// The mailbox attributes.
Attributes []string
// The server's path separator.
Delimiter string
// The mailbox name.
Name string
}
Basic mailbox info.
func (*MailboxInfo) Format ¶
func (info *MailboxInfo) Format() []interface{}
Format mailbox info to fields.
func (*MailboxInfo) Match ¶
func (info *MailboxInfo) Match(reference, pattern string) bool
Match checks if a reference and a pattern matches this mailbox name, as defined in RFC 3501 section 6.3.8.
func (*MailboxInfo) Parse ¶
func (info *MailboxInfo) Parse(fields []interface{}) error
Parse mailbox info from fields.
type MailboxStatus ¶
type MailboxStatus struct {
// The mailbox name.
Name string
// True if the mailbox is open in read-only mode.
ReadOnly bool
// The mailbox items that are currently filled in. This map's values
// should not be used directly, they must only be used by libraries
// implementing extensions of the IMAP protocol.
Items map[StatusItem]interface{}
// The Items map may be accessed in different goroutines. Protect
// concurrent writes.
ItemsLocker sync.Mutex
// The mailbox flags.
Flags []string
// The mailbox permanent flags.
PermanentFlags []string
// The sequence number of the first unseen message in the mailbox.
UnseenSeqNum uint32
// The number of messages in this mailbox.
Messages uint32
// The number of messages not seen since the last time the mailbox was opened.
Recent uint32
// The number of unread messages.
Unseen uint32
// The next UID.
UidNext uint32
// Together with a UID, it is a unique identifier for a message.
// Must be greater than or equal to 1.
UidValidity uint32
}
A mailbox status.
func NewMailboxStatus ¶
func NewMailboxStatus(name string, items []StatusItem) *MailboxStatus
Create a new mailbox status that will contain the specified items.
func (*MailboxStatus) Format ¶
func (status *MailboxStatus) Format() []interface{}
func (*MailboxStatus) Parse ¶
func (status *MailboxStatus) Parse(fields []interface{}) error
type Message ¶
type Message struct {
// The message sequence number. It must be greater than or equal to 1.
SeqNum uint32
// The mailbox items that are currently filled in. This map's values
// should not be used directly, they must only be used by libraries
// implementing extensions of the IMAP protocol.
Items map[FetchItem]interface{}
// The message envelope.
Envelope *Envelope
// The message body structure (either BODYSTRUCTURE or BODY).
BodyStructure *BodyStructure
// The message flags.
Flags []string
// The date the message was received by the server.
InternalDate time.Time
// The message size.
Size uint32
// The message unique identifier. It must be greater than or equal to 1.
Uid uint32
// The message body sections.
Body map[*BodySectionName]Literal
// contains filtered or unexported fields
}
A message.
func NewMessage ¶
Create a new empty message that will contain the specified items.
func (*Message) GetBody ¶
func (m *Message) GetBody(section *BodySectionName) Literal
Get the body section with the specified name. Returns nil if it's not found.
type PartSpecifier ¶
type PartSpecifier string
A PartSpecifier specifies which parts of the MIME entity should be returned.
type Reader ¶
type Reader struct {
MaxLiteralSize uint32 // The maximum literal size.
// contains filtered or unexported fields
}
An IMAP reader.
func NewServerReader ¶
func (*Reader) ReadFields ¶
func (*Reader) ReadLiteral ¶
func (*Reader) ReadQuotedString ¶
func (*Reader) ReadRespCode ¶
func (r *Reader) ReadRespCode() (code StatusRespCode, fields []interface{}, err error)
type Resp ¶
type Resp interface {
// contains filtered or unexported methods
}
Resp is an IMAP response. It is either a *DataResp, a *ContinuationReq or a *StatusResp.
type SearchCriteria ¶
type SearchCriteria struct {
SeqNum *SeqSet // Sequence number is in sequence set
Uid *SeqSet // UID is in sequence set
// Time and timezone are ignored
Since time.Time // Internal date is since this date
Before time.Time // Internal date is before this date
SentSince time.Time // Date header field is since this date
SentBefore time.Time // Date header field is before this date
Header textproto.MIMEHeader // Each header field value is present
Body []string // Each string is in the body
Text []string // Each string is in the text (header + body)
WithFlags []string // Each flag is present
WithoutFlags []string // Each flag is not present
Larger uint32 // Size is larger than this number
Smaller uint32 // Size is smaller than this number
Not []*SearchCriteria // Each criteria doesn't match
Or [][2]*SearchCriteria // Each criteria pair has at least one match of two
}
SearchCriteria is a search criteria. A message matches the criteria if and only if it matches each one of its fields.
func NewSearchCriteria ¶
func NewSearchCriteria() *SearchCriteria
NewSearchCriteria creates a new search criteria.
func (*SearchCriteria) Format ¶
func (c *SearchCriteria) Format() []interface{}
Format formats search criteria to fields. UTF-8 is used.
func (*SearchCriteria) ParseWithCharset ¶
func (c *SearchCriteria) ParseWithCharset(fields []interface{}, charsetReader func(io.Reader) io.Reader) error
ParseWithCharset parses a search criteria from the provided fields. charsetReader is an optional function that converts from the fields charset to UTF-8.
type Seq ¶
type Seq struct {
Start, Stop uint32
}
Seq represents a single seq-number or seq-range value (RFC 3501 ABNF). Values may be static (e.g. "1", "2:4") or dynamic (e.g. "*", "1:*"). A seq-number is represented by setting Start = Stop. Zero is used to represent "*", which is safe because seq-number uses nz-number rule. The order of values is always Start <= Stop, except when representing "n:*", where Start = n and Stop = 0.
func (Seq) Contains ¶
Contains returns true if the seq-number q is contained in sequence value s. The dynamic value "*" contains only other "*" values, the dynamic range "n:*" contains "*" and all numbers >= n.
type SeqSet ¶
type SeqSet struct {
Set []Seq
}
SeqSet is used to represent a set of message sequence numbers or UIDs (see sequence-set ABNF rule). The zero value is an empty set.
func ParseSeqSet ¶
ParseSeqSet returns a new SeqSet instance after parsing the set string.
func (*SeqSet) Add ¶
Add inserts new sequence values into the set. The string format is described by RFC 3501 sequence-set ABNF rule. If an error is encountered, all values inserted successfully prior to the error remain in the set.
func (*SeqSet) AddNum ¶
AddNum inserts new sequence numbers into the set. The value 0 represents "*".
func (SeqSet) Contains ¶
Contains returns true if the non-zero sequence number or UID q is contained in the set. The dynamic range "n:*" contains all q >= n. It is the caller's responsibility to handle the special case where q is the maximum UID in the mailbox and q < n (i.e. the set cannot match UIDs against "*:n" or "*" since it doesn't know what the maximum value is).
type StatusItem ¶
type StatusItem string
A StatusItem is a mailbox status data item that can be retrieved with a STATUS command. See RFC 3501 section 6.3.10.
type StatusResp ¶
type StatusResp struct {
// The response tag. If empty, it defaults to *.
Tag string
// The status type.
Type StatusRespType
// The status code.
// See https://www.iana.org/assignments/imap-response-codes/imap-response-codes.xhtml
Code StatusRespCode
// Arguments provided with the status code.
Arguments []interface{}
// The status info.
Info string
}
A status response. See RFC 3501 section 7.1
func (*StatusResp) Err ¶
func (r *StatusResp) Err() error
If this status is NO or BAD, returns an error with the status info. Otherwise, returns nil.
func (*StatusResp) WriteTo ¶
func (r *StatusResp) WriteTo(w *Writer) error
type StatusRespCode ¶
type StatusRespCode string
type StoreItem ¶
type StoreItem string
A StoreItem is a message data item that can be updated.
func FormatFlagsOp ¶
FormatFlagsOp returns the StoreItem that executes the flags operation op.
type StringReader ¶
type StringReader interface {
// ReadString reads until the first occurrence of delim in the input,
// returning a string containing the data up to and including the delimiter.
// See https://golang.org/pkg/bufio/#Reader.ReadString
ReadString(delim byte) (line string, err error)
}
A string reader.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package backend defines an IMAP server backend interface.
|
Package backend defines an IMAP server backend interface. |
|
backendutil
Package backendutil provides utility functions to implement IMAP backends.
|
Package backendutil provides utility functions to implement IMAP backends. |
|
memory
A memory backend.
|
A memory backend. |
|
Package client provides an IMAP client.
|
Package client provides an IMAP client. |
|
Package commands implements IMAP commands defined in RFC 3501.
|
Package commands implements IMAP commands defined in RFC 3501. |
|
IMAP responses defined in RFC 3501.
|
IMAP responses defined in RFC 3501. |
|
Package server provides an IMAP server.
|
Package server provides an IMAP server. |
|
Modified UTF-7 encoding defined in RFC 3501 section 5.1.3
|
Modified UTF-7 encoding defined in RFC 3501 section 5.1.3 |