text: IM=True, stream=False, ssl_context=None, timeout=None)[source]¶
  A connection to the IMAP server specified by host is made when this class is instantiated.
  port defaults to 993, or 143 if ssl is
  False.
  If use_uid is
  Trueunique message UIDs be used for all calls that accept message ids (defaults to
  True).
  If ssl is
  True(the default) a secure connection will be made. Otherwise an insecure connection over plain text will be established.
  If ssl is
  Truethe optional ssl_context argument can be used to provide an can be either a float number, or an instance of
  imapclient.SocketTimeout.
  - If a single float number is passed, the same timeout delay applies during the initial connection to the server and for all future socket reads and writes.
  - In case of a
  SocketTimeout, connection timeout and read/write operations can have distinct timeouts.
  - The default is
  None, where no timeout.
  Can be used as a context manager to automatically close opened connections:
  >>> with IMAPClient(host="imap.foo.org") as client: ... client.login("bar@foo.org", "passwd")
  add_flags(messages, flags, silent=False)[source]¶
  Add flags to messages in the currently selected folder.
  flags should be a sequence of strings.
  Returns the flags set for each modified message (see get_flags), or None if silent is true.
  add_gmail_labels(messages, labels, silent=False)[source]¶
  Add labels)., silent=False)[source]¶
  Delete one or more messages from the currently selected folder.
  Returns the flags set for each modified message (see get_flags).
  enable(*args, **kwargs)[source]¶
  Activate one or more server side capability extensions.
  Most capabilities do not need to be enabled. This is only required for extensions which introduce backwards incompatible behaviour. Two capabilities which may require enable are
  CONDSTOREand
  UTF8=ACCEPT.
  A list of the requested extensions that were successfully enabled on the server is returned.
  Once enabled each extension remains active until the IMAP connection is closed.
  See RFC 5161 for more details.
  expunge(messages=None)[source]¶
  When, no messages are specified, remove all.
  When messages are specified, remove the specified messages from the selected folder, provided those messages also have the
  \Deletedflag set. The return value is
  Nonein this case.
  Expunging messages by id(s) requires that use_uid is
  Truefor the client.
  See RFC 4315#section-2.1 section 2}}
  find_special_folder(folder_flag)[source]¶
  Try to locate a special folder, like the Sent or Trash folder.
  >>> server.find_special_folder(imapclient.SENT) 'INBOX.Sent'
  This function tries its best to find the correct folder (if any) but uses heuristics when the server is unable to precisely tell where special folders are located.
  Returns the name of the folder if found, or None otherwise._quota(*args, **kwargs)[source]¶
  Get the quotas associated with a mailbox.
  Returns a list of Quota objects.
  get_quota_root(*args, **kwargs)[source]¶
  Get the quota roots for a mailbox.
  The IMAP server responds with the quota root and the quotas associated so there is usually no need to call get_quota after.
  See RFC 2087 for more details.
  Return a tuple of MailboxQuotaRoots and list of Quota associated
  getacl(*args, **kwargs)[source]¶
  Returns a list of
  (who, acl)tuples describing the access controls for folder.
  gmail_search(*args, **kwargs)_(*args, **kwargs)[source]¶
  Issue the ID command, returning a dict of server implementation fields.
  parameters should be specified as a dictionary of field/value pairs, for example:
  {"name": "IMAPClient", "version": "0.12"}
  idle(*args, **kwargs)(*args, **kwargs)(*args, **kwargs).
  move(*args, **kwargs)[source]¶
  Atomically move messages to another folder.
  Requires the MOVE capability, see RFC 6851.
  namespace(*args, **kwargs).
  plain_login(identity, password, authorization_identity=None)[source]¶
  Authenticate using the PLAIN method (requires server support).
  remove_flags(messages, flags, silent=False)[source]¶
  Remove one or more flags from messages in the currently selected folder.
  flags should be a sequence of strings.
  Returns the flags set for each modified message (see get_flags), or None if silent is true.
  remove_gmail_labels(messages, labels, silent=False)[source]¶
  Remove one or more labels from messages in the currently selected folder, or None if silent is true.'
  To support complex search expressions, criteria lists can be nested. IMAPClient will insert parentheses in the right places. The following will match messages that are both not flagged and do not have “foo” in the subject:[‘NOT’, [‘SUBJECT’, ‘foo’, ‘FLAGGED’]], silent=False)[source]¶
  Set the flags for messages in the currently selected folder.
  flags should be a sequence of strings.
  Returns the flags set for each modified message (see get_flags), or None if silent is true.
  set_gmail_labels(messages, labels, silent=False)[source]¶
  Set the labels).
  setacl(*args, **kwargs)(*args, **kwargs)(*args, **kwargs)[source]¶
  Switch to an SSL encrypted connection by sending a STARTTLS command.
  The ssl_context argument is optional and should be a.
  unselect_folder(*args, **kwargs)[source]¶
  Unselect the current folder and release associated resources.
  Unlike
  close_folder, the
  UNSELECTcommand does not expunge the mailbox, keeping messages with Deleted flag set for example.
  Returns the UNSELECT response string returned by the server.
  xlist_folders(*args, **kwargs)).
  The directory and pattern arguments are as per list_folders().
  - class
  imapclient.
  SocketTimeout[source]¶
  Represents timeout configuration for an IMAP connection.
  As an example,
  SocketTimeout(connect=15, read=60)will make the socket timeout if the connection takes more than 15 seconds to establish but read/write operations can take up to 60 seconds once the connection is done.')
  See RFC 2822 for more detail.
  See also
  Envelopefor information about handling of “group syntax”.
  - class
  imapclient.response_types.
  BodyData[source]¶
  Returned when parsing BODY and BODYSTRUCTURE responses.
  - class
  imapclient.response_types.
  Envelope[source]¶
  Represents envelope structures of messages. Returned when parsing ENVELOPE responses.
  A particular issue to watch out for is IMAP’s handling of “group syntax” in address fields. This is often encountered as a recipient header of the form:
  undisclosed-recipients:;
  but can also be expressed per this more general example:
  A group: a@example.com, B <b@example.org>;
  This example would yield the following Address tuples:
  Address(name=None, route=None, mailbox=u'A group', host=None) Address(name=None, route=None, mailbox=u'a', host=u'example.com') Address(name=u'B', route=None, mailbox=u'b', host=u'example.org') Address(name=None, route=None, mailbox=None, host=None)
  The first Address, where
  hostis
  None, indicates the start of the group. The
  mailboxfield contains the group name. The final Address, where both
  mailboxand
  hostare
  None, indicates the end of the group.
  See RFC 3501#section-7.4.2 and RFC 2822 for further details.
  Exceptions¶
  IMAPClient wraps exceptions raised by imaplib to ease the error handling. All the exceptions related to IMAP errors are defined in the module imapclient.exceptions. The following general exceptions may be raised:
  - IMAPClientError: the base class for IMAPClient’s exceptions and the most commonly used error.
  - IMAPClientAbortError: raised if a serious error has occurred that means the IMAP connection is no longer usable. The connection should be dropped without logout if this occurs.
  - IMAPClientReadOnlyError: raised if a modifying operation was attempted on a read-only folder.
  More specific exceptions existed for common known errors:
  - exception
  imapclient.exceptions.
  CapabilityError[source]¶
  The command tried by the user needs a capability not installed on the IMAP server
  - exception
  imapclient.exceptions.
  IllegalStateError[source]¶
  The command tried needs a different state to be executed. This means the user is not logged in or the command needs a folder to be selected.
  - exception
  imapclient.exceptions.
  InvalidCriteriaError[source]¶
  A command using a search criteria failed, probably due to a syntax error in the criteria string.
  - exception
  imapclient.exceptions.
  LoginError[source]¶
  A connection has been established with the server but an error occurred during the authentication.
  - exception
  imapclient.exceptions.
  ProtocolError[source]¶
  The server replied with a response that violates the IMAP protocol.
  Exceptions from lower layers are possible, such as networks error or unicode malformed exception. In particular:
  - socket.error
  - socket.timeout: raised if a timeout was specified when creating the IMAPClient instance and a network operation takes too long.
  - ssl.SSLError: the base class for network or SSL protocol errors when
  ssl=Trueor
  starttls()is used.
  - ssl.CertificateError: raised when TLS certification verification fails. This is not a subclass of SSLError.
  Utilities¶
  - class
  imapclient.testable_imapclient.
  TestableIMAPClient[source]¶
  Wrapper of
  imapclient.IMAPClientthat mocks all interaction with real IMAP server.
  This class should only be used in tests, where you can safely interact with imapclient without running commands on a real IMAP account.
  TLS Support¶
  This module contains IMAPClient’s functionality related to Transport Layer Security (TLS a.k.a. SSL).