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

Перечисляет имена почтовых ящиков в 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)

Показывает мои 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 требует указать хотя бы один критерий; при получении ошибки от сервера будет вызвано исключение. Если возможность UTF8=ACCEPT включена с помощью команды enable(), параметр charset должен иметь значение None.

Пример:

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

Устанавливает limits ресурсов корня quota root. Этот метод входит в расширение IMAP4 QUOTA, определённое в rfc2087.

IMAP4.shutdown()

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

IMAP4.socket()

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

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

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

Перед аргументом search_criterion у команды sort идут два аргумента: заключённый в скобки список 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)

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

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

Перед аргументами 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, если для возможности UTF8=ACCEPT успешно выполняется команда enable().

Добавлено в версии 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()