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. Этот метод является частью расширения 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, timeout=None)

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

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

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

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