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)	Instantiate an IMAP4 client object
🔑 Login	M.login(user, password)	Authenticate with plaintext password
📂 List mailboxes	M.list(directory, pattern)	List mailbox names matching pattern
📁 Select mailbox	M.select(mailbox, readonly)	Select a mailbox (default INBOX)
🔍 Search messages	M.search(charset, *criteria)	Search for messages matching criteria
📥 Fetch messages	M.fetch(message_set, parts)	Fetch parts of messages
🚪 Logout	M.logout()	Shutdown connection to server

📚 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

builtins.object
    IMAP4
        IMAP4_SSL
        IMAP4_stream

🏷️ 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). If timeout is not given or is None, the global default socket timeout is used.

All IMAP4rev1 commands are supported by methods of the same name (in lower-case).

Each command returns a tuple: (type, [data, ...]) where 'type' is usually 'OK' or 'NO', and 'data' is either the text from the tagged response, or untagged results from command. Each 'data' is either a string, or a tuple. If a tuple, then the first part is the header of the response, and the second part contains the data (i.e., 'literal' value).

Errors raise the exception class .error(""). IMAP4 server errors raise .abort(""), which is a sub-class of 'error'. Mailbox status changes from READ-WRITE to READ-ONLY raise the exception class .readonly(""), which is a sub-class of 'abort'.

• 🚫 "error" exceptions imply a program error.
• 🔌 "abort" exceptions imply the connection should be reset, and the command re-tried.
• 📖 "readonly" exceptions imply the command should be re-tried.

Note: to use this module, you must read the RFCs pertaining to the IMAP4 protocol, as the semantics of the arguments to each IMAP4 command are left to the invoker, not to mention the results. Also, most IMAP servers implement a sub-set of the commands available here.

Methods defined here:

