smtplib — SMTP protocol client

Código-fonte: Lib/smtplib.py

The smtplib module defines an SMTP client session object that can be used to send mail to any internet machine with an SMTP or ESMTP listener daemon. For details of SMTP and ESMTP operation, consult RFC 821 (Simple Mail Transfer Protocol) and RFC 1869 (SMTP Service Extensions).

Disponibilidade: not WASI.

Este módulo não funciona ou não está disponível em WebAssembly. Veja Plataformas WebAssembly para mais informações.

class smtplib.SMTP(host='', port=0, local_hostname=None, [timeout, ]source_address=None)

An SMTP instance encapsulates an SMTP connection. It has methods that support a full repertoire of SMTP and ESMTP operations. If the optional host and port parameters are given, the SMTP connect() method is called with those parameters during initialization. If specified, local_hostname is used as the FQDN of the local host in the HELO/EHLO command. Otherwise, the local hostname is found using socket.getfqdn(). If the connect() call returns anything other than a success code, an SMTPConnectError is raised. The optional timeout parameter specifies a timeout in seconds for blocking operations like the connection attempt (if not specified, the global default timeout setting will be used). If the timeout expires, TimeoutError is raised. The optional source_address parameter allows binding to some specific source address in a machine with multiple network interfaces, and/or to some specific source TCP port. It takes a 2-tuple (host, port), for the socket to bind to as its source address before connecting. If omitted (or if host or port are '' and/or 0 respectively) the OS default behavior will be used.

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

Клас SMTP підтримує оператор with. При такому використанні команда SMTP QUIT виконується автоматично, коли завершується оператор with. Наприклад:

>>> from smtplib import SMTP
>>> with SMTP("domain.org") as smtp:
...     smtp.noop()
...
(250, b'Ok')
>>>

Усі команди викличуть подію аудиту smtplib.SMTP.send з аргументами self і data, де data це байти, які мають бути надіслані до віддалений хост.

Alterado na versão 3.3: Suporte para a instrução with foi adicionado.

Alterado na versão 3.3: source_address argument was added.

Adicionado na versão 3.5: A extensão SMTPUTF8 ( RFC 6531 ) é suportada agora.

Alterado na versão 3.9: Якщо параметр timeout дорівнює нулю, це викличе ValueError, щоб запобігти створенню неблокуючого сокета.

class smtplib.SMTP_SSL(host='', port=0, local_hostname=None, *, [timeout, ]context=None, source_address=None)

Екземпляр SMTP_SSL поводиться точно так само, як екземпляри SMTP. SMTP_SSL слід використовувати для ситуацій, коли SSL потрібен від початку з’єднання, а використання starttls() не підходить. Якщо host не вказано, використовується локальний хост. Якщо port дорівнює нулю, використовується стандартний порт SMTP через SSL (465). Необов’язкові аргументи local_hostname, timeout і source_address мають те саме значення, що й у класі SMTP. context, також необов’язковий, може містити SSLContext і дозволяє налаштовувати різні аспекти безпечного з’єднання. Будь ласка, прочитайте Considerações de segurança, щоб дізнатися про найкращі практики.

Alterado na versão 3.3: context foi adicionado.

Alterado na versão 3.3: O argumento source_address foi adicionado.

Alterado na versão 3.4: The class now supports hostname check with ssl.SSLContext.check_hostname and Server Name Indication (see ssl.HAS_SNI).

Alterado na versão 3.9: Якщо параметр timeout дорівнює нулю, це викличе ValueError, щоб запобігти створенню неблокуючого сокета

Alterado na versão 3.12: Os parâmetros depreciados keyfile e certfile foram removidos.

class smtplib.LMTP(host='', port=LMTP_PORT, local_hostname=None, source_address=None[, timeout])

The LMTP protocol, which is very similar to ESMTP, is heavily based on the standard SMTP client. It’s common to use Unix sockets for LMTP, so our connect() method must support that as well as a regular host:port server. The optional arguments local_hostname and source_address have the same meaning as they do in the SMTP class. To specify a Unix socket, you must use an absolute path for host, starting with a ‘/’.

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

Alterado na versão 3.9: O parâmetro opcional timeout foi adicionado.

Також визначено хороший вибір винятків:

exception smtplib.SMTPException

Підклас OSError, який є базовим класом винятків для всіх інших винятків, наданих цим модулем.

Alterado na versão 3.4: SMTPException став підкласом OSError

exception smtplib.SMTPServerDisconnected

Цей виняток виникає, коли сервер несподівано відключається або коли робиться спроба використати екземпляр SMTP перед підключенням до сервера.

exception smtplib.SMTPResponseException

Базовий клас для всіх винятків, які містять код помилки SMTP. Ці винятки виникають у деяких випадках, коли сервер SMTP повертає код помилки. Код помилки зберігається в атрибуті smtp_code помилки, а атрибут smtp_error встановлюється на повідомлення про помилку.

exception smtplib.SMTPSenderRefused

Адресу відправника відхилено. На додаток до атрибутів, встановлених для всіх винятків SMTPResponseException, це встановлює “відправником” рядок, який сервер SMTP відхилив.

