smtplib – клиент протокола SMTP¶smtplib – SMTP protocol client

Объекты SMTP¶SMTP Objects

Экземпляр SMTP имеет следующие методы:

SMTP.set_debuglevel(level)¶

Устанавливает уровень отладочного вывода. Значение 1 или True для параметра level приводит к выводу отладочных сообщений о соединении и обо всех сообщениях, отправленных на сервер и полученных от него. Значение 2 для level добавляет к этим сообщениям временные метки.

Изменено в версии 3.5: Добавлен отладочный уровень 2.

SMTP.docmd(cmd, args='')¶

Отправляет команду cmd серверу. Необязательный аргумент args просто дописывается к команде через пробел.

Возвращает кортеж из двух элементов: числового кода ответа и собственно строки ответа (многострочные ответы объединяются в одну длинную строку).

При обычной работе нет необходимости явно вызывать этот метод. Он используется для реализации других методов и может быть полезен при тестировании частных расширений.

Если соединение с сервером потеряно во время ожидания ответа, будет возбуждено SMTPServerDisconnected.

SMTP.connect(host='localhost', port=0)¶

Подключается к хосту на указанном порту. По умолчанию подключается к локальному хосту на стандартном порту SMTP (25). Если имя хоста заканчивается на двоеточие (':'), за которым следует число, этот суффикс отбрасывается, а число интерпретируется как номер порта для использования. Этот метод автоматически вызывается конструктором, если хост указан при создании экземпляра. Возвращает кортеж из двух элементов: код ответа и сообщение, отправленное сервером в своём ответе на подключение.

Если порт не изменён относительно значения по умолчанию 0, значение атрибута default_port используется.

Вызывает событие аудита smtplib.connect с аргументами self, host, port.

SMTP.helo(name='')¶

Идентифицирует себя перед SMTP-сервером с помощью HELO. Аргумент hostname по умолчанию равен полному доменному имени локального хоста. Сообщение, возвращённое сервером, сохраняется в атрибуте helo_resp объекта.

При обычной работе нет необходимости явно вызывать этот метод. Он будет неявно вызван sendmail() при необходимости.

SMTP.ehlo(name='')¶

Идентифицирует себя на ESMTP-сервере с помощью команды EHLO. Аргумент hostname по умолчанию равен полному доменному имени локального хоста. Анализирует ответ на предмет опций ESMTP и сохраняет их для использования методом has_extn(). Также устанавливает несколько информационных атрибутов: сообщение, возвращённое сервером, сохраняется как атрибут ehlo_resp, does_esmtp устанавливается в True или False в зависимости от того, поддерживает ли сервер ESMTP, а esmtp_features будет словарём, содержащим имена расширений SMTP-сервиса, которые поддерживает этот сервер, и их параметры (если есть).

Если не требуется использовать has_extn() перед отправкой почты, явно вызывать этот метод необязательно. Он будет неявно вызван методом sendmail() при необходимости.

SMTP.ehlo_or_helo_if_needed()¶

Этот метод вызывает ehlo() и/или helo(), если в течение этого сеанса ещё не было выполнено команды EHLO или HELO. Сначала он пробует ESMTP EHLO.

SMTPHeloError

Сервер некорректно ответил на приветствие HELO.

SMTP.has_extn(name)¶

Возвращает True, если name присутствует в наборе расширений SMTP-сервиса, возвращённых сервером, и False в противном случае. Регистр игнорируется.

SMTP.verify(address)¶

Проверяет корректность адреса на этом сервере с помощью SMTP VRFY. Возвращает кортеж, состоящий из кода 250 и полного адреса RFC 822 (включая имя человека), если адрес пользователя действителен. В противном случае возвращает код ошибки SMTP 400 или больше и строку ошибки.

Примечание

Многие сайты отключают SMTP VRFY, чтобы помешать спамерам.

SMTP.login(user, password, *, initial_response_ok=True)¶

Выполняет вход на SMTP-сервер, требующий аутентификации. Аргументами являются имя пользователя и пароль для аутентификации. Если в течение этого сеанса ещё не было выполнено команды EHLO или HELO, этот метод сначала пробует ESMTP EHLO. Этот метод завершается нормально, если аутентификация прошла успешно, или может возбудить следующие исключения:

SMTPHeloError

Сервер некорректно ответил на приветствие HELO.

SMTPAuthenticationError

Сервер не принял комбинацию имя пользователя/пароль.

SMTPNotSupportedError

Команда AUTH не поддерживается сервером.

SMTPException

Не найден подходящий метод аутентификации.

Каждый из методов аутентификации, поддерживаемых smtplib, перебирается по очереди, если сервер объявляет о их поддержке. Список поддерживаемых методов аутентификации см. в auth(). Параметр initial_response_ok передаётся в auth().

Необязательный именованный аргумент initial_response_ok определяет, можно ли для методов аутентификации, которые это поддерживают, отправлять «начальный ответ» (initial response), как указано в RFC 4954, вместе с командой AUTH, а не требовать запроса/ответа (challenge/response).