• __enter__(self)
• __exit__(self, *args)
• __getattr__(self, attr)
• __init__(self, host='', port=143, timeout=None) – Initialize self.
• append(self, mailbox, flags, date_time, message) – 📎 Append message to named mailbox. (typ, [data]) = .append(mailbox, flags, date_time, message). All args except message can be None.
• authenticate(self, mechanism, authobject) – 🔐 Authenticate command - requires response processing. 'mechanism' must appear in .capabilities as AUTH=. 'authobject' must be a callable: data = authobject(response).
• capability(self) – 📋 Fetch capabilities list from server. (typ, [data]) = .capability()
• check(self) – ✅ Checkpoint mailbox on server. (typ, [data]) = .check()
• close(self) – ❌ Close currently selected mailbox. Deleted messages are removed from writable mailbox. This is the recommended command before 'LOGOUT'. (typ, [data]) = .close()
• copy(self, message_set, new_mailbox) – 📋 Copy 'message_set' messages onto end of 'new_mailbox'. (typ, [data]) = .copy(message_set, new_mailbox)
• create(self, mailbox) – 🆕 Create new mailbox. (typ, [data]) = .create(mailbox)
• delete(self, mailbox) – 🗑️ Delete old mailbox. (typ, [data]) = .delete(mailbox)
• deleteacl(self, mailbox, who) – 🚫 Delete the ACLs (remove any rights) set for who on mailbox. (typ, [data]) = .deleteacl(mailbox, who)
• enable(self, capability) – 📡 Send an RFC5161 enable string to the server. (typ, [data]) = .enable(capability)
• expunge(self) – 🧹 Permanently remove deleted items from selected mailbox. Generates 'EXPUNGE' response for each deleted message. (typ, [data]) = .expunge(). 'data' is list of message numbers.
• fetch(self, message_set, message_parts) – 📥 Fetch (parts of) messages. (typ, [data, ...]) = .fetch(message_set, message_parts). 'message_parts' should be a string like "(UID BODY[TEXT])".
• getacl(self, mailbox) – 🔑 Get the ACLs for a mailbox. (typ, [data]) = .getacl(mailbox)
• getannotation(self, mailbox, entry, attribute) – 🏷️ Retrieve ANNOTATIONs. (typ, [data]) = .getannotation(mailbox, entry, attribute)
• getquota(self, root) – 📊 Get the quota root's resource usage and limits (RFC2087). (typ, [data]) = .getquota(root)
• getquotaroot(self, mailbox) – 📋 Get the list of quota roots for the named mailbox. (typ, [[QUOTAROOT responses...], [QUOTA responses]]) = .getquotaroot(mailbox)
• list(self, directory='""', pattern='*') – 📂 List mailbox names in directory matching pattern. (typ, [data]) = .list(directory='""', pattern='*'). 'data' is list of LIST responses.
• login(self, user, password) – 🔑 Identify client using plaintext password. (typ, [data]) = .login(user, password). NB: 'password' will be quoted.
• login_cram_md5(self, user, password) – 🔐 Force use of CRAM-MD5 authentication. (typ, [data]) = .login_cram_md5(user, password)
• logout(self) – 🚪 Shutdown connection to server. Returns server 'BYE' response. (typ, [data]) = .logout()
• lsub(self, directory='""', pattern='*') – 📋 List 'subscribed' mailbox names in directory matching pattern. (typ, [data, ...]) = .lsub(directory='""', pattern='*')
• myrights(self, mailbox) – 🔑 Show my ACLs for a mailbox. (typ, [data]) = .myrights(mailbox)
• namespace(self) – 🌐 Returns IMAP namespaces (RFC2342). (typ, [data, ...]) = .namespace()
• noop(self) – 🔄 Send NOOP command. (typ, [data]) = .noop()
• open(self, host='', port=143, timeout=None) – 🔗 Setup connection to remote server. Used by: read, readline, send, shutdown.
• partial(self, message_num, message_part, start, length) – ✂️ Fetch truncated part of a message. (typ, [data, ...]) = .partial(message_num, message_part, start, length)
• print_log(self)
• proxyauth(self, user) – 👤 Assume authentication as "user". Allows an authorised administrator to proxy into any user's mailbox. (typ, [data]) = .proxyauth(user)
• 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'. (typ, [data]) = .recent()
• rename(self, oldmailbox, newmailbox) – ✏️ Rename old mailbox name to new. (typ, [data]) = .rename(oldmailbox, newmailbox)
• response(self, code) – 📨 Return data for response 'code' if received, or None. Old value cleared. (code, [data]) = .response(code)
• search(self, charset, *criteria) – 🔍 Search mailbox for matching messages. (typ, [data]) = .search(charset, criterion, ...). '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. (typ, [data]) = .select(mailbox='INBOX', readonly=False). '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. (typ, [data]) = .setacl(mailbox, who, what)
• setannotation(self, *args) – 🏷️ Set ANNOTATIONs. (typ, [data]) = .setannotation(mailbox[, entry, attribute]+)
• setquota(self, root, limits) – 📊 Set the quota root's resource limits. (typ, [data]) = .setquota(root, limits)
• shutdown(self) – 🔌 Close I/O established in "open".
• socket(self) – 🔌 Return socket instance used to connect. socket = .socket()
• sort(self, sort_criteria, charset, *search_criteria) – 🔢 IMAP4rev1 extension SORT command. (typ, [data]) = .sort(sort_criteria, charset, search_criteria, ...)
• starttls(self, ssl_context=None) – 🔒
• status(self, mailbox, names) – 📊 Request named status conditions for mailbox. (typ, [data]) = .status(mailbox, names)
• store(self, message_set, command, flags) – 🏷️ Alters flag dispositions for messages. (typ, [data]) = .store(message_set, command, flags)
• subscribe(self, mailbox) – 📋 Subscribe to new mailbox. (typ, [data]) = .subscribe(mailbox)
• thread(self, threading_algorithm, charset, *search_criteria) – 🧵 IMAPrev1 extension THREAD command. (type, [data]) = .thread(threading_algorithm, charset, search_criteria, ...)
• uid(self, command, *args) – 🆔 Execute command with messages identified by UID. (typ, [data]) = .uid(command, arg1, arg2, ...)
• unselect(self) – 🔄 Free server's resources associated with the selected mailbox and return to authenticated state. No messages removed. (typ, [data]) = .unselect()
• unsubscribe(self, mailbox) – 🚫 Unsubscribe from old mailbox. (typ, [data]) = .unsubscribe(mailbox)
• xatom(self, name, *args) – 🔧 Allow simple extension commands. (typ, [data]) = .xatom(name, arg, ...)

Data descriptors defined here:

• __dict__ – dictionary for instance variables
• __weakref__ – list of weak references

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.

Instantiate with: IMAP4_SSL([host[, port[, keyfile[, certfile[, ssl_context[, timeout=None]]]]]])

• host – host's name (default: localhost);
• port – port number (default: standard IMAP4 SSL port);
• keyfile – PEM formatted file that contains your private key (default: None);
• certfile – PEM formatted certificate chain file (default: None);
• ssl_context – a SSLContext object that contains your certificate chain and private key (default: None). Note: if ssl_context is provided, then parameters keyfile or certfile should not be set otherwise ValueError is raised.
• timeout – socket timeout (default: None). If timeout is not given or is None, the global default socket timeout is used.

For more documentation see the docstring of the parent class IMAP4.

Methods defined here:

• __init__(self, host='', port=993, keyfile=None, certfile=None, ssl_context=None, timeout=None)
• 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.

Methods defined here:

• __init__(self, command)
• 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 representing local time, an instance of time.struct_time, an aware datetime instance, or a double-quoted string (already in 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