exception smtplib.SMTPRecipientsRefused

Усі адреси одержувачів відхилено. Помилки для кожного одержувача доступні через атрибут recipients, який є словником того самого типу, що й повертає SMTP.sendmail().

exception smtplib.SMTPDataError

O servidor SMTP recusou aceitar o dados da mensagem.

exception smtplib.SMTPConnectError

Ocorreu um erro ao estabelecer uma conexão com o servidor.

exception smtplib.SMTPHeloError

O servidor recusou sua mensagem HELO.

exception smtplib.SMTPNotSupportedError

Вибрана команда або параметр не підтримується сервером.

Adicionado na versão 3.5.

exception smtplib.SMTPAuthenticationError

Автентифікація SMTP сталася неправильною. Швидше за все, сервер не прийняв надану комбінацію імені користувача та пароля.

Ver também

RFC 821 - Простий протокол передачі пошти

Визначення протоколу для SMTP. У цьому документі описано модель, операційну процедуру та деталі протоколу SMTP.

RFC 1869 - розширення служби SMTP

Визначення розширень ESMTP для SMTP. Тут описано структуру для розширення SMTP новими командами, підтримкою динамічного виявлення команд, які надає сервер, і визначено кілька додаткових команд.

Objetos SMTP

Екземпляр SMTP має такі методи:

SMTP.set_debuglevel(level)

Установіть вихідний рівень налагодження. Значення 1 або True для рівня призводить до повідомлень про налагодження для з’єднання та для всіх повідомлень, надісланих і отриманих із сервера. Значення 2 для рівня призводить до того, що ці повідомлення мають мітку часу.

Alterado na versão 3.5: Adicionado o nível de depuração 2.

SMTP.docmd(cmd, args='')

Надішліть на сервер команду cmd. Необов’язковий аргумент args просто об’єднується з командою, розділяючись пробілом.

Це повертає 2-кортеж, що складається з числового коду відповіді та фактичного рядка відповіді (багаторядкові відповіді об’єднуються в один довгий рядок).

У нормальній роботі не потрібно явно викликати цей метод. Він використовується для реалізації інших методів і може бути корисним для тестування приватних розширень.

Якщо з’єднання із сервером втрачено під час очікування відповіді, буде виведено SMTPServerDisconnected.

SMTP.connect(host='localhost', port=0)

Підключіться до хосту на заданому порту. За замовчуванням підключення до локального хосту здійснюється через стандартний порт SMTP (25). Якщо ім’я хоста закінчується двокрапкою (':''), після якої йде число, цей суфікс буде видалено, а число інтерпретується як номер порту для використання. Цей метод автоматично викликається конструктором, якщо під час створення екземпляра вказано хост. Повертає 2-кортеж коду відповіді та повідомлення, надіслане сервером у відповіді на підключення.

Levanta um evento de auditoria smtplib.connect com os argumentos self, host, port.

SMTP.helo(name='')

Ідентифікуйте себе на сервері SMTP за допомогою HELO. Аргумент імені хоста за замовчуванням відповідає повному доменному імені локального хосту. Повідомлення, яке повертає сервер, зберігається як атрибут helo_resp об’єкта.

У нормальній роботі не потрібно явно викликати цей метод. За потреби його неявно викликає sendmail().

SMTP.ehlo(name='')

Identify yourself to an ESMTP server using EHLO. The hostname argument defaults to the fully qualified domain name of the local host. Examine the response for ESMTP option and store them for use by has_extn(). Also sets several informational attributes: the message returned by the server is stored as the ehlo_resp attribute, does_esmtp is set to True or False depending on whether the server supports ESMTP, and esmtp_features will be a dictionary containing the names of the SMTP service extensions this server supports, and their parameters (if any).

Якщо ви не бажаєте використовувати 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 або більше та рядок помилки.

Nota

Muitos servidores desabilitam o SMTP VRFY para despistar spammers.

SMTP.login(user, password, *, initial_response_ok=True)

Увійдіть на сервер SMTP, який вимагає автентифікації. Аргументами є ім’я користувача та пароль для автентифікації. Якщо в цьому сеансі не було попередньої команди EHLO або HELO, цей метод спочатку намагається ESMTP EHLO. Цей метод повернеться нормально, якщо автентифікація пройшла успішно, або може викликати такі винятки:

SMTPHeloError

Сервер не відповів належним чином на привітання HELO.

SMTPAuthenticationError

O servidor não aceitou a combinação de usuário/senha.

SMTPNotSupportedError

Команда AUTH не підтримується сервером.

SMTPException

Відповідний метод автентифікації не знайдено.

Кожен із методів автентифікації, які підтримує smtplib, пробується по черзі, якщо вони оголошуються як такі, що підтримуються сервером. Перегляньте auth() список підтримуваних методів автентифікації. initial_response_ok передається до auth().

Необов’язковий аргумент ключового слова initial_response_ok визначає, чи для методів автентифікації, які його підтримують, “початкову відповідь”, як зазначено в RFC 4954, можна надіслати разом із командою AUTH замість того, щоб вимагати виклик/відповідь .

Alterado na versão 3.5: SMTPNotSupportedError може бути викликано, і було додано параметр initial_response_ok.

SMTP.auth(mechanism, authobject, *, initial_response_ok=True)

Видайте команду SMTP AUTH для вказаного механізму автентифікації та обробіть відповідь на виклик через authobject.

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

authobject must be a callable object taking an optional single argument:

data = authobject(challenge=None)

Якщо необов’язковий аргумент ключового слова initial_response_ok має значення true, спочатку буде викликано authobject() без аргументу. Він може повертати RFC 4954 “початкову відповідь” ASCII str, який буде закодовано та надіслано командою AUTH, як показано нижче. Якщо authobject() не підтримує початкову відповідь (наприклад, через те, що він вимагає виклику), він повинен повернути None під час виклику challenge=None. Якщо initial_response_ok має значення false, то authobject() не буде викликано спочатку з None.

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

Клас SMTP надає authobjects для механізмів CRAM-MD5, PLAIN і LOGIN; вони називаються SMTP.auth_cram_md5, SMTP.auth_plain і SMTP.auth_login відповідно. Усі вони вимагають, щоб властивості користувач і пароль примірника SMTP були встановлені на відповідні значення.

Код користувача зазвичай не потребує безпосереднього виклику auth, але натомість може викликати метод login(), який спробує по черзі кожен із наведених вище механізмів у зазначеному порядку. auth доступний для полегшення реалізації методів автентифікації, які не (або ще не підтримуються) безпосередньо smtplib.

Adicionado na versão 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.

Alterado na versão 3.12: Os parâmetros depreciados keyfile e certfile foram removidos.

SMTPHeloError

Сервер не відповів належним чином на привітання HELO.

SMTPNotSupportedError

O servidor não da suporte a extensão STARTTLS.

RuntimeError

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

Alterado na versão 3.3: context foi adicionado.

Alterado na versão 3.4: The method now supports hostname check with SSLContext.check_hostname and Server Name Indicator (see HAS_SNI).

Alterado na versão 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() для надсилання повідомлення.)

