imaplib — клиент протокола IMAP4

Объекты IMAP4

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

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

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

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

Экземпляр IMAP4 имеет следующие методы:

IMAP4.append(mailbox, flags, date_time, message)

Добавляет message в почтовый ящик с указанным именем.

flags может быть None или строкой токенов флагов IMAP. Несколько флагов разделяются пробелами, например r'\Seen \Answered'. Если flags еще не заключен в круглые скобки, они добавляются автоматически.

IMAP4.authenticate(mechanism, authobject)

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

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

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

data = authobject(response)

Он будет вызван для обработки ответов сервера, требующих продолжения; передаваемый ему аргумент response будет иметь значение bytes. Он должен возвращать bytes data, которое будет закодировано в Base64 и отправлено серверу. Если вместо этого следует отправить ответ прерывания клиента *, он должен вернуть None.

Изменено в версии 3.5: строковые имена пользователей и пароли теперь кодируются в utf-8, а не ограничиваются ASCII.

IMAP4.check()

Выполняет контрольную проверку почтового ящика на сервере.

IMAP4.close()

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

IMAP4.copy(message_set, new_mailbox)

Копирует сообщения message_set в конец почтового ящика new_mailbox.

IMAP4.create(mailbox)

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

IMAP4.delete(mailbox)

Удаляет существующий почтовый ящик с именем mailbox.

IMAP4.deleteacl(mailbox, who)

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

IMAP4.enable(capability)

Включает возможность capability (см. RFC 5161). Большинство возможностей не требуется включать. В настоящее время поддерживается только возможность UTF8=ACCEPT (см. RFC 6855).

Добавлено в версии 3.5: сам метод enable() и поддержка RFC 6855.

IMAP4.expunge()

Окончательно удаляет помеченные для удаления элементы из выбранного почтового ящика. Для каждого удаленного сообщения генерируется ответ EXPUNGE. Возвращаемые данные содержат список номеров сообщений EXPUNGE в порядке их получения.

IMAP4.fetch(message_set, message_parts)

Извлекает сообщения (или их части). message_parts должна быть строкой с именами частей сообщения, заключенными в круглые скобки, например "(UID BODY[TEXT])". Возвращаемые данные представляют собой кортежи из конверта части сообщения и данных.

IMAP4.getacl(mailbox)

Получает ACL для mailbox. Метод не является стандартным, но поддерживается сервером Cyrus.

IMAP4.getannotation(mailbox, entry, attribute)

Получает указанные ANNOTATION для mailbox. Метод не является стандартным, но поддерживается сервером Cyrus.

IMAP4.getquota(root)

Получает сведения об использовании ресурсов и ограничениях quota root. Этот метод входит в расширение IMAP4 QUOTA, определенное в rfc2087.

IMAP4.getquotaroot(mailbox)

Получает список quota roots для указанного mailbox. Этот метод входит в расширение IMAP4 QUOTA, определенное в rfc2087.

IMAP4.idle(duration=None)

Возвращает Idler: итерируемый менеджер контекста, реализующий команду IMAP4 IDLE, определенную в RFC 2177.

Возвращенный объект отправляет команду IDLE при активации оператором with, выдает не помеченные тегами ответы IMAP через протокол итератора и отправляет DONE при выходе из контекста.

Все не помеченные тегами ответы, поступившие после отправки команды IDLE (включая ответы, полученные до подтверждения команды сервером), будут доступны при итерации. Любые оставшиеся ответы (те, по которым не выполнялась итерация в контексте with) можно получить обычным способом после завершения IDLE с помощью IMAP4.response().

Ответы представлены в виде кортежей (type, [data, ...]), как описано в разделе Объекты IMAP4.

Аргумент duration задает максимальную продолжительность ожидания (в секундах), по истечении которой текущая итерация остановится. Это может быть int или float, либо None для отсутствия ограничения по времени. Вызывающим сторонам, которые хотят избежать тайм-аутов бездействия на серверах, использующих такие ограничения, следует задавать значение не более 29 минут (1740 секунд). Требуется подключение через сокет; для соединений IMAP4_stream значение duration должно быть None.

