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

Исходный код: Lib/smtplib.py

Модуль smtplib определяет объект сеанса SMTP-клиента, который можно использовать для отправки почты на любой интернет-машине с SMTP- или ESMTP-сервером-демон. Для получения подробностей о работе SMTP и ESMTP обратитесь к RFC 821 (Простой протокол передачи почты) и RFC 1869 (Расширения сервиса SMTP).

class smtplib.SMTP([host[, port[, local_hostname[, timeout]]]])

Объект SMTP инкапсулирует SMTP-соединение. Он имеет методы, которые поддерживают весь набор операций SMTP и ESMTP. Если заданы необязательные параметры host и port, метод SMTP connect() вызывается с этими параметрами во время инициализации. Если задан параметр local_hostname, он используется в качестве FQDN локального хоста в команде HELO/EHLO. В противном случае локальное имя хоста находится с помощью socket.getfqdn(). Если вызов connect() возвращает что-либо, кроме кода успеха, генерируется SMTPConnectError. Необязательный параметр timeout задаёт таймаут в секундах для блокирующих операций, таких как попытка подключения (если не указан, используется глобальное значение таймаута по умолчанию). Если таймаут истекает, генерируется socket.timeout.

Для обычного использования вам понадобятся только методы инициализации/подключения, sendmail() и SMTP.quit(). Пример приведен ниже.

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

class smtplib.SMTP_SSL([host[, port[, local_hostname[, keyfile[, certfile[, timeout]]]]]])

Объект SMTP_SSL ведет себя точно так же, как объекты класса SMTP. SMTP_SSL следует использовать в ситуациях, когда SSL требуется с самого начала подключения и использование starttls() неприменимо. Если host не указан, используется локальный хост. Если port опущен, используется стандартный порт SMTP-over-SSL (465). local_hostname имеет то же значение, что и для класса SMTP. Параметры keyfile и certfile также необязательны и могут содержать файл закрытого ключа и файл цепочки сертификатов в формате PEM для SSL-соединения. Необязательный параметр timeout задаёт таймаут в секундах для блокирующих операций, таких как попытка подключения (если не указан, используется глобальное значение таймаута по умолчанию). Если таймаут истекает, генерируется socket.timeout.

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

class smtplib.LMTP([host[, port[, local_hostname]]])

Протокол LMTP, очень похожий на ESMTP, в значительной степени основан на стандартном SMTP-клиенте. Для LMTP часто используются сокеты Unix, поэтому наш метод connect() должен поддерживать это, а также обычный сервер host:port. Параметр local_hostname имеет то же значение, что и для класса SMTP. Для указания сокета Unix необходимо использовать абсолютный путь к host, начинающийся с ‘/’.

Поддержка аутентификации с использованием стандартного механизма SMTP. При использовании сокета Unix LMTP обычно не поддерживает и не требует аутентификации, но ваш опыт может отличаться.

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

Также определён ряд исключений:

exception smtplib.SMTPException

Базовый класс исключений для всех других исключений, предоставляемых этим модулем.

exception smtplib.SMTPServerDisconnected

Это исключение генерируется, когда сервер неожиданно отключается или когда попытка использовать объект SMTP выполняется до его подключения к серверу.

exception smtplib.SMTPResponseException

Базовый класс всех исключений, содержащих код ошибки SMTP. Эти исключения генерируются в некоторых случаях, когда SMTP-сервер возвращает код ошибки. Код ошибки хранится в атрибуте smtp_code исключения, а атрибут smtp_error содержит сообщение об ошибке.

exception smtplib.SMTPSenderRefused

Адрес отправителя отклонен. В дополнение к атрибутам, установленным для всех исключений SMTPResponseException, этот атрибут устанавливает ‘sender’ в строку, которую SMTP-сервер отклонил.

exception smtplib.SMTPRecipientsRefused

Все адреса получателей отклонены. Ошибки для каждого получателя доступны через атрибут recipients, который является словарем, аналогичным тому, который возвращает SMTP.sendmail().

exception smtplib.SMTPDataError

SMTP-сервер отказался принять данные сообщения.

exception smtplib.SMTPConnectError

Произошла ошибка при установлении соединения с сервером.

exception smtplib.SMTPHeloError

Сервер отклонил наше сообщение HELO.

exception smtplib.SMTPAuthenticationError

Произошла ошибка SMTP-аутентификации. Вероятнее всего, сервер не принял предоставленную комбинацию имени пользователя/пароля.

1. Объекты SMTP

У объекта SMTP есть следующие методы:

SMTP.set_debuglevel(level)

Установить уровень вывода отладки. Значение level типа true приводит к отображению сообщений отладки для подключения и для всех сообщений, отправленных на сервер и полученных от него.

SMTP.docmd(cmd[, argstring])

