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 указывает, можно ли для поддерживающих это методов аутентификации отправить вместе с командой AUTH «начальный ответ», определённый в RFC 4954, вместо использования схемы запрос/ответ.

Изменено в версии 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 str «начального ответа» согласно RFC 4954; эти данные будут закодированы и отправлены вместе с командой AUTH, как описано ниже. Если authobject() не поддерживает начальный ответ (например, поскольку ему требуется запрос), при вызове с challenge=None он должен вернуть None. Если initial_response_ok имеет значение false, authobject() не будет предварительно вызван с None.

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

Класс SMTP предоставляет authobjects для механизмов 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 должны быть None.

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

Изменено в версии 3.12: Устаревшие параметры keyfile и certfile удалены.

SMTPHeloError

Сервер некорректно ответил на приветствие HELO.

SMTPNotSupportedError

Сервер не поддерживает расширение STARTTLS.

RuntimeError

Интерпретатор Python не поддерживает SSL/TLS.

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

Изменено в версии 3.4: Теперь метод поддерживает проверку имени узла с помощью ssl.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. Каждый параметр следует передавать в виде строки с его полным текстом, включая возможный ключ (например, "NOTIFY=SUCCESS,FAILURE"). (Если для разных получателей требуются разные параметры 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

Всем получателям было отказано. Никто не получил письмо.

SMTPHeloError

Сервер некорректно ответил на приветствие HELO.

SMTPSenderRefused

Сервер не принял адрес from_addr.

SMTPDataError

Сервер ответил неожиданным кодом ошибки (не связанным с отказом получателю).

SMTPNotSupportedError

В mail_options указан SMTPUTF8, который сервер не поддерживает.

Если не указано иное, соединение остаётся открытым даже после вызова исключения.

Изменено в версии 3.2: msg может быть байтовой строкой.

Изменено в версии 3.5: Добавлена поддержка SMTPUTF8; если указан SMTPUTF8, но сервер его не поддерживает, может быть вызвано исключение SMTPNotSupportedError.

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, вызывается исключение SMTPNotSupportedError. В противном случае Message сериализуется с клоном его policy, у которого атрибут utf8 установлен в True; в mail_options добавляются SMTPUTF8 и BODY=8BITMIME.

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

Добавлено в версии 3.5: Поддержка интернационализированных адресов (SMTPUTF8).

SMTP.quit()

Завершить сеанс SMTP и закрыть соединение. Возвращает результат команды SMTP QUIT.

Также поддерживаются низкоуровневые методы, соответствующие стандартным командам SMTP/ESMTP HELP, RSET, NOOP, MAIL, RCPT и DATA. Обычно вызывать их напрямую не требуется, поэтому здесь они не описаны. Подробности см. в коде модуля.

Кроме того, экземпляр SMTP имеет следующие атрибуты:

SMTP.helo_resp

Ответ на команду HELO, см. helo().

SMTP.ehlo_resp

Ответ на команду EHLO, см. ehlo().

SMTP.does_esmtp

Логическое значение, указывающее, поддерживает ли сервер ESMTP; см. ehlo().

SMTP.esmtp_features

Словарь с именами поддерживаемых сервером расширений службы SMTP; см. ehlo().

Пример SMTP

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

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()