`imaplib` — IMAP4 protocol client¶

Вихідний код: Lib/imaplib.py

This module defines three classes, IMAP4, IMAP4_SSL and IMAP4_stream, which encapsulate a connection to an IMAP4 server and implement a large subset of the IMAP4rev1 client protocol as defined in RFC 3501. It is backward compatible with IMAP4 (RFC 1730) servers, but note that the STATUS command is not supported in IMAP4.

Availability: not WASI.

This module does not work or is not available on WebAssembly. See WebAssembly platforms for more information.

Three classes are provided by the imaplib module, IMAP4 is the base class:

class imaplib.IMAP4(host='', port=IMAP4_PORT, timeout=None)¶

This class implements the actual IMAP4 protocol. The connection is created and protocol version (IMAP4 or IMAP4rev1) is determined when the instance is initialized. If host is not specified, '' (the local host) is used. If port is omitted, the standard IMAP4 port (143) is used. The optional timeout parameter specifies a timeout in seconds for the connection attempt. If timeout is not given or is None, the global default socket timeout is used.

Клас IMAP4 підтримує оператор with. При такому використанні команда LOGOUT IMAP4 виконується автоматично, коли завершується оператор with. Наприклад:

>>> from imaplib import IMAP4
>>> with IMAP4("domain.org") as M:
...     M.noop()
...
('OK', [b'Nothing Accomplished. d25if65hy903weo.87'])

Змінено в версії 3.5: Додано підтримку оператора with.

Змінено в версії 3.9: Додано необов’язковий параметр timeout.

Три винятки визначено як атрибути класу IMAP4:

exception IMAP4.error¶: Виняток створено для будь-яких помилок. Причина винятку передається конструктору у вигляді рядка.

exception IMAP4.abort¶: Помилки сервера IMAP4 призводять до виникнення цього винятку. Це підклас IMAP4.error. Зауважте, що закриття екземпляра та створення нового екземпляра зазвичай дозволяє відновлення після цього винятку.

exception IMAP4.readonly¶: Цей виняток виникає, коли сервер змінює статус доступної для запису поштової скриньки. Це підклас IMAP4.error. Інший клієнт тепер має дозвіл на запис, і поштову скриньку потрібно буде повторно відкрити, щоб знову отримати дозвіл на запис.

Існує також підклас для безпечних з’єднань:

class imaplib.IMAP4_SSL(host='', port=IMAP4_SSL_PORT, *, ssl_context=None, timeout=None)¶

Це підклас, похідний від IMAP4, який підключається через сокет, зашифрований SSL (щоб використовувати цей клас, вам потрібен модуль сокета, скомпільований із підтримкою SSL). Якщо host не вказано, використовується '' (локальний хост). Якщо порт не вказано, використовується стандартний порт IMAP4 через SSL (993). ssl_context — це об’єкт ssl.SSLContext, який дозволяє об’єднувати параметри конфігурації SSL, сертифікати та приватні ключі в єдину (потенційно довговічну) структуру. Будь ласка, прочитайте Міркування безпеки, щоб дізнатися про найкращі практики.

Примітка

With the default ssl_context, the connection is encrypted but the server certificate and hostname are not verified. To verify them, pass a context created by ssl.create_default_context().

The optional timeout parameter specifies a timeout in seconds for the connection attempt. If timeout is not given or is None, the global default socket timeout is used.

Змінено в версії 3.3: Додано параметр ssl_context.

Змінено в версії 3.4: The class now supports hostname check with ssl.SSLContext.check_hostname and Server Name Indication (see ssl.HAS_SNI).

Змінено в версії 3.9: Додано необов’язковий параметр timeout.

Змінено в версії 3.12: The deprecated keyfile and certfile parameters have been removed.

Другий підклас дозволяє з’єднання, створені дочірнім процесом:

class imaplib.IMAP4_stream(command)¶: Це підклас, похідний від IMAP4, який підключається до файлових дескрипторів stdin/stdout, створених передачею команди до subprocess.Popen().