Nota

Параметри 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.

Esse método deve levantar as seguintes exceções:

SMTPRecipientsRefused

Усім одержувачам було відмовлено. Ніхто не отримав пошту. Атрибут recipients об’єкта винятку — це словник з інформацією про відхилених одержувачів (наприклад, той, що повертається, коли принаймні один одержувач був прийнятий).

SMTPHeloError

Сервер не відповів належним чином на привітання HELO.

SMTPSenderRefused

O servidor não aceita o from_addr.

SMTPDataError

Сервер відповів неочікуваним кодом помилки (окрім відмови одержувача).

SMTPNotSupportedError

SMTPUTF8 було вказано в mail_options, але не підтримується сервером.

Якщо не зазначено інше, з’єднання буде відкритим навіть після того, як виникне виняток.

Alterado na versão 3.2: msg може бути рядком байтів.

Alterado na versão 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 з повідомлення. Якщо в повідомленні з’являється рівно один набір заголовків Resent-*, звичайні заголовки ігноруються, а замість них використовуються заголовки Resent-*. Якщо повідомлення містить більше одного набору заголовків Resent-*, виникає помилка ValueError, оскільки неможливо однозначно визначити останній набір заголовків Resent- .

send_message serializes msg using BytesGenerator with \r\n as the linesep, and calls sendmail() to transmit the resulting message. Regardless of the values of from_addr and to_addrs, send_message does not transmit any Bcc or Resent-Bcc headers that may appear in msg. If any of the addresses in from_addr and to_addrs contain non-ASCII characters and the server does not advertise SMTPUTF8 support, an SMTPNotSupportedError is raised. Otherwise the Message is serialized with a clone of its policy with the utf8 attribute set to True, and SMTPUTF8 and BODY=8BITMIME are added to mail_options.

Adicionado na versão 3.2.

Adicionado na versão 3.5: Підтримка інтернаціоналізованих адрес (SMTPUTF8).

SMTP.quit()

Припиніть сеанс SMTP і закрийте з’єднання. Повертає результат виконання команди SMTP QUIT.

Методи низького рівня, що відповідають стандартним командам SMTP/ESMTP HELP, RSET, NOOP, MAIL, RCPT і DATA, також є підтримується. Зазвичай їх не потрібно викликати безпосередньо, тому вони тут не задокументовані. Для отримання додаткової інформації зверніться до коду модуля.

Exemplo SMTP

This example prompts the user for addresses needed in the message envelope (‘To’ and ‘From’ addresses), and the message to be delivered. Note that the headers to be included with the message must be included in the message as entered; this example doesn’t do any processing of the RFC 822 headers. In particular, the ‘To’ and ‘From’ addresses must be included in the message headers explicitly:

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

Nota

Загалом, ви захочете використати функції пакета email для створення повідомлення електронної пошти, яке потім можна надіслати через send_message(); див. email: Exemplos.