smtplib — Клиент протокола SMTP

Объекты SMTP

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

SMTP.set_debuglevel(level)

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

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

SMTP.docmd(cmd, args='')

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

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

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

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

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

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

Вызывает событие аудита аудита 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

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

Если сервер рекламирует поддержку нескольких методов аутентификации, они будут перепробованы в определенном порядке. Список поддерживаемых методов аутентификации см. в auth(). initial_response_ok передаётся методу auth().

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

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

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

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

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

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

data = authobject(challenge=None)

Если необязательный ключевой аргумент initial_response_ok равен true, authobject() будет вызван первым без аргументов. Он может вернуть ASCII-строку «начального ответа» RFC 4954 str, которая будет закодирована и отправлена вместе с командой AUTH как указано ниже. Если сервер не поддерживает начальный ответ (например, потому что требует вызов), он должен вернуть 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(keyfile=None, certfile=None, context=None)

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

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

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

Если до этого в сессии не было выполнено ни одной команды EHLO или HELO, метод сначала попытается использовать расширенный SMTP (EHLO).

Устарело начиная с версии 3.6: keyfile и certfile устарели в пользу context. Используйте вместо них ssl.SSLContext.load_cert_chain() или позвольте ssl.create_default_context() выбрать доверенные сертификаты CA вашей системы.

SMTPHeloError

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

SMTPNotSupportedError

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

RuntimeError

Поддержка SSL/TLS недоступна для вашего интерпретатора Python.

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

Изменено в версии 3.4: Метод теперь поддерживает проверку имени хоста с помощью 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 (одиночная строка будет обработана как список с 1 адресом) и строка сообщения. Вызывающая сторона может передать список опций ESMTP (таких как 8bitmime) для использования в командах MAIL FROM в качестве mail_options. Опции ESMTP (такие как DSN команды), которые должны использоваться со всеми командами RCPT, могут быть переданы в качестве rcpt_options. (Если вам нужно использовать разные опции ESMTP для разных получателей, вы должны использовать низкоуровневые методы, такие как mail(), rcpt() и data() для отправки сообщения.)

Примечание

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

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

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

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

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

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

SMTPRecipientsRefused

Все получатели были отклонены. Никто не получил письмо. Атрибут recipients объекта исключения — словарь с информацией об отклоненных получателях (такой же, как возвращаемый, когда был принят хотя бы один получатель).

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, возникает ошибка SMTPNotSupported. В противном случае 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

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

import smtplib

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

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

# Add the From: and To: headers at the start!
msg = ("From: %s\r\nTo: %s\r\n\r\n"
       % (fromaddr, ", ".join(toaddrs)))
while True:
    try:
        line = input()
    except EOFError:
        break
    if not line:
        break
    msg = msg + line

print("Message length is", len(msg))

server = smtplib.SMTP('localhost')
server.set_debuglevel(1)
server.sendmail(fromaddr, toaddrs, msg)
server.quit()