Визначаються наступні функції корисності:

imaplib.Internaldate2tuple(resp)¶: Parse a bytes-like object containing an IMAP4 INTERNALDATE response and return the corresponding local time. The return value is a time.struct_time tuple or None if the input has wrong format.

imaplib.Int2AP(num)¶: Перетворює ціле число на представлення байтів за допомогою символів із набору [A .. P].

imaplib.ParseFlags(resp)¶: Converts a bytes-like object containing an IMAP4 FLAGS response to a tuple of individual flags as bytes. The return value is an empty tuple if the input has wrong format.

imaplib.Time2Internaldate(date_time)¶: Перетворіть date_time на представлення INTERNALDATE IMAP4. Поверненим значенням є рядок у формі: "ДД-МММ-РРРР ГГ:ХМ:СС +ГГММ" (включаючи подвійні лапки). Аргумент date_time може бути числом (int або float), що представляє секунди з епохи (як повертає time.time()), 9-кортеж, що представляє місцевий час, екземпляр time.struct_time (як повертає time.localtime()), відомий екземпляр datetime.datetime або рядок у подвійних лапках. В останньому випадку передбачається, що він уже має правильний формат.

Зверніть увагу, що номери повідомлень IMAP4 змінюються разом зі зміною поштової скриньки; зокрема, після видалення командою EXPUNGE повідомлення, що залишилися, перенумеровуються. Тому вкрай доцільно використовувати натомість UID з командою UID.

Наприкінці модуля є тестовий розділ, який містить докладніший приклад використання.

Дивись також

Документи, що описують протокол, джерела для серверів, які його реалізують, Інформаційний центр IMAP Університету Вашингтона можна знайти за адресою (Вихідний код) https://github.com/uw-imap/imap (Не підтримується).

Об’єкти IMAP4¶

All IMAP4rev1 commands are represented by methods of the same name, either uppercase or lowercase.

All arguments to commands are converted to strings, except for AUTHENTICATE, and the last argument to APPEND which is passed as an IMAP4 literal. If necessary (the string contains IMAP4 protocol-sensitive characters and isn’t enclosed with either parentheses or double quotes) each string is quoted. However, the password argument to the LOGIN command is always quoted. If you want to avoid having an argument string quoted (eg: the flags argument to STORE) then enclose the string in parentheses (eg: r'(\Deleted)'). Or you can quote the string yourself; an argument that is already enclosed in double quotes is left unchanged. In general, however, it is better to pass arguments unquoted and let the module quote them as needed.

Mailbox names are encoded as modified UTF-7 (RFC 3501, section 5.1.3), so a mailbox name containing non-ASCII characters can be passed as an ordinary str. A str that is already valid modified UTF-7 is left unchanged, so that a name obtained from list() (raw bytes decoded to text) round-trips; pass bytes to send the exact bytes with no encoding. When UTF8=ACCEPT is enabled (see enable()), mailbox names are sent as UTF-8 instead.

Змінено в версії 3.16.0a0 (unreleased): Non-ASCII mailbox names are automatically encoded as modified UTF-7.

Most commands return a tuple: (type, [data, ...]) where type is usually 'OK' or 'NO', and data is either the text from the command response, or mandated results from the command. Each data is either a bytes, or a tuple. If a tuple, then the first part is the header of the response, and the second part contains the data (ie: „literal“ value).

The message_set options to the commands below can be a string specifying one or more messages to be acted upon. It may be a simple message number ('1'), a range of message numbers ('2:4'), or a group of non-contiguous ranges separated by commas ('1:3,6:9'). A range can contain an asterisk to indicate an infinite upper bound ('3:*').

Alternatively it can be specified using integers and range objects. It may be a single message number or a sequence. The sequence items may be integers, (start, stop) tuples (where None or '*' stands for the last message), or range objects. For example, [1, (3, 5), 8] and [range(1, 6), 8] are both equivalent to '1,3:5,8'.

