> **Источник:** https://python-all.ru/3.0/library/imaplib.html
>
> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.

---

# `imaplib` – клиент протокола IMAP4

Этот модуль определяет три класса: [`IMAP4`](https://python-all.ru/3.0/library/imaplib.html#imaplib.IMAP4), [`IMAP4_SSL`](https://python-all.ru/3.0/library/imaplib.html#imaplib.IMAP4_SSL) и [`IMAP4_stream`](https://python-all.ru/3.0/library/imaplib.html#imaplib.IMAP4_stream), которые инкапсулируют соединение с сервером IMAP4 и реализуют большой подмножество клиентского протокола IMAP4rev1, определённого в [**RFC 2060**](https://python-all.ru/3.0/library/imaplib.html). Он обратно совместим с серверами IMAP4 ([**RFC 1730**](https://python-all.ru/3.0/library/imaplib.html)), но следует учесть, что команда `STATUS` в IMAP4 не поддерживается.

Модуль `imaplib` предоставляет три класса, [`IMAP4`](https://python-all.ru/3.0/library/imaplib.html#imaplib.IMAP4) является базовым классом:

#### `[imaplib.IMAP4]class imaplib.IMAP4([host[, port]])`

Этот класс реализует протокол IMAP4. Соединение создается, а версия протокола (IMAP4 или IMAP4rev1) определяется при инициализации экземпляра. Если

*host*

не указан, используется

`''`

(локальный хост). Если

*port*

опущен, используется стандартный порт IMAP4 (143).

Три исключения определены как атрибуты класса [`IMAP4`](https://python-all.ru/3.0/library/imaplib.html#imaplib.IMAP4):

#### `[imaplib.IMAP4.error]exception IMAP4.error`

Исключение возникает при любых ошибках. Причина исключения передаётся конструктору в виде строки.

#### `[imaplib.IMAP4.abort]exception IMAP4.abort`

Ошибки сервера IMAP4 вызывают это исключение. Оно является подклассом

[`IMAP4.error`](https://python-all.ru/3.0/library/imaplib.html#imaplib.IMAP4.error)

. Обратите внимание, что закрытие экземпляра и создание нового обычно позволяет восстановиться после этого исключения.

#### `[imaplib.IMAP4.readonly]exception IMAP4.readonly`

Это исключение возникает, когда сервер изменяет статус почтового ящика, доступного для записи. Оно является подклассом

[`IMAP4.error`](https://python-all.ru/3.0/library/imaplib.html#imaplib.IMAP4.error)

. Теперь какой-то другой клиент имеет права на запись, и для повторного получения прав на запись потребуется открыть ящик заново.

Также существует подкласс для безопасных соединений:

#### `[imaplib.IMAP4_SSL]class imaplib.IMAP4_SSL([host[, port[, keyfile[, certfile]]]])`

Это подкласс

[`IMAP4`](https://python-all.ru/3.0/library/imaplib.html#imaplib.IMAP4)

, который подключается через SSL-шифрованный сокет (для использования этого класса нужен модуль socket, скомпилированный с поддержкой SSL). Если

*host*

не указан, используется

`''`

(локальный хост). Если

*port*

опущен, используется стандартный IMAP4-over-SSL порт (993).

*keyfile*

и

*certfile*

также необязательны – они могут содержать PEM-форматированный закрытый ключ и файл цепочки сертификатов для SSL-соединения.

Второй подкласс предназначен для соединений, создаваемых дочерним процессом:

#### `[imaplib.IMAP4_stream]class imaplib.IMAP4_stream(command)`

Это подкласс, производный от

[`IMAP4`](https://python-all.ru/3.0/library/imaplib.html#imaplib.IMAP4)

, который подключается к файловым дескрипторам

`stdin/stdout`

, созданным передачей

*command*

в

`subprocess.Popen()`

.

Определены следующие вспомогательные функции:

#### `[imaplib.Internaldate2tuple]imaplib.Internaldate2tuple(datestr)`

Преобразует строку INTERNALDATE IMAP4 во всемирное координированное время. Возвращает кортеж модуля

[`time`](https://python-all.ru/3.0/library/time.html#module-time)

.

#### `[imaplib.Int2AP]imaplib.Int2AP(num)`

Преобразует целое число в строковое представление, используя символы из набора \[

`A`

..

`P`

\].

#### `[imaplib.ParseFlags]imaplib.ParseFlags(flagstr)`

Преобразует ответ IMAP4

`FLAGS`

в кортеж отдельных флагов.

#### `[imaplib.Time2Internaldate]imaplib.Time2Internaldate(date_time)`

Преобразует кортеж модуля

[`time`](https://python-all.ru/3.0/library/time.html#module-time)

в представление IMAP4

`INTERNALDATE`

. Возвращает строку вида:

`"DD-Mmm-YYYY HH:MM:SS +HHMM"`

(включая dвойные кавычки).

Обратите внимание, что номера сообщений IMAP4 изменяются при изменении почтового ящика; в частности, после выполнения команды `EXPUNGE`, удаляющей сообщения, оставшиеся сообщения перенумеровываются. Поэтому настоятельно рекомендуется использовать UID с командой UID.

В конце модуля есть тестовый раздел, содержащий более полный пример использования.

> **См. также**
>
> Документы, описывающие протокол, а также исходные коды и бинарные сборки для серверов, реализующих его, можно найти в *IMAP Information Center* Вашингтонского университета ([http://www.washington.edu/imap/](https://python-all.ru/3.0/library/imaplib.html)).

## Объекты IMAP4

Все команды IMAP4rev1 представлены методами с теми же именами, в верхнем или нижнем регистре.

Все аргументы команд преобразуются в строки, за исключением `AUTHENTICATE` и последнего аргумента `APPEND`, который передаётся как литерал IMAP4. При необходимости (если строка содержит символы, чувствительные к протоколу IMAP4, и не заключена в круглые скобки или двойные кавычки) каждая строка заключается в кавычки. Однако аргумент *password* команды `LOGIN` всегда заключается в кавычки. Если требуется избежать заключения строки аргумента в кавычки (например, аргумент *flags* команды `STORE`), то заключите строку в круглые скобки (например: `r'(\Deleted)'`).

Каждая команда возвращает кортеж: `(type, [data, ...])`, где *type* обычно равно `'OK'` или `'NO'`, а *data* – это либо текст ответа команды, либо обязательные результаты команды. Каждый *data* – это строка или кортеж. Если это кортеж, то первая часть – заголовок ответа, а вторая часть содержит данные (т.е. «литеральное» значение).

Параметр *message\_set* в командах ниже – это строка, задающая одно или несколько сообщений, над которыми нужно выполнить действие. Это может быть простой номер сообщения (`'1'`), диапазон номеров сообщений (`'2:4'`) или группа несмежных диапазонов, разделённых запятыми (`'1:3,6:9'`). Диапазон может содержать звёздочку для обозначения бесконечной верхней границы (`'3:*'`).

Экземпляр [`IMAP4`](https://python-all.ru/3.0/library/imaplib.html#imaplib.IMAP4) имеет следующие методы:

#### `[imaplib.IMAP4.append]IMAP4.append(mailbox, flags, date_time, message)`

Добавляет

*message*

в указанный почтовый ящик.

#### `[imaplib.IMAP4.authenticate]IMAP4.authenticate(mechanism, authobject)`

Команда аутентификации – требуется обработка ответа.

*mechanism* указывает, какой механизм аутентификации следует использовать; он должен присутствовать в переменной экземпляра `capabilities` в форме `AUTH=mechanism`.

*authobject* должен быть вызываемым объектом:

```python
data = authobject(response)
```

Она будет вызвана для обработки серверных ответов продолжения. Она должна возвращать `data`, которые будут закодированы и отправлены на сервер. Она должна возвращать `None`, если вместо этого должен быть отправлен ответ `*` об отмене клиентом.

#### `[imaplib.IMAP4.check]IMAP4.check()`

Контрольная точка почтового ящика на сервере.

#### `[imaplib.IMAP4.close]IMAP4.close()`

Закрывает текущий выбранный почтовый ящик. Удаленные сообщения удаляются из доступного для записи почтового ящика. Это рекомендуемая команда перед

`LOGOUT`

.

#### `[imaplib.IMAP4.copy]IMAP4.copy(message_set, new_mailbox)`

Копирует сообщения

*message\_set*

в конец

*new\_mailbox*

.

#### `[imaplib.IMAP4.create]IMAP4.create(mailbox)`

Создаёт новый почтовый ящик с именем

*mailbox*

.

#### `[imaplib.IMAP4.delete]IMAP4.delete(mailbox)`

Удаляет старый почтовый ящик с именем

*mailbox*

.

#### `[imaplib.IMAP4.deleteacl]IMAP4.deleteacl(mailbox, who)`

Удалить ACL (убрать все права), установленные для who на mailbox.

#### `[imaplib.IMAP4.expunge]IMAP4.expunge()`

Окончательно удаляет удаленные сообщения из выбранного почтового ящика. Генерирует ответ

`EXPUNGE`

для каждого удаленного сообщения. Возвращаемые данные содержат список номеров сообщений

`EXPUNGE`

в порядке получения.

#### `[imaplib.IMAP4.fetch]IMAP4.fetch(message_set, message_parts)`

Извлекает (части) сообщений.

*message\_parts*

должна быть строкой с именами частей сообщения, заключенными в круглые скобки, например:

`"(UID BODY[TEXT])"`

. Возвращаемые данные представляют собой кортежи, содержащие конверт и данные части сообщения.

#### `[imaplib.IMAP4.getacl]IMAP4.getacl(mailbox)`

Получает

`ACL`

для

*mailbox*

. Этот метод является нестандартным, но поддерживается сервером

`Cyrus`

.

#### `[imaplib.IMAP4.getannotation]IMAP4.getannotation(mailbox, entry, attribute)`

Извлекает указанные

`ANNOTATION`

для

*mailbox*

. Метод является нестандартным, но поддерживается сервером

`Cyrus`

.

#### `[imaplib.IMAP4.getquota]IMAP4.getquota(root)`

Получает использование ресурсов и лимиты

`quota`

*root*

. Этот метод является частью расширения QUOTA IMAP4, определённого в RFC 2087.

#### `[imaplib.IMAP4.getquotaroot]IMAP4.getquotaroot(mailbox)`

Получает список

`quota`

`roots`

для указанного

*mailbox*

. Этот метод является частью расширения QUOTA IMAP4, определённого в RFC 2087.

#### `[imaplib.IMAP4.list]IMAP4.list([directory[, pattern]])`

Выводит имена почтовых ящиков в

*directory*

, соответствующие

*pattern*

.

*directory*

по умолчанию равен корневой почтовой папке, а

*pattern*

по умолчанию соответствует всему. Возвращаемые данные содержат список ответов

`LIST`

.

#### `[imaplib.IMAP4.login]IMAP4.login(user, password)`

Идентифицирует клиента с помощью пароля в открытом виде. Параметр

*password*

будет заключён в кавычки.

#### `[imaplib.IMAP4.login_cram_md5]IMAP4.login_cram_md5(user, password)`

Принудительно использует аутентификацию

`CRAM-MD5`

при идентификации клиента для защиты пароля. Работает только в том случае, если ответ сервера

`CAPABILITY`

содержит строку

`AUTH=CRAM-MD5`

.

#### `[imaplib.IMAP4.logout]IMAP4.logout()`

Закрывает соединение с сервером. Возвращает ответ сервера

`BYE`

.

#### `[imaplib.IMAP4.lsub]IMAP4.lsub([directory[, pattern]])`

Выводит список подписанных почтовых ящиков в указанном каталоге, соответствующих шаблону. По умолчанию

*directory*

– корневой каталог, а

*pattern*

– любой почтовый ящик. Возвращаемые данные – кортежи из конверта части сообщения и данных.

#### `[imaplib.IMAP4.myrights]IMAP4.myrights(mailbox)`

Показывает списки управления доступом (ACL) почтового ящика (т.е. права, которые у клиента есть на этот ящик).

#### `[imaplib.IMAP4.namespace]IMAP4.namespace()`

Возвращает пространства имён IMAP согласно RFC2342.

#### `[imaplib.IMAP4.noop]IMAP4.noop()`

Отправляет

`NOOP`

на сервер.

#### `[imaplib.IMAP4.open]IMAP4.open(host, port)`

Открывает сокет на

*port*

на

*host*

. Объекты соединения, установленные этим методом, будут использоваться в методах

`read`

,

`readline`

,

`send`

и

`shutdown`

. Этот метод можно переопределить.

#### `[imaplib.IMAP4.partial]IMAP4.partial(message_num, message_part, start, length)`

Извлекает усечённую часть сообщения. Возвращаемые данные – кортеж из конверта части сообщения и данных.

#### `[imaplib.IMAP4.proxyauth]IMAP4.proxyauth(user)`

Предполагает аутентификацию от имени пользователя

*user*

. Позволяет авторизованному администратору выполнять прокси-доступ к почтовому ящику любого пользователя.

#### `[imaplib.IMAP4.read]IMAP4.read(size)`

Читает

*size*

байт с удалённого сервера. Этот метод можно переопределить.

#### `[imaplib.IMAP4.readline]IMAP4.readline()`

Читает одну строку с удалённого сервера. Этот метод можно переопределить.

#### `[imaplib.IMAP4.recent]IMAP4.recent()`

Запрашивает у сервера обновление. Возвращаемые данные –

`None`

, если нет новых сообщений, иначе значение ответа

`RECENT`

.

#### `[imaplib.IMAP4.rename]IMAP4.rename(oldmailbox, newmailbox)`

Переименовывает почтовый ящик с именем

*oldmailbox*

в

*newmailbox*

.

#### `[imaplib.IMAP4.response]IMAP4.response(code)`

Возвращает данные для ответа

*code*

, если он получен, или

`None`

. Возвращает указанный код, а не обычный тип.

#### `[imaplib.IMAP4.search]IMAP4.search(charset, criterion[, ...])`

Ищет в почтовом ящике сообщения, соответствующие критериям. *charset* может быть `None`, в этом случае в запросе к серверу не будет указан `CHARSET`. Протокол IMAP требует указания хотя бы одного критерия; при возврате ошибки сервером будет возбуждено исключение.

Пример:

```python
# M – это подключенный экземпляр IMAP4...
typ, msgnums = M.search(None, 'FROM', '"LDJ"')

# или:
typ, msgnums = M.search(None, '(FROM "LDJ")')
```

#### `[imaplib.IMAP4.select]IMAP4.select([mailbox[, readonly]])`

Выбирает почтовый ящик. Возвращаемые данные – количество сообщений в

*mailbox*

(ответ

`EXISTS`

). Ящик по умолчанию –

*mailbox*

, это

`'INBOX'`

. Если установлен флаг

*readonly*

, изменения в ящике запрещены.

#### `[imaplib.IMAP4.send]IMAP4.send(data)`

Отправляет

`data`

на удалённый сервер. Этот метод можно переопределить.

#### `[imaplib.IMAP4.setacl]IMAP4.setacl(mailbox, who, what)`

Устанавливает

`ACL`

для

*mailbox*

. Этот метод является нестандартным, но поддерживается сервером

`Cyrus`

.

#### `[imaplib.IMAP4.setannotation]IMAP4.setannotation(mailbox, entry, attribute[, ...])`

Устанавливает

`ANNOTATION`

для

*mailbox*

. Этот метод является нестандартным, но поддерживается сервером

`Cyrus`

.

#### `[imaplib.IMAP4.setquota]IMAP4.setquota(root, limits)`

Устанавливает

`quota`

ресурса

*root*

–

*limits*

. Этот метод является частью расширения QUOTA протокола IMAP4, определённого в RFC 2087.

#### `[imaplib.IMAP4.shutdown]IMAP4.shutdown()`

Закрывает соединение, установленное в

`open`

. Этот метод можно переопределить.

#### `[imaplib.IMAP4.socket]IMAP4.socket()`

Возвращает экземпляр сокета, используемый для подключения к серверу.

#### `[imaplib.IMAP4.sort]IMAP4.sort(sort_criteria, charset, search_criterion[, ...])`

Команда `sort` является разновидностью `search` с семантикой сортировки результатов. Возвращаемые данные содержат разделённый пробелами список номеров подходящих сообщений.

У sort есть два аргумента перед *search\_criterion*: заключённый в скобки список *sort\_criteria* и *charset* для поиска. Обратите внимание: в отличие от `search`, аргумент *charset* является обязательным. Также существует команда `uid sort`, которая соотносится с `sort` так же, как `uid search` соотносится с `search`. Команда `sort` сначала ищет в почтовом ящике сообщения, соответствующие заданным критериям поиска, используя аргумент charset для интерпретации строк в критериях. Затем она возвращает номера подходящих сообщений.

Это расширенная команда `IMAP4rev1`.

#### `[imaplib.IMAP4.status]IMAP4.status(mailbox, names)`

Запрашивает именованные условия состояния для

*mailbox*

.

#### `[imaplib.IMAP4.store]IMAP4.store(message_set, command, flag_list)`

Изменяет состояния флагов для сообщений в почтовом ящике. Параметр *command* задаётся в разделе 6.4.6 документа [**RFC 2060**](https://python-all.ru/3.0/library/imaplib.html) как одно из значений «FLAGS», «+FLAGS» или «-FLAGS», возможно с суффиксом «.SILENT».

Например, чтобы установить флаг удаления на все сообщения:

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

#### `[imaplib.IMAP4.subscribe]IMAP4.subscribe(mailbox)`

Подписаться на новый почтовый ящик.

#### `[imaplib.IMAP4.thread]IMAP4.thread(threading_algorithm, charset, search_criterion[, ...])`

Команда `thread` является вариантом `search` с семантикой threading для результатов. Возвращаемые данные содержат разделённый пробелами список участников threading.

Участники ветвей состоят из нуля или более номеров сообщений, разделенных пробелами, указывающих последовательные родительские и дочерние элементы.

Команда thread принимает два аргумента перед аргументом(ами) *search\_criterion*: *threading\_algorithm* и *charset* поиска. Обратите внимание, что в отличие от `search`, аргумент *charset* поиска является обязательным. Также существует команда `uid thread`, которая соответствует `thread` так же, как `uid search` соответствует `search`. Команда `thread` сначала ищет в почтовом ящике сообщения, соответствующие заданным критериям поиска, используя аргумент charset для интерпретации строк в критериях поиска. Затем она возвращает соответствующие сообщения, сгруппированные в соответствии с заданным алгоритмом threading.

Это расширенная команда `IMAP4rev1`.

#### `[imaplib.IMAP4.uid]IMAP4.uid(command, arg[, ...])`

Выполняет команду с аргументами для сообщений, идентифицированных по UID, а не по номеру сообщения. Возвращает ответ, соответствующий команде. Должен быть указан по крайней мере один аргумент; если ни одного не передано, сервер вернет ошибку, и будет возбуждено исключение.

#### `[imaplib.IMAP4.unsubscribe]IMAP4.unsubscribe(mailbox)`

Отписаться от старого почтового ящика.

#### `[imaplib.IMAP4.xatom]IMAP4.xatom(name[, arg[, ...]])`

Разрешает простые расширенные команды, уведомляемые сервером в ответе

`CAPABILITY`

.

Следующие атрибуты определены для экземпляров [`IMAP4`](https://python-all.ru/3.0/library/imaplib.html#imaplib.IMAP4):

#### `[imaplib.IMAP4.PROTOCOL_VERSION]IMAP4.PROTOCOL_VERSION`

Последняя поддерживаемая версия протокола в ответе

`CAPABILITY`

от сервера.

#### `[imaplib.IMAP4.debug]IMAP4.debug`

Целое число для управления отладочным выводом. Начальное значение берётся из модульной переменной

`Debug`

. Значения больше трёх трассируют каждую команду.

## Пример IMAP4

Вот минимальный пример (без проверки ошибок), который открывает почтовый ящик и извлекает и выводит все сообщения:

```python
import getpass, imaplib

M = imaplib.IMAP4()
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()
```