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

Объекты IMAP4

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

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

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

Параметр 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)

Получить использование ресурсов и лимиты для root quota. Этот метод является частью расширения 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)

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

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

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. Обратитесь к Рекомендациям по безопасности для оптимальной практики.

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

Изменено в версии 3.4: Метод теперь поддерживает проверку имени хоста с помощью ssl.SSLContext.check_hostname и указания имени сервера (см. 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; алгоритм ветвления и набор charset для поиска. В отличие от search, аргумент charset для поиска обязателен. Также существует команда uid thread, которая соответствует команде thread, так же как uid search соответствует search. Команда thread сначала ищет в почтовом ящике сообщения, соответствующие заданным критериям поиска, используя аргумент charset для интерпретации строк в критериях поиска. Затем она возвращает сообщения, сгруппированные по ветвям согласно указанному алгоритму.

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

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

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

IMAP4.unsubscribe(mailbox)

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

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