Змінено в версії 3.16.0a0 (unreleased): Added support for the structured message_set.

Command arguments that are parenthesized lists of atoms — such as the flag_list argument of store() and the flags argument of append(), the names argument of status(), the sort_criteria argument of sort(), or the message_parts argument of fetch() — can be passed as a sequence of strings instead of a single preformatted string. For example, [r'\Seen', r'\Answered'] is equivalent to (\Seen \Answered).

Змінено в версії 3.16.0a0 (unreleased): Added support for passing these arguments as a sequence.

The value-bearing arguments of the search and fetch commands can be quoted by hand, but this is error prone. Instead, they may contain ? placeholders that are substituted, and quoted as required, from a params keyword argument, in the manner of sqlite3 parameter substitution:

# SEARCH FROM me@example.com SUBJECT "trip report"
M.search(None, 'FROM ? SUBJECT ?', params=['me@example.com', 'trip report'])

# FETCH 1:5 (FLAGS BODY[HEADER.FIELDS (DATE FROM)])
M.fetch('1:5', 'FLAGS BODY[HEADER.FIELDS ?]', params=[['DATE', 'FROM']])

The placeholders are:

? — an astring: a string (which will be quoted if necessary), an integer, or a list of integers and/or strings (which will be sent as a parenthesized list);
?f — a flag or a list of flags, sent verbatim without quoting;
?s — a message_set in the structured form described above.

?? stands for a literal ?.

Substitution is only performed when params is given; if no params are given, an argument containing a literal ? is unchanged. The params keyword is accepted by search(), fetch(), sort(), thread() and uid().

Added in version 3.16.0a0 (unreleased): The params keyword argument.

Екземпляр IMAP4 має такі методи:

IMAP4.append(mailbox, flags, date_time, message, *, translate_line_endings=True)¶

Додайте повідомлення до вказаної поштової скриньки.

flags may be None or a string of IMAP flag tokens. Multiple flags are separated by spaces, for example r'\Seen \Answered'. If flags is not already enclosed in parentheses, parentheses are added automatically.

If translate_line_endings is true (the default), line endings in message are translated to CRLF. Pass False to send the message literal exactly as given, which is required to preserve messages that contain bare CR or LF. In that case message must already use CRLF line endings as required by RFC 3501; for example, serialize email messages using email.policy.SMTP.

Змінено в версії 3.16.0a0 (unreleased): Added the translate_line_endings parameter.

IMAP4.authenticate(mechanism, authobject)¶

Команда автентифікації — вимагає обробки відповіді.

mechanism вказує, який механізм автентифікації буде використано - він має відображатися в змінній екземпляра capabilities у формі AUTH=mechanism.

authobject повинен бути викликаним об’єктом:

data = authobject(response)

Він буде викликаний для обробки відповідей продовження сервера; аргумент відповідь, який він передає, буде байт. Він має повернути байти дані, які будуть закодовані в base64 і надіслані на сервер. Він має повертати None, якщо замість цього потрібно надіслати відповідь * про переривання клієнта.

Змінено в версії 3.5: рядкові імена користувачів і паролі тепер кодуються як utf-8 замість обмеження ASCII.

IMAP4.check()¶: Контрольна поштова скринька на сервері.

IMAP4.close()¶: Закрити вибрану поштову скриньку. Видалені повідомлення видаляються з доступної для запису поштової скриньки. Це рекомендована команда перед ВИХОДОМ.

IMAP4.copy(message_set, new_mailbox, *, uid=False)¶

Скопіюйте повідомлення message_set у кінець new_mailbox.

If uid is true, message_set is a set of UIDs and the UID COPY command is used instead of COPY.

Змінено в версії 3.16.0a0 (unreleased): Added the uid parameter.

IMAP4.create(mailbox)¶: Створіть нову поштову скриньку з назвою mailbox.

