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)

Удалить разрешения 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.list([directory[, pattern]])

Вывести имена папок в каталоге, соответствующие шаблону 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='*')

Вывести имена подписок папок в каталоге, соответствующие шаблону 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 для интерпретации строк в критериях поиска. Затем она возвращает номера соответствующих сообщений.

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

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 для интерпретации строк в критериях поиска. Затем она возвращает сообщения, сгруппированные в потоки в соответствии со специфицированным алгоритмом потоков.

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

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