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

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

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