IMAP4.delete(mailbox)¶: Видалити стару поштову скриньку з назвою mailbox.

IMAP4.deleteacl(mailbox, who)¶: Видалити списки керування доступом (вилучити будь-які права), встановлені для поштової скриньки who.

IMAP4.enable(capability)¶: Увімкнути можливість (див. RFC 5161). Більшість можливостей не потрібно вмикати. Наразі підтримується лише можливість UTF8=ACCEPT (див. RFC 6855).

Added in version 3.5: Сам метод enable() і підтримка RFC 6855.

IMAP4.expunge(message_set=None, *, uid=False)¶

Назавжди видалити видалені елементи з вибраної поштової скриньки. Генерує відповідь EXPUNGE для кожного видаленого повідомлення. Повернуті дані містять список номерів повідомлень EXPUNGE у порядку отримання.

If uid is true, the UID EXPUNGE command (RFC 4315) is used to remove only the messages that both are marked as deleted and have a UID in message_set. message_set is required in this case, and must be omitted otherwise.

Змінено в версії 3.16.0a0 (unreleased): Added the message_set and uid parameters.

IMAP4.fetch(message_set, message_parts, *, uid=False, params=None)¶

Отримати (частини) повідомлень. message_parts має бути рядком імен частин повідомлення, укладених у круглі дужки, наприклад: "(UID BODY[TEXT]). Повернуті дані – це кортежі конверта частини повідомлення та даних.

If uid is true, message_set is a set of UIDs and the message numbers in the response are UIDs (UID FETCH).

If params is given, ? placeholders in message_parts are substituted with the quoted parameters (see the placeholders).

Змінено в версії 3.16.0a0 (unreleased): Added the params and uid parameters.

IMAP4.getacl(mailbox)¶: Отримайте ACL для поштової скриньки. Метод нестандартний, але підтримується сервером Cyrus.

IMAP4.getannotation(mailbox, entry, attribute)¶: Отримати вказані АННОТАЦІЇ для поштової скриньки. Метод нестандартний, але підтримується сервером Cyrus.

IMAP4.getquota(root)¶: Отримайте квоту root щодо використання ресурсів і обмежень. Цей метод є частиною розширення IMAP4 QUOTA, визначеного в rfc2087.

IMAP4.getquotaroot(mailbox)¶: Отримайте список квоти roots для вказаної поштової скриньки. Цей метод є частиною розширення IMAP4 QUOTA, визначеного в rfc2087.

IMAP4.id(fields=None)¶: Send client identification information to the server and return the identification information sent back by the server (the ID command, defined in RFC 2971). fields is a mapping of field names to values (for example, {'name': 'myclient', 'version': '1.0'}); a value can be None. The server must support the ID capability.

Added in version 3.16.0a0 (unreleased).

IMAP4.idle(duration=None)¶

Return an Idler: an iterable context manager implementing the IMAP4 IDLE command as defined in RFC 2177.

The returned object sends the IDLE command when activated by the with statement, produces IMAP untagged responses via the iterator protocol, and sends DONE upon context exit.

All untagged responses that arrive after sending the IDLE command (including any that arrive before the server acknowledges the command) will be available via iteration. Any leftover responses (those not iterated in the with context) can be retrieved in the usual way after IDLE ends, using IMAP4.response().

Responses are represented as (type, [data, ...]) tuples, as described in IMAP4 Objects.

The duration argument sets a maximum duration (in seconds) to keep idling, after which any ongoing iteration will stop. It can be an int or float, or None for no time limit. Callers wishing to avoid inactivity timeouts on servers that impose them should keep this at most 29 minutes (1740 seconds). Requires a socket connection; duration must be None on IMAP4_stream connections.

>>> with M.idle(duration=29 * 60) as idler:
...     for typ, data in idler:
...         print(typ, data)
...
EXISTS [b'1']
RECENT [b'1']