>>> 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)

Выдает группу ответов, поступивших с интервалом не более interval секунд (значение задается как int или float).

Этот генератор служит альтернативой получению ответов по одному и предназначен для эффективной пакетной обработки. Он получает следующий ответ вместе со всеми последующими ответами, которые доступны немедленно. (Например, быструю последовательность ответов EXPUNGE после массового удаления.)

Требуется подключение через сокет; не работает для соединений IMAP4_stream.

>>> 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'])]

Совет

Максимальная продолжительность контекста IDLE, переданная в IMAP4.idle(), учитывается при ожидании первого ответа в группе. Поэтому истекший Idler приведет к немедленному завершению генератора без выдачи каких-либо данных. Если вы используете его в цикле, учитывайте это.

Примечание

Итератор, возвращенный IMAP4.idle(), можно использовать только внутри оператора with. До или после этого контекста незапрошенные ответы собираются внутри программы при каждом завершении команды; их можно получить с помощью IMAP4.response().

Примечание

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

Добавлено в версии 3.14.

IMAP4.list(directory='', pattern='*')

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

IMAP4.login(user, password)

Идентифицирует клиента с помощью пароля в открытом виде. Аргумент password будет заключен в кавычки.

IMAP4.login_cram_md5(user, password)

Принудительно использует аутентификацию CRAM-MD5 при идентификации клиента для защиты пароля. Работает только в том случае, если ответ сервера CAPABILITY содержит фразу AUTH=CRAM-MD5.

Изменено в версии 3.14: если поддержка MD5 недоступна, возникает исключение IMAP4.error.

IMAP4.logout()

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

Изменено в версии 3.8: метод больше не игнорирует произвольные исключения без уведомления.

IMAP4.lsub(directory='', pattern='*')

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

IMAP4.myrights(mailbox)

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

IMAP4.namespace()

Возвращает пространства имен IMAP, определенные в RFC 2342.

IMAP4.noop()

Отправляет серверу NOOP.

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

Открывает сокет на port узла host. Необязательный параметр timeout задает время ожидания попытки подключения в секундах. Если параметр timeout не задан или равен None, используется глобальное значение тайм-аута сокета по умолчанию. Также обратите внимание: если параметр timeout равен нулю, возникнет исключение ValueError, запрещающее создание неблокирующего сокета. Этот метод неявно вызывается конструктором IMAP4. Объекты соединения, созданные этим методом, используются методами IMAP4.read(), IMAP4.readline(), IMAP4.send() и IMAP4.shutdown(). Этот метод можно переопределить.

Вызывает событие аудита imaplib.open с аргументами self, host, port.

Изменено в версии 3.9: добавлен параметр timeout.

IMAP4.partial(message_num, message_part, start, length)

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

IMAP4.proxyauth(user)

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

IMAP4.read(size)

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

IMAP4.readline()

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

IMAP4.recent()

Запрашивает у сервера обновление. Возвращаемые данные равны None, если новых сообщений нет; в противном случае возвращается значение ответа RECENT.

IMAP4.rename(oldmailbox, newmailbox)

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

IMAP4.response(code)

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

IMAP4.search(charset, criterion[, ...])

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

Пример:

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

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

IMAP4.select(mailbox='INBOX', readonly=False)

Выбирает почтовый ящик. Возвращаемые данные — количество сообщений в mailbox (ответ EXISTS). По умолчанию mailbox равен 'INBOX'. Если установлен флаг readonly, изменять почтовый ящик нельзя.

IMAP4.send(data)

Отправляет data удаленному серверу. Этот метод можно переопределить.

Вызывает событие аудита imaplib.send с аргументами self, data.

IMAP4.setacl(mailbox, who, what)

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

IMAP4.setannotation(mailbox, entry, attribute[, ...])

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

IMAP4.setquota(root, limits)