Изменено в версии 3.5: SMTPNotSupportedError может быть возбуждено, и добавлен параметр initial_response_ok.

SMTP.auth(mechanism, authobject, *, initial_response_ok=True)¶

Отправляет команду SMTP AUTH для указанного механизма аутентификации mechanism и обрабатывает ответ на запрос (challenge response) через authobject.

mechanism указывает, какой механизм аутентификации будет использоваться в качестве аргумента команды AUTH; допустимые значения перечислены в элементе auth словаря esmtp_features.

authobject должен быть вызываемым объектом, принимающим один необязательный аргумент:

data = authobject(challenge=None)

Если необязательный именованный аргумент initial_response_ok равен true, сначала вызывается authobject() без аргументов. Он может вернуть «начальный ответ» RFC 4954 в виде ASCII str, который будет закодирован и отправлен с командой AUTH, как описано ниже. Если authobject() не поддерживает начальный ответ (например, потому что требует запроса), он должен вернуть None при вызове с challenge=None. Если initial_response_ok равен false, то authobject() не будет сначала вызываться с None.

Если проверка начального ответа возвращает None или если initial_response_ok равен false, вызывается authobject() для обработки ответа на запрос сервера; аргумент challenge, который ему передаётся, будет bytes. Он должен вернуть ASCII str data, который будет закодирован в base64 и отправлен на сервер.

Класс SMTP предоставляет authobjects для механизмов CRAM-MD5, PLAIN и LOGIN; они называются SMTP.auth_cram_md5, SMTP.auth_plain и SMTP.auth_login соответственно. Все они требуют, чтобы свойства user и password экземпляра SMTP были установлены в соответствующие значения.

Пользовательскому коду обычно не нужно вызывать auth напрямую; вместо этого можно вызвать метод login(), который переберёт каждый из вышеперечисленных механизмов по порядку. auth предоставляется для упрощения реализации методов аутентификации, не поддерживаемых (пока) напрямую smtplib.

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

SMTP.starttls(*, context=None)¶

Переводит SMTP-соединение в режим TLS (безопасность транспортного уровня). Все последующие SMTP-команды будут зашифрованы. После этого следует снова вызвать ehlo().

Если указаны keyfile и certfile, они используются для создания ssl.SSLContext.

Необязательный параметр context – это объект ssl.SSLContext; это альтернатива использованию keyfile и certfile, и если он указан, то keyfile и certfile должны быть None.

Если в течение этого сеанса ещё не выполнялась команда EHLO или HELO, метод сначала пытается выполнить ESMTP EHLO.

Изменено в версии 3.12: Устаревшие параметры keyfile и certfile были удалены.

SMTPHeloError

Сервер некорректно ответил на приветствие HELO.

SMTPNotSupportedError

Сервер не поддерживает расширение STARTTLS.

RuntimeError

Интерпретатор Python не поддерживает SSL/TLS.

Изменено в версии 3.3: был добавлен параметр context.

Изменено в версии 3.4: Теперь метод поддерживает проверку имени хоста с помощью ssl.SSLContext.check_hostname и Server Name Indicator (см. HAS_SNI).

Изменено в версии 3.5: Исключение, возбуждаемое при отсутствии поддержки STARTTLS, теперь является подклассом SMTPNotSupportedError вместо базового SMTPException.

SMTP.sendmail(from_addr, to_addrs, msg, mail_options=(), rcpt_options=())¶

Отправляет почту. Обязательные аргументы: строка с обратным адресом RFC 822, список строк с адресами получателей RFC 822 (если передана просто строка, она будет считаться списком из одного адреса) и строка сообщения. Вызывающий код может передать список ESMTP-опций (например, "8bitmime"), которые будут использоваться в командах MAIL FROM, через параметр mail_options. ESMTP-опции (например, команды DSN), которые должны применяться ко всем командам RCPT, можно передать через параметр rcpt_options. Каждая опция должна быть передана в виде строки, содержащей полный текст опции, включая возможный ключ (например, "NOTIFY=SUCCESS,FAILURE"). (Если нужно использовать разные ESMTP-опции для разных получателей, придётся воспользоваться низкоуровневыми методами, такими как mail(), rcpt() и data() для отправки сообщения.)

Примечание

Параметры from_addr и to_addrs используются для построения конверта сообщения, используемого транспортными агентами. sendmail никак не изменяет заголовки сообщения.

msg может быть строкой, содержащей символы из диапазона ASCII, или байтовой строкой. Строка кодируется в байты с помощью кодека ascii, а одиночные символы \r и \n преобразуются в символы \r\n. Байтовая строка не изменяется.

Если в течение этого сеанса ещё не выполнялась команда EHLO или HELO, данный метод сначала пытается выполнить ESMTP EHLO. Если сервер поддерживает ESMTP, ему будут переданы размер сообщения и каждая из указанных опций (если опция присутствует в наборе возможностей, объявленных сервером). Если EHLO не удаётся, будет выполнена попытка HELO и ESMTP-опции будут подавлены.