Idler.burst(interval=0.1)¶

Yield a burst of responses no more than interval seconds apart (expressed as an int or float).

This generator is an alternative to iterating one response at a time, intended to aid in efficient batch processing. It retrieves the next response along with any immediately available subsequent responses. (For example, a rapid series of EXPUNGE responses after a bulk delete.)

Requires a socket connection; does not work on IMAP4_stream connections.

>>> with M.idle() as idler:
...     # get a response and any others following by < 0.1 seconds
...     batch = list(idler.burst())
...     print(f'processing {len(batch)} responses...')
...     print(batch)
...
processing 3 responses...
[('EXPUNGE', [b'2']), ('EXPUNGE', [b'1']), ('RECENT', [b'0'])]

Порада

The IDLE context’s maximum duration, as passed to IMAP4.idle(), is respected when waiting for the first response in a burst. Therefore, an expired Idler will cause this generator to return immediately without producing anything. Callers should consider this if using it in a loop.

Примітка

The iterator returned by IMAP4.idle() is usable only within a with statement. Before or after that context, unsolicited responses are collected internally whenever a command finishes, and can be retrieved with IMAP4.response().

Примітка

The Idler class name and structure are internal interfaces, subject to change. Calling code can rely on its context management, iteration, and public method to remain stable, but should not subclass, instantiate, compare, or otherwise directly reference the class.

Added in version 3.14.

IMAP4.list(directory='', pattern='*')¶: Список імен поштових скриньок у каталозі, що відповідає шаблону. каталог за замовчуванням є текою електронної пошти верхнього рівня, а шаблон за замовчуванням відповідає будь-чому. Повернуті дані містять список відповідей СПИСОК.

IMAP4.login(user, password)¶: Ідентифікуйте клієнта за допомогою відкритого пароля. Пароль буде взято в лапки.

IMAP4.login_cram_md5(user, password)¶: Force use of CRAM-MD5 authentication when identifying the client to protect the password. It will only work if the server CAPABILITY response includes the phrase AUTH=CRAM-MD5.

Змінено в версії 3.15: An IMAP4.error is raised if MD5 support is not available.

IMAP4.login_plain(user, password)¶

Authenticate using the PLAIN SASL mechanism (RFC 4616).

This is a plaintext authentication mechanism that can be used instead of login() when UTF-8 support is required (see RFC 6855). Since the credentials are only base64-encoded, not encrypted, this method should only be used over a TLS-protected connection, such as IMAP4_SSL or after starttls().

It will only work if the server supports the PLAIN mechanism, which it need not advertise as AUTH=PLAIN in its CAPABILITY response.

Added in version 3.16.0a0 (unreleased).

IMAP4.logout()¶: Вимкніть з’єднання з сервером. Повертає відповідь сервера BYE.

Змінено в версії 3.8: Метод більше не ігнорує мовчки довільні винятки.

IMAP4.lsub(directory='', pattern='*')¶: Список імен передплачених поштових скриньок у каталозі, що відповідає шаблону. каталог за замовчуванням є каталогом верхнього рівня, а шаблон за замовчуванням відповідає будь-якій поштовій скриньці. Повернуті дані – це кортежі конверта частини повідомлення та даних.

IMAP4.move(message_set, new_mailbox, *, uid=False)¶

Move message_set messages onto end of new_mailbox.

The server must support the MOVE capability (RFC 6851).

If uid is true, message_set is a set of UIDs and the UID MOVE command is used instead of MOVE.

Added in version 3.16.0a0 (unreleased).

IMAP4.myrights(mailbox)¶: Показати мої ACL для поштової скриньки (тобто права, які я маю на поштову скриньку).

IMAP4.namespace()¶: Повертає простори імен IMAP, як визначено в RFC 2342.

IMAP4.noop()¶: Надіслати NOOP на сервер.

IMAP4.open(host, port, timeout=None)¶

