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

Добавить сообщение в названный почтовый ящик.

IMAP4.authenticate(mechanism, authobject)¶

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

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

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

data = authobject(response)

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

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

IMAP4.check()¶

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

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 (удаление любых прав), установленных для who на почтовом ящике.

IMAP4.enable(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)¶

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

IMAP4.getannotation(mailbox, entry, attribute)¶

Получить указанные ANNOTATIONs для 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 по умолчанию соответствует чему угодно. Возвращаемые данные содержат список ответов LIST.

IMAP4.login(user, 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)¶

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

IMAP4.namespace()¶

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

IMAP4.noop()¶

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

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

Открывает сокет к порту на хосте. Необязательный параметр 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)¶

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

IMAP4.read(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 на удаленный сервер. Вы можете переопределить этот метод.

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

IMAP4.setacl(mailbox, who, what)¶

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

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

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

IMAP4.setquota(root, limits)¶

Установите лимиты ресурсов ``quota`` *корня. Этот метод является частью расширения IMAP4 QUOTA, определенного в rfc2087.

IMAP4.shutdown()¶

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

IMAP4.socket()¶

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

IMAP4.sort(sort_criteria, charset, search_criterion[, ...])¶

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

Sort имеет два аргумента перед аргументом(ами) поиск_критерия; список критериев сортировки, заключенный в круглые скобки, и набор символов поиска 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)¶

Изменяет расположение флагов для сообщений в почтовом ящике. команда определена в разделе 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 с семантикой потоков для результатов. Возвращаемые данные содержат разделенный пробелами список членов потока.

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

Перед аргументом (аргументами) search_criterion у Thread есть два аргумента: 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()
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()