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

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

Каждый из методов аутентификации, поддерживаемых smtplib, пытается использоваться по очереди, если они объявлены как поддерживаемые сервером. Список поддерживаемых методов аутентификации см. в 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 для указанного механизма аутентификации и обработайте ответ на вызов с помощью authobject.

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

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

data = authobject(challenge=None)

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

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

Класс SMTP предоставляет реализацию для механизмов 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 (Transport Layer Security). Все последующие команды 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

Поддержка 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, метод сначала попробует ESMTP EHLO. Если сервер поддерживает ESMTP, размер сообщения и каждая из указанных опций будут переданы ему (если опция присутствует в наборе функций, которые сервер объявил). Если ESMTP неудачен, будет использоваться 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

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

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):")

# Add the From: and To: headers at the start!
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()