Opens socket to port at host. The optional timeout parameter specifies a timeout in seconds for the connection attempt. If timeout is not given or is None, the global default socket timeout is used. Also note that if the timeout parameter is set to be zero, it will raise a ValueError to reject creating a non-blocking socket. This method is implicitly called by the IMAP4 constructor. The connection objects established by this method will be used in the IMAP4.read(), IMAP4.readline(), IMAP4.send(), and IMAP4.shutdown() methods. You may override this method.

Викликає подію аудиту imaplib.open з аргументами self, host, port.

Змінено в версії 3.9: Додано параметр timeout.

IMAP4.partial(message_num, message_part, start, length)¶: Отримати скорочену частину повідомлення. Повернуті дані — це кортеж із конверта частини повідомлення та даних.

IMAP4.proxyauth(user)¶: Припустити автентифікацію як користувача. Дозволяє авторизованому адміністратору надсилати проксі до поштової скриньки будь-якого користувача.

IMAP4.read(size)¶: Читає size байти з віддаленого сервера. Ви можете змінити цей метод.

IMAP4.readline()¶: Читає один рядок з віддаленого сервера. Ви можете змінити цей метод.

IMAP4.recent()¶: Запитувати сервер для оновлення. Повернені дані: None, якщо немає нових повідомлень, інакше значення відповіді RECENT.

IMAP4.rename(oldmailbox, newmailbox)¶: Перейменуйте поштову скриньку з назвою oldmailbox на newmailbox.

IMAP4.response(code)¶: Повернути дані для відповіді код, якщо отримано, або None. Повертає заданий код замість звичайного типу.

IMAP4.search(charset, criterion, [..., ]*, uid=False, params=None)¶

Пошук поштової скриньки для відповідних повідомлень. charset може мати значення None, у цьому випадку CHARSET не буде вказано у запиті до сервера. Протокол IMAP вимагає вказівки принаймні одного критерію; виняток буде викликано, коли сервер повертає помилку. charset має бути None, якщо можливість UTF8=ACCEPT було ввімкнено за допомогою команди enable().

If uid is true, the message numbers in the response are UIDs (UID SEARCH).

A criterion passed as str is encoded to charset (which must name a codec known to Python); pass bytes to send a criterion that is already encoded, for example when charset is one that Python does not support. When charset is None (as it must be under UTF8=ACCEPT), the criterion is sent using the connection’s encoding instead.

If params is given, ? placeholders in the criteria are substituted with the quoted parameters (see the placeholders).

Приклад:

# M is a connected IMAP4 instance...
typ, msgnums = M.search(None, 'FROM', '"John Smith"')

# or:
typ, msgnums = M.search(None, '(FROM "John Smith")')

# or, letting the module quote the value (this is recommended):
typ, msgnums = M.search(None, 'FROM ?', params=['John Smith'])

Змінено в версії 3.16.0a0 (unreleased): Added the params and uid parameters. str search criteria are encoded to charset.

IMAP4.select(mailbox='INBOX', readonly=False)¶: Виберіть поштову скриньку. Повернені дані – це кількість повідомлень у поштовій скриньці (відповідь «ІСНУЄ»). Типовою поштовою скринькою є 'INBOX'. Якщо встановлено прапорець readonly, зміни поштової скриньки заборонені.

IMAP4.send(data)¶

Надсилає дані на віддалений сервер. Ви можете змінити цей метод.

Викликає подію аудиту imaplib.send з аргументами self, data.

IMAP4.setacl(mailbox, who, what)¶: Установіть ACL для поштової скриньки. Метод нестандартний, але підтримується сервером Cyrus.

IMAP4.setannotation(mailbox, entry, attribute[, ...])¶: Установіть АННОТАЦІЮ для поштової скриньки. Метод нестандартний, але підтримується сервером Cyrus.

IMAP4.setquota(root, limits)¶: Встановіть ліміти ресурсів квоти root. Цей метод є частиною розширення IMAP4 QUOTA, визначеного в rfc2087.