Метод завершается нормально, если почта принята хотя бы одним получателем. В противном случае возбуждается исключение. То есть, если метод не возбуждает исключение, значит, кто-то должен получить ваше письмо. Если метод не возбуждает исключение, он возвращает словарь с одной записью для каждого получателя, которому было отказано. Каждая запись содержит кортеж из кода ошибки SMTP и соответствующего сообщения об ошибке, отправленного сервером.

Если SMTPUTF8 включён в mail_options и сервер это поддерживает, from_addr и to_addrs могут содержать символы, не входящие в ASCII.

Этот метод может возбуждать следующие исключения:

SMTPRecipientsRefused

Всем получателям было отказано. Письмо не доставлено никому.

SMTPHeloError

Сервер некорректно ответил на приветствие HELO.

SMTPSenderRefused

Сервер не принял адрес from_addr.

SMTPDataError

Сервер ответил неожиданным кодом ошибки (не связанным с отказом отдельному получателю).

SMTPNotSupportedError

Параметр SMTPUTF8 был указан в mail_options, но не поддерживается сервером.

Если не указано иное, соединение остаётся открытым даже после возбуждения исключения.

Изменено в версии 3.2: msg может быть байтовой строкой.

Изменено в версии 3.5: Добавлена поддержка SMTPUTF8, и может возбуждаться SMTPNotSupportedError, если указан SMTPUTF8, но сервер его не поддерживает.

SMTP.send_message(msg, from_addr=None, to_addrs=None, mail_options=(), rcpt_options=())¶

Это удобный метод для вызова sendmail() с сообщением, представленным объектом email.message.Message. Аргументы имеют тот же смысл, что и для sendmail(), за исключением того, что msg является объектом Message.

Если from_addr равно None или to_addrs равно None, send_message заполняет эти аргументы адресами, извлечёнными из заголовков msg в соответствии с RFC 5322: from_addr устанавливается в поле Sender, если оно присутствует, иначе – в поле From. to_addrs объединяет значения (если они есть) полей To, Cc и Bcc из msg. Если в сообщении присутствует ровно один набор заголовков Resent-*, обычные заголовки игнорируются, а используются заголовки Resent-*. Если сообщение содержит более одного набора заголовков Resent-*, возбуждается ValueError, поскольку нет способа однозначно определить самый последний набор заголовков Resent-.

send_message сериализует msg с помощью BytesGenerator, используя \r\n в качестве linesep, и вызывает sendmail() для передачи полученного сообщения. Независимо от значений from_addr и to_addrs, send_message не передаёт никакие заголовки Bcc или Resent-Bcc, которые могут присутствовать в msg. Если какой-либо из адресов в from_addr и to_addrs содержит не-ASCII символы и сервер не объявляет поддержку SMTPUTF8, возбуждается SMTPNotSupportedError. В противном случае Message сериализуется с клоном своего policy, в котором атрибут utf8 установлен в True, и SMTPUTF8 и BODY=8BITMIME добавляются в mail_options.

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

Добавлено в версии 3.5: Поддержка интернационализированных адресов (SMTPUTF8).

SMTP.quit()¶

Завершает сеанс SMTP и закрывает соединение. Возвращает результат команды SMTP QUIT.

Также поддерживаются низкоуровневые методы, соответствующие стандартным командам SMTP/ESMTP HELP, RSET, NOOP, MAIL, RCPT и DATA. Обычно их не нужно вызывать напрямую, поэтому они не документированы здесь. Подробнее см. в коде модуля.

Кроме того, экземпляр SMTP имеет следующие атрибуты:

SMTP.helo_resp¶

Ответ на команду HELO, см. helo().

SMTP.ehlo_resp¶

Ответ на команду EHLO, см. ehlo().

SMTP.does_esmtp¶

Логическое значение, указывающее, поддерживает ли сервер ESMTP. См. ehlo().

SMTP.esmtp_features¶

Словарь названий расширений службы SMTP, поддерживаемых сервером. См. ehlo().

Пример SMTP¶SMTP Example

Этот пример запрашивает у пользователя адреса, необходимые для конверта сообщения (адреса «Кому» и «От»), а также само сообщение для отправки. Обратите внимание, что заголовки, которые должны быть включены в сообщение, должны быть введены в самом сообщении; этот пример не выполняет никакой обработки заголовков RFC 822. В частности, адреса «Кому» и «От» должны быть явно указаны в заголовках сообщения:

import smtplib

def prompt(title):
    return input(title).strip()

from_addr = prompt("From: ")
to_addrs  = prompt("To: ").split()
print("Enter message, end with ^D (Unix) or ^Z (Windows):")

# Добавьте заголовки From: и To: в начало!
lines = [f"From: {from_addr}", f"To: {', '.join(to_addrs)}", ""]
while True:
    try:
        line = input()
    except EOFError:
        break
    else:
        lines.append(line)

msg = "\r\n".join(lines)
print("Message length is", len(msg))

server = smtplib.SMTP("localhost")
server.set_debuglevel(1)
server.sendmail(from_addr, to_addrs, msg)
server.quit()