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 в почтовый ящик с заданным именем.

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)

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

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

IMAP4.logout()

Отключить подключение к серверу. Возвращает ответ сервера BYE.

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

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

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

IMAP4.myrights(mailbox)

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

IMAP4.namespace()

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

IMAP4.noop()

Отправить NOOP на сервер.

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

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

Вызывает событие аудита auditing event 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 с ограничениями limits. Этот метод является частью расширения 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. Для получения рекомендаций ознакомьтесь с Учтите рекомендации по безопасности.

Введено в версии 3.2.

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

IMAP4.status(mailbox, names)

Запрос параметров состояния mailbox.

IMAP4.store(message_set, command, flag_list)

Изменяет флаги сообщений в почтовом ящике. command указан в разделе 6.4.6 RFC 2060 как один из «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[, ...])

Выполняет команду args с идентификацией сообщений по 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()
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()