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 для указанного механизма аутентификации mechanism и обработать ответ на вызов с помощью authobject.

mechanism указывает, какой механизм аутентификации использовать в качестве аргумента для команды AUTH; допустимые значения перечислены в элементе auth от esmtp_features.

authobject должен быть вызываемым объектом, принимающим необязательный единственный аргумент:

data = authobject(challenge=None)

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

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

В этом примере пользователя просят ввести адреса, необходимые в конверте сообщения («Кому» и «От»), и само сообщение, которое должно быть доставлено. Обратите внимание, что заголовки, которые должны быть включены в сообщение, должны быть включены в введённое сообщение; в этом примере не выполняется никакая обработка заголовков 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()