pydoc > imaplib

man perldoc info pydoc3 ri search

📛 NAME

imaplib - IMAP4 client.

🚀 Quick Reference

Use Case	Command	Description
📡 Connect to IMAP server	IMAP4(host='', port=143)	Create an IMAP4 client instance
🔑 Login	login(user, password)	Authenticate with plaintext password
📁 Select mailbox	select(mailbox='INBOX', readonly=False)	Select a mailbox for operations
🔍 Search messages	search(charset, *criteria)	Search mailbox for matching messages
📥 Fetch messages	fetch(message_set, message_parts)	Fetch parts of specified messages
📤 Append message	append(mailbox, flags, date_time, message)	Append message to named mailbox
🗑️ Delete messages	store(message_set, '+FLAGS', '(\\Deleted)')	Mark messages for deletion
🔄 Expunge	expunge()	Permanently remove deleted messages
🚪 Logout	logout()	Shutdown connection to server
🔒 SSL connection	IMAP4_SSL(host='', port=993)	IMAP4 over SSL

📚 MODULE REFERENCE

https://docs.python.org/3.10/library/imaplib.html

The following documentation is automatically generated from the Python source files. It may be incomplete, incorrect or include features that are considered implementation detail and may vary between Python implementations. When in doubt, consult the module reference at the location listed above.

📖 DESCRIPTION

Based on RFC 2060.

• 📦 Public class: IMAP4
• ⚙️ Public variable: Debug
• 🔧 Public functions: Internaldate2tuple, Int2AP, ParseFlags, Time2Internaldate

🏛️ CLASSES

🟦 class IMAP4(builtins.object)

IMAP4(host='', port=143, timeout=None)

IMAP4 client class. Instantiate with: IMAP4([host[, port[, timeout=None]]])

• 🏠 host – host’s name (default: localhost)
• 🔌 port – port number (default: standard IMAP4 port)
• ⏱️ timeout – socket timeout (default: None, uses global default)

All IMAP4rev1 commands are supported by lower‑case methods. Arguments are converted to strings, except for AUTHENTICATE and the last argument to APPEND. Each command returns a tuple: (type, [data, ...]) where type is usually 'OK' or 'NO'. Errors raise <instance>.error("<reason>"); server errors raise <instance>.abort("<reason>"); mailbox status changes raise <instance>.readonly("<reason>").

📋 Methods defined here:

• __enter__(self)
  Enter context manager.
• __exit__(self, *args)
  Exit context manager.
• __getattr__(self, attr)
  Handle attribute access.
• __init__(self, host='', port=143, timeout=None)
  Initialize self. See help(type(self)) for accurate signature.
• append(self, mailbox, flags, date_time, message)
  Append message to named mailbox. All args except message can be None. Returns (typ, [data]).
• authenticate(self, mechanism, authobject)
  Authenticate command. mechanism must appear in <instance>.capabilities as AUTH=<mechanism>. authobject is a callable: data = authobject(response) returning bytes or None.
• capability(self)
  Fetch capabilities list from server. Returns (typ, [data]).
• check(self)
  Checkpoint mailbox on server. Returns (typ, [data]).
• close(self)
  Close currently selected mailbox. Deleted messages are removed from writable mailbox. Recommended before LOGOUT. Returns (typ, [data]).
• copy(self, message_set, new_mailbox)
  Copy message_set messages onto end of new_mailbox. Returns (typ, [data]).
• create(self, mailbox)
  Create new mailbox. Returns (typ, [data]).
• delete(self, mailbox)
  Delete old mailbox. Returns (typ, [data]).
• deleteacl(self, mailbox, who)
  Delete ACLs (remove any rights) set for who on mailbox. Returns (typ, [data]).
• enable(self, capability)
  Send an RFC5161 enable string to the server. Returns (typ, [data]).
• expunge(self)
  Permanently remove deleted items from selected mailbox. Generates EXPUNGE response for each deleted message. Returns (typ, [data]) where data is list of message numbers.
