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 порту источника. Он принимает пару из двух элементов (host, port), для того чтобы сокет привязался к этому адресу источника перед подключением. Если он опущен (или если host или port равны '' и/или 0 соответственно), будет использоваться поведение по умолчанию ОС.

Для обычного использования вам потребуются только методы инициализации/подключения, sendmail() и SMTP.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).

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

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, это устанавливает «отправитель» в строку, которую 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. Скорее всего, сервер не принял предоставленную комбинацию имени пользователя/пароля.

Объекты 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 элементов: код ответа и сообщение, отправленное сервером в ответ на подключение.

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() будет вызван сначала без аргументов. Он может вернуть 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 предоставляет реализации для 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, этот метод сначала попробует использовать ESMTP EHLO.

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

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

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