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.

Изменено в версии 3.13.8: если поддержка MD5 недоступна, возбуждается исключение IMAP4.error.

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 требует указать хотя бы один критерий; если сервер вернёт ошибку, будет возбуждено исключение. Значение 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)

Устанавливает ограничения 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)

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

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

Команда thread принимает два аргумента перед аргументами search_criterion: алгоритм 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()