• fetch(self, message_set, message_parts)
  Fetch (parts of) messages. message_parts should be a string of selected parts enclosed in parentheses, e.g., "(UID BODY[TEXT])". Returns (typ, [data, ...]) where data are tuples of message part envelope and data.
• getacl(self, mailbox)
  Get the ACLs for a mailbox. Returns (typ, [data]).
• getannotation(self, mailbox, entry, attribute)
  Retrieve ANNOTATIONs. Returns (typ, [data]).
• getquota(self, root)
  Get quota root’s resource usage and limits (RFC2087). Returns (typ, [data]).
• getquotaroot(self, mailbox)
  Get list of quota roots for the named mailbox. Returns (typ, [[QUOTAROOT responses...], [QUOTA responses]]).
• list(self, directory='""', pattern='*')
  List mailbox names in directory matching pattern. Returns (typ, [data]) where data is list of LIST responses.
• login(self, user, password)
  Identify client using plaintext password. password will be quoted. Returns (typ, [data]).
• login_cram_md5(self, user, password)
  Force use of CRAM‑MD5 authentication. Returns (typ, [data]).
• logout(self)
  Shutdown connection to server. Returns server BYE response. Returns (typ, [data]).
• lsub(self, directory='""', pattern='*')
  List subscribed mailbox names in directory matching pattern. Returns (typ, [data, ...]) where data are tuples of message part envelope and data.
• myrights(self, mailbox)
  Show my ACLs for a mailbox (rights I have on mailbox). Returns (typ, [data]).
• namespace(self)
  Returns IMAP namespaces per RFC2342. Returns (typ, [data, ...]).
• noop(self)
  Send NOOP command. Returns (typ, [data]).
• open(self, host='', port=143, timeout=None)
  Setup connection to remote server on host:port (default: localhost:standard IMAP4 port). Used by read, readline, send, shutdown.
• partial(self, message_num, message_part, start, length)
  Fetch truncated part of a message. Returns (typ, [data, ...]) where data is tuple of message part envelope and data.
• print_log(self)
  Print log.
• proxyauth(self, user)
  Assume authentication as user. Allows authorised administrator to proxy into any user’s mailbox. Returns (typ, [data]).
• read(self, size)
  Read size bytes from remote.
• readline(self)
  Read line from remote.
• recent(self)
  Return most recent RECENT responses if any exist, else prompt server using NOOP. Returns (typ, [data]); data is None if no new messages, else list of RECENT responses.
• rename(self, oldmailbox, newmailbox)
  Rename old mailbox name to new. Returns (typ, [data]).
• response(self, code)
  Return data for response code if received, or None. Old value for response code is cleared. Returns (code, [data]).
• search(self, charset, *criteria)
  Search mailbox for matching messages. Returns (typ, [data]) where data is space‑separated list of matching message numbers. If UTF8 is enabled, charset must be None.
• select(self, mailbox='INBOX', readonly=False)
  Select a mailbox. Flush all untagged responses. Returns (typ, [data]) where data is count of messages in mailbox (EXISTS response). Mandated responses: FLAGS, EXISTS, RECENT, UIDVALIDITY.
• send(self, data)
  Send data to remote.
• setacl(self, mailbox, who, what)
  Set a mailbox ACL. Returns (typ, [data]).
• setannotation(self, *args)
  Set ANNOTATIONs. Returns (typ, [data]).
• setquota(self, root, limits)
  Set quota root’s resource limits. Returns (typ, [data]).
• shutdown(self)
  Close I/O established in open.
• socket(self)
  Return socket instance used to connect to IMAP4 server. Returns socket = <instance>.socket().
• sort(self, sort_criteria, charset, *search_criteria)
  IMAP4rev1 extension SORT command. Returns (typ, [data]).
• starttls(self, ssl_context=None)
  Start TLS.
• status(self, mailbox, names)
  Request named status conditions for mailbox. Returns (typ, [data]).