IMAP4.shutdown()¶: Закрити з’єднання встановлено в відкритому. Цей метод неявно викликається IMAP4.logout(). Ви можете змінити цей метод.

IMAP4.socket()¶: Повертає екземпляр сокета, який використовується для підключення до сервера.

IMAP4.sort(sort_criteria, charset, search_criterion, [..., ]*, uid=False, params=None)¶

Команда sort є варіантом search із семантикою сортування для результатів. Повернуті дані містять розділений пробілами список відповідних номерів повідомлень.

Сортування має два аргументи перед аргументом(ами) критерій_пошуку; список критеріїв_сортування в дужках і пошуковий набір символів. Зауважте, що на відміну від search, пошуковий аргумент charset є обов’язковим. Існує також команда uid sort, яка відповідає sort так, як uid search відповідає search. Команда sort спочатку шукає в поштовій скриньці повідомлення, які відповідають заданим критеріям пошуку, використовуючи аргумент набору символів для інтерпретації рядків у критеріях пошуку. Потім він повертає номери відповідних повідомлень.

If uid is true, the message numbers in the response are UIDs (UID SORT).

As with search(), a search_criterion passed as str is encoded to charset; pass bytes to send one already encoded.

If params is given, ? placeholders in the search criteria are substituted with the quoted parameters (see the placeholders).

Це команда розширення IMAP4rev1.

Змінено в версії 3.16.0a0 (unreleased): Added the params and uid parameters. str search criteria are encoded to charset.

IMAP4.starttls(ssl_context=None)¶: Надішліть команду STARTTLS. Аргумент ssl_context є необов’язковим і має бути об’єктом ssl.SSLContext. Це дозволить шифрувати підключення IMAP. Будь ласка, прочитайте Міркування безпеки, щоб дізнатися про найкращі практики.

Примітка

With the default ssl_context, the connection is encrypted but the server certificate and hostname are not verified. To verify them, pass a context created by ssl.create_default_context().

Added in version 3.2.

Змінено в версії 3.4: The method now supports hostname check with ssl.SSLContext.check_hostname and Server Name Indication (see ssl.HAS_SNI).

IMAP4.status(mailbox, names)¶: Запит умов іменованого статусу для поштової скриньки.

IMAP4.store(message_set, command, flag_list, *, uid=False)¶

Alters flag dispositions for messages in mailbox. command is specified by section 6.4.6 of RFC 3501 as being one of «FLAGS», «+FLAGS», or «-FLAGS», optionally with a suffix of «.SILENT».

If uid is true, message_set is a set of UIDs and the UID STORE command is used instead of STORE.

Наприклад, щоб встановити позначку видалення для всіх повідомлень:

typ, data = M.search(None, 'ALL')
for num in data[0].split():
   M.store(num, '+FLAGS', r'\Deleted')
M.expunge()

Примітка

Creating flags containing „]“ (for example: «[test]») violates RFC 3501 (the IMAP protocol). However, imaplib has historically allowed creation of such flags, and popular IMAP servers, such as Gmail, accept and produce such flags. There are non-Python programs which also create such flags. Although it is an RFC violation and IMAP clients and servers are supposed to be strict, imaplib still continues to allow such flags to be created for backward compatibility reasons, and as of Python 3.6, handles them if they are sent from the server, since this improves real-world compatibility.

Змінено в версії 3.16.0a0 (unreleased): Added the uid parameter.

IMAP4.subscribe(mailbox)¶: Підписатися на нову скриньку.

IMAP4.thread(threading_algorithm, charset, search_criterion, [..., ]*, uid=False, params=None)¶

Команда thread є варіантом search із семантикою потоків для результатів. Повернуті дані містять розділений пробілами список учасників потоку.

Члени ланцюжка складаються з нуля або більше номерів повідомлень, розділених пробілами, що вказує на послідовне батьківське та дочірнє повідомлення.

