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. Если он указан, значения keyfile и certfile должны быть равны None.

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

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

SMTPHeloError

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

SMTPNotSupportedError

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

RuntimeError

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

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