• store(self, message_set, command, flags)
  Alters flag dispositions for messages in mailbox. Returns (typ, [data]).
• subscribe(self, mailbox)
  Subscribe to new mailbox. Returns (typ, [data]).
• thread(self, threading_algorithm, charset, *search_criteria)
  IMAPrev1 extension THREAD command. Returns (type, [data]).
• uid(self, command, *args)
  Execute command with messages identified by UID rather than message number. Returns response appropriate to command.
• unselect(self)
  Free server’s resources associated with the selected mailbox and return to authenticated state. Same as CLOSE but no messages are removed. Returns (typ, [data]).
• unsubscribe(self, mailbox)
  Unsubscribe from old mailbox. Returns (typ, [data]).
• xatom(self, name, *args)
  Allow simple extension commands notified by server in CAPABILITY response. Assumes command is legal in current state. Returns response appropriate to extension command name.

📊 Data descriptors defined here:

• __dict__ – dictionary for instance variables (if defined)
• __weakref__ – list of weak references to the object (if defined)

📁 Data and other attributes defined here:

• abort = <class 'imaplib.IMAP4.abort'>
• error = <class 'imaplib.IMAP4.error'>
• readonly = <class 'imaplib.IMAP4.readonly'>

🟩 class IMAP4_SSL(IMAP4)

IMAP4_SSL(host='', port=993, keyfile=None, certfile=None, ssl_context=None, timeout=None)

IMAP4 client class over SSL connection. For more documentation see the docstring of the parent class IMAP4.

Method resolution order: IMAP4_SSL, IMAP4, builtins.object

🔧 Methods defined here:

• __init__(self, host='', port=993, keyfile=None, certfile=None, ssl_context=None, timeout=None)
  Initialize self. See help(type(self)) for accurate signature.
• open(self, host='', port=993, timeout=None)
  Setup connection to remote server on host:port (default: localhost:standard IMAP4 SSL port). Used by read, readline, send, shutdown.

All other methods are inherited from IMAP4 (see above).

🟪 class IMAP4_stream(IMAP4)

IMAP4_stream(command)

IMAP4 client class over a stream. Instantiate with IMAP4_stream(command) where command is a string that can be passed to subprocess.Popen(). For more documentation see the docstring of the parent class IMAP4.

Method resolution order: IMAP4_stream, IMAP4, builtins.object

🔧 Methods defined here:

• __init__(self, command)
  Initialize self. See help(type(self)) for accurate signature.
• open(self, host=None, port=None, timeout=None)
  Setup a stream connection. Used by read, readline, send, shutdown.
• read(self, size)
  Read size bytes from remote.
• readline(self)
  Read line from remote.
• send(self, data)
  Send data to remote.
• shutdown(self)
  Close I/O established in open.

All other methods are inherited from IMAP4 (see above).

🔧 FUNCTIONS

• Int2AP(num)
  Convert integer to A‑P string representation.
• Internaldate2tuple(resp)
  Parse an IMAP4 INTERNALDATE string. Return corresponding local time as a time.struct_time tuple or None if the string has wrong format.
• ParseFlags(resp)
  Convert IMAP4 flags response to Python tuple.
• Time2Internaldate(date_time)
  Convert date_time to IMAP4 INTERNALDATE representation. Return string in form: '"DD-Mmm-YYYY HH:MM:SS +HHMM"'. The date_time argument can be a number (int or float) representing seconds since epoch, a 9‑tuple, a time.struct_time, an aware datetime instance, or a double-quoted string (assumed already correct format).

📦 DATA

__all__ = ['IMAP4', 'IMAP4_stream', 'Internaldate2tuple', 'Int2AP', 'P...]

🆚 VERSION

2.58

📁 FILE

/usr/lib/python3.10/imaplib.py

📛 NAME 🚀 Quick Reference 📚 MODULE REFERENCE 📖 DESCRIPTION 🏛️ CLASSES 🔧 FUNCTIONS 📦 DATA 🆚 VERSION 📁 FILE