Thread has two arguments before the search_criterion argument(s); a threading_algorithm, and the searching charset. Note that unlike search, the searching charset argument is mandatory. There is also a uid thread command which corresponds to thread the way that uid search corresponds to search. The thread command first searches the mailbox for messages that match the given searching criteria using the charset argument for the interpretation of strings in the searching criteria. It then returns the matching messages threaded according to the specified threading algorithm.

If uid is true, the message numbers in the response are UIDs (UID THREAD).

As with search(), a search_criterion passed as str is encoded to charset; pass bytes to send one already encoded.

If params is given, ? placeholders in the search criteria are substituted with the quoted parameters (see the placeholders).

Це команда розширення IMAP4rev1.

Змінено в версії 3.16.0a0 (unreleased): Added the params and uid parameters. str search criteria are encoded to charset.

IMAP4.uid(command, arg, [..., ]*, params=None)¶

Виконайте аргументи команди з повідомленнями, ідентифікованими UID, а не номером повідомлення. Повертає відповідь, що відповідає команді. Необхідно надати принаймні один аргумент; якщо їх не надано, сервер поверне повідомлення про помилку та виникне виняток.

If params is given, ? placeholders in the SEARCH, SORT and THREAD criteria or in the FETCH parts are substituted with the quoted parameters (see the placeholders).

Змінено в версії 3.16.0a0 (unreleased): Added the params parameter.

IMAP4.unsubscribe(mailbox)¶: Відписатися від старої поштової скриньки.

IMAP4.unselect()¶: imaplib.IMAP4.unselect() звільняє ресурси сервера, пов’язані з вибраною поштовою скринькою, і повертає сервер до автентифікованого стану. Ця команда виконує ті самі дії, що й imaplib.IMAP4.close(), за винятком того, що повідомлення не видаляються назавжди з поточної вибраної поштової скриньки.

Added in version 3.9.

IMAP4.xatom(name[, ...])¶: Дозволити прості команди розширення, сповіщені сервером у відповіді CAPABILITY.

Наступні атрибути визначені для екземплярів IMAP4:

IMAP4.PROTOCOL_VERSION¶: Останній підтримуваний протокол у відповіді CAPABILITY від сервера.

IMAP4.debug¶: Ціле значення для керування виведенням налагодження. Значення ініціалізації береться зі змінної модуля Debug. Значення більше трьох відстежують кожну команду.

IMAP4.utf8_enabled¶: Логічне значення, яке зазвичай має значення False, але встановлюється на True, якщо команда enable() успішно виконана для можливості UTF8=ACCEPT.

Added in version 3.5.

property IMAP4.file¶: Internal BufferedReader associated with the underlying socket. This property is documented for legacy purposes but not part of the public interface. The caller is responsible to ensure that the current file is closed before changing it.

Deprecated since version 3.15, will be removed in version 3.19.

Приклад IMAP4¶

Ось мінімальний приклад (без перевірки помилок), який відкриває поштову скриньку, отримує та друкує всі повідомлення:

import getpass, imaplib

M = imaplib.IMAP4(host='example.org')
M.login(getpass.getuser(), getpass.getpass())
M.select()
typ, data = M.search(None, 'ALL')
for num in data[0].split():
    typ, data = M.fetch(num, '(RFC822)')
    print('Message %s\n%s\n' % (num, data[0][1]))
M.close()
M.logout()

Примітка

A FETCH response may contain additional or unsolicited data (see RFC 3501, section 7.4.2), so production code should inspect the whole response rather than rely on data[0][1].

`imaplib` — IMAP4 protocol client¶

Об’єкти IMAP4¶

Приклад IMAP4¶

Table of Contents

Попередній розділ

Наступна тема

This page

imaplib — IMAP4 protocol client¶

Об’єкти IMAP4¶

Приклад IMAP4¶

`imaplib` — IMAP4 protocol client¶