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

Исходный код: Lib/smtplib.py

Модуль smtplib определяет объект сеанса SMTP-клиента, который может использоваться для отправки почты на любой компьютер в Интернете с SMTP или ESMTP-сервером. Для получения подробной информации об операциях SMTP и ESMTP обратитесь к RFC 821 (Простой протокол передачи почты) и RFC 1869 (Расширения службы SMTP).

class smtplib.SMTP(host='', port=0, local_hostname=None, [timeout, ]source_address=None)

Экземпляр SMTP инкапсулирует SMTP-соединение. Он имеет методы, которые поддерживают полный набор операций SMTP и ESMTP. Если необязательные параметры host и port указаны, метод SMTP connect() вызывается с этими параметрами во время инициализации. Если указано, local_hostname используется в качестве FQDN локального хоста в команде HELO/EHLO. В противном случае локальное имя хоста находится с помощью socket.getfqdn(). Если вызов connect() возвращает что-либо, кроме кода успеха, генерируется SMTPConnectError. Необязательный параметр timeout задает таймаут в секундах для блокирующих операций, таких как попытка подключения (если не указано, используется глобальная настройка таймаута по умолчанию). Если таймаут истечет, будет возбуждено исключение socket.timeout. Необязательный параметр source_address позволяет привязываться к определенному адресу источника на машине с несколькими сетевыми интерфейсами и/или к определенному TCP-порту источника. Он принимает кортеж из 2 элементов (host, port) для сокета, к которому нужно привязаться в качестве адреса источника перед подключением. Если он опущен (или если host или port равны '' и/или 0 соответственно), будет использовано поведение по умолчанию ОС.

Для нормального использования вам потребуются только методы инициализации/подключения, sendmail() и quit(). Пример приведен ниже.

Класс SMTP поддерживает оператор with. При использовании таким образом, команда SMTP QUIT автоматически выполняется при завершении оператора with. Пример:

>>> from smtplib import SMTP
>>> with SMTP("domain.org") as smtp:
...     smtp.noop()
...
(250, b'Ok')
>>>

Изменено в версии 3.3: Добавлена поддержка оператора with.

Изменено в версии 3.3: Добавлен аргумент source_address.

Добавлен в версии 3.5: Теперь поддерживается расширение SMTPUTF8 (RFC 6531).

class smtplib.SMTP_SSL(host='', port=0, local_hostname=None, keyfile=None, certfile=None, [timeout, ]context=None, source_address=None)

Экземпляр SMTP_SSL ведет себя точно так же, как экземпляры SMTP. SMTP_SSL следует использовать в ситуациях, где SSL требуется с самого начала соединения, и использование starttls() неприемлемо. Если host не указан, используется локальный хост. Если port равен нулю, используется стандартный порт SMTP-over-SSL (465). Необязательные аргументы local_hostname, timeout и source_address имеют то же значение, что и в классе SMTP. Необязательный параметр context может содержать SSLContext и позволяет настраивать различные аспекты защищенного соединения. Для получения рекомендаций по лучшим практикам ознакомьтесь с разделом Безопасность.

keyfile и certfile — это устаревший альтернативный способ передаче параметров вместо context, и могут указывать на файл с закрытым ключом и цепочкой сертификатов в формате PEM для SSL-соединения.

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

Изменено в версии 3.3: Добавлен аргумент source_address.

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

class smtplib.LMTP(host='', port=LMTP_PORT, local_hostname=None, source_address=None)

Протокол LMTP, очень похожий на ESMTP, в значительной степени основан на стандартном SMTP-клиенте. Часто для LMTP используются сокеты Unix, поэтому наш метод connect() должен поддерживать их, а также обычный сервер host:port. Необязательные аргументы local_hostname и source_address имеют то же значение, что и в классе SMTP. Для указания сокета Unix необходимо использовать абсолютный путь к host, начинающийся с '/'.

Поддерживается аутентификация, использующая обычный механизм SMTP. При использовании сокета Unix LMTP, как правило, не поддерживает или не требует аутентификации, но ваши результаты могут отличаться.

Также определен ряд исключений:

exception smtplib.SMTPException

Подкласс OSError, который является базовым классом исключений для всех других исключений, предоставляемых этим модулем.

Изменено в версии 3.4: SMTPException стал подклассом OSError.

exception smtplib.SMTPServerDisconnected

Это исключение генерируется, когда сервер неожиданно отключается или когда попытка использования экземпляра SMTP осуществляется до подключения его к серверу.

exception smtplib.SMTPResponseException

Базовый класс для всех исключений, которые содержат код ошибки SMTP. Эти исключения генерируются в некоторых случаях, когда SMTP-сервер возвращает код ошибки. Код ошибки хранится в атрибуте smtp_code ошибки, а атрибут smtp_error устанавливается в сообщение об ошибке.

exception smtplib.SMTPSenderRefused

Адрес отправителя отклонен. В дополнение к атрибутам, установленным во всех исключениях SMTPResponseException, этот исключение устанавливает ‘sender’ в строку, отклоненную SMTP-сервером.

exception smtplib.SMTPRecipientsRefused

Все адреса получателей отклонены. Ошибки для каждого получателя доступны через атрибут recipients, который является словарем, имеющим точно такой же вид, как и словарь, возвращаемый методом SMTP.sendmail().

exception smtplib.SMTPDataError

SMTP-сервер отказался принять данные сообщения.

exception smtplib.SMTPConnectError

Во время установления соединения с сервером произошла ошибка.

exception smtplib.SMTPHeloError

Сервер отклонил наше сообщение HELO.

exception smtplib.SMTPNotSupportedError

Попытанная команда или опция не поддерживается сервером.

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

exception smtplib.SMTPAuthenticationError

Произошла ошибка при аутентификации SMTP. Вероятнее всего, сервер не принял предоставленную комбинацию имени пользователя/пароля.

1. Объекты SMTP

У экземпляра 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). Если имя хоста заканчивается двоеточием (':') за которым следует число, этот суффикс будет удален, а число интерпретируется как номер порта, который следует использовать. Этот метод автоматически вызывается конструктором, если имя хоста указано во время создания экземпляра. Возвращает кортеж из двух элементов: код ответа и сообщение, отправленное сервером в ответ на подключение.

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

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

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

data = authobject(challenge=None)

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

Если проверка начального ответа вернет None, или если initial_response_ok равен false, authobject() будет вызван для обработки ответа сервера на вызов; аргумент challenge, который он получит, будет bytes. Он должен вернуть байты 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(keyfile=None, certfile=None, context=None)

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

Если заданы keyfile и certfile, они передаются в функцию socket модуля ssl().

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

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

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

2. Пример 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()