Отправить команду cmd на сервер. Необязательный аргумент argstring просто конкатенируется с командой, разделённой пробелом.

Возвращает кортеж из двух элементов: числовой код ответа и фактическая строка ответа (многострочные ответы объединяются в одну длинную строку.)

В обычном режиме нет необходимости вызывать этот метод явно. Он используется для реализации других методов и может быть полезен для тестирования частных расширений.

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

SMTP.connect([host[, port]])

Подключиться к хосту на заданном порту. По умолчанию подключается к локальному хосту на стандартном порту SMTP (25). Если имя хоста оканчивается двоеточием (':') за которым следует число, этот суффикс будет удалён, а число интерпретировано как порт, который нужно использовать. Этот метод автоматически вызывается конструктором, если при инициализации указан хост. Возвращает кортеж из двух элементов: код ответа и сообщение, отправленное сервером в ответ на подключение.

SMTP.helo([hostname])

Представить себя SMTP-серверу с помощью HELO. Аргумент hostname по умолчанию — полное доменное имя локального хоста. Сообщение, возвращённое сервером, хранится в атрибуте helo_resp объекта.

В обычном режиме нет необходимости вызывать этот метод явно. Он будет неявно вызываться методом sendmail() при необходимости.

SMTP.ehlo([hostname])

Представьтесь серверу 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.

В версии 2.6.

SMTP.has_extn(name)

Возвращает True, если name входит в набор расширений SMTP-сервиса, возвращённых сервером, и False в противном случае. Регистр игнорируется.

SMTP.verify(address)

Проверяет валидность адреса на данном сервере с использованием SMTP VRFY. Возвращает кортеж, состоящий из кода 250 и полного адреса RFC 822 (включая имя получателя), если адрес пользователя валиден. В противном случае возвращает код ошибки SMTP 400 или выше и строку ошибки.

Примечание

Многие сайты отключают SMTP VRFY для предотвращения спама.

SMTP.login(user, password)

Вход на SMTP-сервер, требующий аутентификацию. Аргументы — имя пользователя и пароль для аутентификации. Если в текущем сеансе не было предыдущей команды EHLO или HELO, этот метод пытается использовать ESMTP EHLO в первую очередь. Этот метод вернёт результат, если аутентификация прошла успешно, или может вызвать следующие исключения:

SMTPHeloError

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

SMTPAuthenticationError

Сервер не принял комбинацию имени пользователя/пароля.

SMTPException

Не был найден подходящий метод аутентификации.

SMTP.starttls([keyfile[, certfile]])

Переводит соединение SMTP в режим TLS (Transport Layer Security). Все последующие команды SMTP будут зашифрованы. После этого необходимо снова вызвать ehlo().

Если заданы keyfile и certfile, они передаются функции socket модуля ssl().

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

Изменено в версии 2.6.

SMTPHeloError

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

SMTPException

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

Изменено в версии 2.6.

RuntimeError

Поддержка SSL/TLS недоступна для вашей интерпретатора Python.

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 используются для построения оболочки сообщения, используемой агентами передачи. Модуль SMTP не изменяет заголовки сообщений никоим образом.

Если в текущем сеансе не было предыдущей команды EHLO или HELO , этот метод пытается использовать ESMTP EHLO в первую очередь. Если сервер использует ESMTP, размер сообщения и все указанные параметры будут переданы ему (если параметр указан в наборе функций, о которых сообщает сервер). Если EHLO не удаётся, HELO будет использоваться, а опции ESMTP будут подавлены.

Этот метод возвращает нормальный результат, если почта принята хотя бы для одного получателя. В противном случае он вызывает исключение. То есть, если этот метод не вызывает исключение, то кто-то получит вашу почту. Если этот метод не вызывает исключение, он возвращает словарь, содержащий одну запись для каждого получателя, который был отклонен. Каждая запись содержит кортеж из кода ошибки SMTP и сопроводительного сообщения об ошибке, отправленного сервером.

Этот метод может вызвать следующие исключения:

SMTPRecipientsRefused

Все получатели отклонены. Почта никому не доставлена. Атрибут recipients объекта исключения — словарь с информацией об отклоненных получателях (аналогичный возвращаемому, когда по крайней мере один получатель был принят).

SMTPHeloError

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

SMTPSenderRefused

Сервер не принял from_addr.

SMTPDataError

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

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

SMTP.quit()

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

Изменено в версии 2.6: Возвращает значение.

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

2. Пример SMTP

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

import smtplib

def prompt(prompt):
    return raw_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 1:
    try:
        line = raw_input()
    except EOFError:
        break
    if not line:
        break
    msg = msg + line

print "Message length is " + repr(len(msg))

server = smtplib.SMTP('localhost')
server.set_debuglevel(1)
server.sendmail(fromaddr, toaddrs, msg)
server.quit()