Documentation

Overview

    Package client provides an IMAP client.

    It is not safe to use the same Client from multiple goroutines. In general, the IMAP protocol doesn't make it possible to send multiple independent IMAP commands on the same connection.

    Index

    Examples

    Constants

    This section is empty.

    Variables

    View Source
    var (
    	// ErrAlreadyLoggedIn is returned if Login or Authenticate is called when the
    	// client is already logged in.
    	ErrAlreadyLoggedIn = errors.New("Already logged in")
    	// ErrTLSAlreadyEnabled is returned if StartTLS is called when TLS is already
    	// enabled.
    	ErrTLSAlreadyEnabled = errors.New("TLS is already enabled")
    	// ErrLoginDisabled is returned if Login or Authenticate is called when the
    	// server has disabled authentication. Most of the time, calling enabling TLS
    	// solves the problem.
    	ErrLoginDisabled = errors.New("Login is disabled in current state")
    )
    View Source
    var ErrAlreadyLoggedOut = errors.New("Already logged out")

      ErrAlreadyLoggedOut is returned if Logout is called when the client is already logged out.

      View Source
      var ErrNoMailboxSelected = errors.New("No mailbox selected")

        ErrNoMailboxSelected is returned if a command that requires a mailbox to be selected is called when there isn't.

        View Source
        var ErrNotLoggedIn = errors.New("Not logged in")

          ErrNotLoggedIn is returned if a function that requires the client to be logged in is called then the client isn't.

          Functions

          This section is empty.

          Types

          type Client

          type Client struct {
          
          	// A channel to which unilateral updates from the server will be sent. An
          	// update can be one of: *StatusUpdate, *MailboxUpdate, *MessageUpdate,
          	// *ExpungeUpdate. Note that blocking this channel blocks the whole client,
          	// so it's recommended to use a separate goroutine and a buffered channel to
          	// prevent deadlocks.
          	Updates chan<- Update
          
          	// ErrorLog specifies an optional logger for errors accepting connections and
          	// unexpected behavior from handlers. By default, logging goes to os.Stderr
          	// via the log package's standard logger. The logger must be safe to use
          	// simultaneously from multiple goroutines.
          	ErrorLog imap.Logger
          
          	// Timeout specifies a maximum amount of time to wait on a command.
          	//
          	// A Timeout of zero means no timeout. This is the default.
          	Timeout time.Duration
          	// contains filtered or unexported fields
          }

            Client is an IMAP client.

            Example
            Output:
            
            

            func Dial

            func Dial(addr string) (*Client, error)

              Dial connects to an IMAP server using an unencrypted connection.

              func DialTLS

              func DialTLS(addr string, tlsConfig *tls.Config) (*Client, error)

                DialTLS connects to an IMAP server using an encrypted connection.

                func DialWithDialer

                func DialWithDialer(dialer Dialer, addr string) (*Client, error)

                  DialWithDialer connects to an IMAP server using an unencrypted connection using dialer.Dial.

                  Among other uses, this allows to apply a dial timeout.

                  func DialWithDialerTLS

                  func DialWithDialerTLS(dialer Dialer, addr string, tlsConfig *tls.Config) (*Client, error)

                    DialWithDialerTLS connects to an IMAP server using an encrypted connection using dialer.Dial.

                    Among other uses, this allows to apply a dial timeout.

                    func New

                    func New(conn net.Conn) (*Client, error)

                      New creates a new client from an existing connection.

                      func (*Client) Append

                      func (c *Client) Append(mbox string, flags []string, date time.Time, msg imap.Literal) error

                        Append appends the literal argument as a new message to the end of the specified destination mailbox. This argument SHOULD be in the format of an RFC 2822 message. flags and date are optional arguments and can be set to nil.

                        Example
                        Output:
                        
                        

                        func (*Client) Authenticate

                        func (c *Client) Authenticate(auth sasl.Client) error

                          Authenticate indicates a SASL authentication mechanism to the server. If the server supports the requested authentication mechanism, it performs an authentication protocol exchange to authenticate and identify the client.

                          func (*Client) Capability

                          func (c *Client) Capability() (map[string]bool, error)

                            Capability requests a listing of capabilities that the server supports. Capabilities are often returned by the server with the greeting or with the STARTTLS and LOGIN responses, so usually explicitly requesting capabilities isn't needed.

                            Most of the time, Support should be used instead.

                            func (*Client) Check

                            func (c *Client) Check() error

                              Check requests a checkpoint of the currently selected mailbox. A checkpoint refers to any implementation-dependent housekeeping associated with the mailbox that is not normally executed as part of each command.

                              func (*Client) Close

                              func (c *Client) Close() error

                                Close permanently removes all messages that have the \Deleted flag set from the currently selected mailbox, and returns to the authenticated state from the selected state.

                                func (*Client) Copy

                                func (c *Client) Copy(seqset *imap.SeqSet, dest string) error

                                  Copy copies the specified message(s) to the end of the specified destination mailbox.

                                  func (*Client) Create

                                  func (c *Client) Create(name string) error

                                    Create creates a mailbox with the given name.

                                    func (*Client) Delete

                                    func (c *Client) Delete(name string) error

                                      Delete permanently removes the mailbox with the given name.

                                      func (*Client) Execute

                                      func (c *Client) Execute(cmdr imap.Commander, h responses.Handler) (*imap.StatusResp, error)

                                        Execute executes a generic command. cmdr is a value that can be converted to a raw command and h is a response handler. The function returns when the command has completed or failed, in this case err is nil. A non-nil err value indicates a network error.

                                        This function should not be called directly, it must only be used by libraries implementing extensions of the IMAP protocol.

                                        func (*Client) Expunge

                                        func (c *Client) Expunge(ch chan uint32) error

                                          Expunge permanently removes all messages that have the \Deleted flag set from the currently selected mailbox. If ch is not nil, sends sequence IDs of each deleted message to this channel.

                                          Example
                                          Output:
                                          
                                          

                                          func (*Client) Fetch

                                          func (c *Client) Fetch(seqset *imap.SeqSet, items []imap.FetchItem, ch chan *imap.Message) error

                                            Fetch retrieves data associated with a message in the mailbox. See RFC 3501 section 6.4.5 for a list of items that can be requested.

                                            Example
                                            Output:
                                            
                                            

                                            func (*Client) IsTLS

                                            func (c *Client) IsTLS() bool

                                              IsTLS checks if this client's connection has TLS enabled.

                                              func (*Client) List

                                              func (c *Client) List(ref, name string, ch chan *imap.MailboxInfo) error

                                                List returns a subset of names from the complete set of all names available to the client.

                                                An empty name argument is a special request to return the hierarchy delimiter and the root name of the name given in the reference. The character "*" is a wildcard, and matches zero or more characters at this position. The character "%" is similar to "*", but it does not match a hierarchy delimiter.

                                                func (*Client) LoggedOut

                                                func (c *Client) LoggedOut() <-chan struct{}

                                                  LoggedOut returns a channel which is closed when the connection to the server is closed.

                                                  func (*Client) Login

                                                  func (c *Client) Login(username, password string) error

                                                    Login identifies the client to the server and carries the plaintext password authenticating this user.

                                                    func (*Client) Logout

                                                    func (c *Client) Logout() error

                                                      Logout gracefully closes the connection.

                                                      func (*Client) Lsub

                                                      func (c *Client) Lsub(ref, name string, ch chan *imap.MailboxInfo) error

                                                        Lsub returns a subset of names from the set of names that the user has declared as being "active" or "subscribed".

                                                        func (*Client) Mailbox

                                                        func (c *Client) Mailbox() *imap.MailboxStatus

                                                          Mailbox returns the selected mailbox. It returns nil if there isn't one.

                                                          func (*Client) Noop

                                                          func (c *Client) Noop() error

                                                            Noop always succeeds and does nothing.

                                                            It can be used as a periodic poll for new messages or message status updates during a period of inactivity. It can also be used to reset any inactivity autologout timer on the server.

                                                            func (*Client) Rename

                                                            func (c *Client) Rename(existingName, newName string) error

                                                              Rename changes the name of a mailbox.

                                                              func (*Client) Search

                                                              func (c *Client) Search(criteria *imap.SearchCriteria) (seqNums []uint32, err error)

                                                                Search searches the mailbox for messages that match the given searching criteria. Searching criteria consist of one or more search keys. The response contains a list of message sequence IDs corresponding to those messages that match the searching criteria. When multiple keys are specified, the result is the intersection (AND function) of all the messages that match those keys. Criteria must be UTF-8 encoded. See RFC 3501 section 6.4.4 for a list of searching criteria. When no criteria has been set, all messages in the mailbox will be searched using ALL criteria.

                                                                Example
                                                                Output:
                                                                
                                                                

                                                                func (*Client) Select

                                                                func (c *Client) Select(name string, readOnly bool) (*imap.MailboxStatus, error)

                                                                  Select selects a mailbox so that messages in the mailbox can be accessed. Any currently selected mailbox is deselected before attempting the new selection. Even if the readOnly parameter is set to false, the server can decide to open the mailbox in read-only mode.

                                                                  func (*Client) SetDebug

                                                                  func (c *Client) SetDebug(w io.Writer)

                                                                    SetDebug defines an io.Writer to which all network activity will be logged. If nil is provided, network activity will not be logged.

                                                                    func (*Client) SetState

                                                                    func (c *Client) SetState(state imap.ConnState, mailbox *imap.MailboxStatus)

                                                                      SetState sets this connection's internal state.

                                                                      This function should not be called directly, it must only be used by libraries implementing extensions of the IMAP protocol.

                                                                      func (*Client) StartTLS

                                                                      func (c *Client) StartTLS(tlsConfig *tls.Config) error

                                                                        StartTLS starts TLS negotiation.

                                                                        Example
                                                                        Output:
                                                                        
                                                                        

                                                                        func (*Client) State

                                                                        func (c *Client) State() imap.ConnState

                                                                          State returns the current connection state.

                                                                          func (*Client) Status

                                                                          func (c *Client) Status(name string, items []imap.StatusItem) (*imap.MailboxStatus, error)

                                                                            Status requests the status of the indicated mailbox. It does not change the currently selected mailbox, nor does it affect the state of any messages in the queried mailbox.

                                                                            See RFC 3501 section 6.3.10 for a list of items that can be requested.

                                                                            func (*Client) Store

                                                                            func (c *Client) Store(seqset *imap.SeqSet, item imap.StoreItem, value interface{}, ch chan *imap.Message) error

                                                                              Store alters data associated with a message in the mailbox. If ch is not nil, the updated value of the data will be sent to this channel. See RFC 3501 section 6.4.6 for a list of items that can be updated.

                                                                              Example
                                                                              Output:
                                                                              
                                                                              

                                                                              func (*Client) Subscribe

                                                                              func (c *Client) Subscribe(name string) error

                                                                                Subscribe adds the specified mailbox name to the server's set of "active" or "subscribed" mailboxes.

                                                                                func (*Client) Support

                                                                                func (c *Client) Support(cap string) (bool, error)

                                                                                  Support checks if cap is a capability supported by the server. If the server hasn't sent its capabilities yet, Support requests them.

                                                                                  func (*Client) SupportAuth

                                                                                  func (c *Client) SupportAuth(mech string) (bool, error)

                                                                                    SupportAuth checks if the server supports a given authentication mechanism.

                                                                                    func (*Client) SupportStartTLS

                                                                                    func (c *Client) SupportStartTLS() (bool, error)

                                                                                      SupportStartTLS checks if the server supports STARTTLS.

                                                                                      func (*Client) Terminate

                                                                                      func (c *Client) Terminate() error

                                                                                        Terminate closes the tcp connection

                                                                                        func (*Client) UidCopy

                                                                                        func (c *Client) UidCopy(seqset *imap.SeqSet, dest string) error

                                                                                          UidCopy is identical to Copy, but seqset is interpreted as containing unique identifiers instead of message sequence numbers.

                                                                                          func (*Client) UidFetch

                                                                                          func (c *Client) UidFetch(seqset *imap.SeqSet, items []imap.FetchItem, ch chan *imap.Message) error

                                                                                            UidFetch is identical to Fetch, but seqset is interpreted as containing unique identifiers instead of message sequence numbers.

                                                                                            func (*Client) UidSearch

                                                                                            func (c *Client) UidSearch(criteria *imap.SearchCriteria) (uids []uint32, err error)

                                                                                              UidSearch is identical to Search, but UIDs are returned instead of message sequence numbers.

                                                                                              func (*Client) UidStore

                                                                                              func (c *Client) UidStore(seqset *imap.SeqSet, item imap.StoreItem, value interface{}, ch chan *imap.Message) error

                                                                                                UidStore is identical to Store, but seqset is interpreted as containing unique identifiers instead of message sequence numbers.

                                                                                                func (*Client) Unsubscribe

                                                                                                func (c *Client) Unsubscribe(name string) error

                                                                                                  Unsubscribe removes the specified mailbox name from the server's set of "active" or "subscribed" mailboxes.

                                                                                                  func (*Client) Upgrade

                                                                                                  func (c *Client) Upgrade(upgrader imap.ConnUpgrader) error

                                                                                                    Upgrade a connection, e.g. wrap an unencrypted connection with an encrypted tunnel.

                                                                                                    This function should not be called directly, it must only be used by libraries implementing extensions of the IMAP protocol.

                                                                                                    func (*Client) Writer

                                                                                                    func (c *Client) Writer() *imap.Writer

                                                                                                      Writer returns the imap.Writer for this client's connection.

                                                                                                      This function should not be called directly, it must only be used by libraries implementing extensions of the IMAP protocol.

                                                                                                      type Dialer

                                                                                                      type Dialer interface {
                                                                                                      	// Dial connects to the given address.
                                                                                                      	Dial(network, addr string) (net.Conn, error)
                                                                                                      }

                                                                                                      type ExpungeUpdate

                                                                                                      type ExpungeUpdate struct {
                                                                                                      	SeqNum uint32
                                                                                                      }

                                                                                                        ExpungeUpdate is delivered when a message is deleted.

                                                                                                        type MailboxUpdate

                                                                                                        type MailboxUpdate struct {
                                                                                                        	Mailbox *imap.MailboxStatus
                                                                                                        }

                                                                                                          MailboxUpdate is delivered when a mailbox status changes.

                                                                                                          type MessageUpdate

                                                                                                          type MessageUpdate struct {
                                                                                                          	Message *imap.Message
                                                                                                          }

                                                                                                            MessageUpdate is delivered when a message attribute changes.

                                                                                                            type StatusUpdate

                                                                                                            type StatusUpdate struct {
                                                                                                            	Status *imap.StatusResp
                                                                                                            }

                                                                                                              StatusUpdate is delivered when a status update is received.

                                                                                                              type Update

                                                                                                              type Update interface {
                                                                                                              	// contains filtered or unexported methods
                                                                                                              }

                                                                                                                Update is an unilateral server update.