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

В этом примере пользователь вводит необходимые адреса в оболочке сообщения (‘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()