Устанавливает ограничения на использование ресурсов для quota root. Этот метод входит в расширение IMAP4 QUOTA, определенное в rfc2087.

IMAP4.shutdown()

Закрывает соединение, установленное в open. Этот метод неявно вызывается методом IMAP4.logout(). Этот метод можно переопределить.

IMAP4.socket()

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

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.

IMAP4.starttls(ssl_context=None)

Отправляет команду STARTTLS. Аргумент ssl_context необязателен и должен быть объектом ssl.SSLContext. Он включает шифрование соединения IMAP. Рекомендации по обеспечению безопасности см. в разделе Рекомендации по безопасности.

Примечание

При использовании ssl_context по умолчанию соединение шифруется, но сертификат сервера и имя узла не проверяются. Чтобы проверять их, передайте контекст, созданный с помощью ssl.create_default_context().

Добавлено в версии 3.2.

Изменено в версии 3.4: метод теперь поддерживает проверку имени узла с помощью ssl.SSLContext.check_hostname и индикацию имени сервера (см. ssl.HAS_SNI).

IMAP4.status(mailbox, names)

Запрашивает указанные сведения о состоянии почтового ящика mailbox.

IMAP4.store(message_set, command, flag_list)

Изменяет состояние флагов сообщений в почтовом ящике. В соответствии с разделом 6.4.6 RFC 3501, command должен принимать одно из значений “FLAGS”, “+FLAGS” или “-FLAGS”, возможно, с суффиксом “.SILENT”.

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

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

Примечание

Создание флагов, содержащих символ ‘]’ (например, “[test]”), нарушает RFC 3501 (протокол IMAP). Однако imaplib исторически позволял создавать такие флаги, а популярные серверы IMAP, например Gmail, принимают и создают их. Такие флаги создаются и некоторыми программами, не написанными на Python. Несмотря на нарушение RFC и требование к клиентам и серверам IMAP строго соблюдать спецификацию, imaplib по-прежнему позволяет создавать такие флаги для обратной совместимости. Начиная с Python 3.6, он также обрабатывает их, если они отправляются сервером, что повышает совместимость в реальных условиях.

IMAP4.subscribe(mailbox)

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

IMAP4.thread(threading_algorithm, charset, search_criterion[, ...])

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

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

Команда Thread принимает два аргумента перед аргументами search_criterion: алгоритм построения цепочки threading_algorithm и набор символов для поиска charset. Обратите внимание: в отличие от команды search, аргумент charset для поиска обязателен. Существует также команда uid thread, соответствующая thread так же, как uid search соответствует search. Команда thread сначала ищет в почтовом ящике сообщения, соответствующие указанным критериям поиска, используя аргумент charset для интерпретации строк в критериях поиска. Затем она возвращает найденные сообщения, объединенные в цепочки согласно указанному алгоритму.

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

IMAP4.uid(command, arg[, ...])

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

IMAP4.unsubscribe(mailbox)

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

IMAP4.unselect()

Команда imaplib.IMAP4.unselect() освобождает ресурсы сервера, связанные с выбранным почтовым ящиком, и возвращает сервер в состояние аутентификации. Эта команда выполняет те же действия, что и imaplib.IMAP4.close(), но при этом сообщения не удаляются окончательно из текущего выбранного почтового ящика.

Добавлено в версии 3.9.

IMAP4.xatom(name[, ...])

Позволяет использовать простые команды расширения, о которых сервер сообщает в ответе CAPABILITY.

Для экземпляров IMAP4 определены следующие атрибуты:

IMAP4.PROTOCOL_VERSION

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

IMAP4.debug

Целочисленное значение, управляющее выводом отладочной информации. Начальное значение берется из переменной модуля Debug. При значениях больше трех трассируется выполнение каждой команды.

IMAP4.utf8_enabled

Логическое значение, обычно равное False, которое устанавливается в True, если команда enable() успешно выполнена для возможности UTF8=ACCEPT.

Добавлено в версии 3.5.

Пример 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()