# `smtplib` — SMTP protocol client

Вихідний код: 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).

Availability: not WASI.

This module does not work or is not available on WebAssembly. See WebAssembly platforms for more information.

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 host parameter is set to a truthy value, `SMTP.connect()` is called with host and port automatically when the object is created; otherwise, `connect()` must be called manually.

  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` це байти, які мають бути надіслані до віддалений хост.

  default_port

    The default port used for SMTP connections (25).

  Змінено в версії 3.3: Додано підтримку оператора `with`.

  Змінено в версії 3.3: source_address argument was added.

  Added in version 3.5: Тепер підтримується розширення SMTPUTF8 (RFC 6531).

  Змінено в версії 3.9: Якщо параметр timeout дорівнює нулю, це викличе `ValueError`, щоб запобігти створенню неблокуючого сокета.

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

  An `SMTP_SSL` instance behaves exactly the same as instances of `SMTP`. `SMTP_SSL` should be used for situations where SSL is required from the beginning of the connection and using `SMTP.starttls()` is not appropriate.

  If the host parameter is set to a truthy value, `SMTP.connect()` is called with host and port automatically when the object is created; otherwise, `SMTP.connect()` must be called manually.

  The optional arguments local_hostname, timeout and source_address have the same meaning as they do in the `SMTP` class. context, also optional, can contain a `SSLContext` and allows configuring various aspects of the secure connection. Please read Міркування безпеки for best practices.

  default_port

    The default port used for SMTP-over-SSL connections (465).

  Змінено в версії 3.3: додано контекст.

  Змінено в версії 3.3: The source_address argument was added.

  Змінено в версії 3.4: The class now supports hostname check with `ssl.SSLContext.check_hostname` and Server Name Indication (see `ssl.HAS_SNI`).

  Змінено в версії 3.9: Якщо параметр timeout дорівнює нулю, це викличе `ValueError`, щоб запобігти створенню неблокуючого сокета

  Змінено в версії 3.12: The deprecated keyfile and certfile parameters have been removed.

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 зазвичай не підтримує та не вимагає жодної автентифікації, але ваш пробіг може відрізнятися.

  Змінено в версії 3.9: Додано необов’язковий параметр timeout.

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

exception smtplib.SMTPException

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

  Змінено в версії 3.4: SMTPException став підкласом `OSError`

exception smtplib.SMTPServerDisconnected

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

exception smtplib.SMTPResponseException

  Base class for all exceptions that include an SMTP error code. These exceptions are generated in some instances when the SMTP server returns an error code.

  smtp_code

    The error code.

  smtp_error

    The error message.

exception smtplib.SMTPSenderRefused

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

exception smtplib.SMTPRecipientsRefused

  All recipient addresses refused.

  recipients

    A dictionary of exactly the same sort as returned by `SMTP.sendmail()` containing the errors for each recipient.

exception smtplib.SMTPDataError

  Сервер SMTP відмовився прийняти дані повідомлення.

exception smtplib.SMTPConnectError

  Під час встановлення з’єднання з сервером сталася помилка.

exception smtplib.SMTPHeloError

  Сервер відхилив наше повідомлення `HELO`.

exception smtplib.SMTPNotSupportedError

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

  Added in version 3.5.

exception smtplib.SMTPAuthenticationError

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

Дивись також

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

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

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

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

## Об’єкти SMTP

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

SMTP.set_debuglevel(level)

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

  Змінено в версії 3.5: Додано рівень налагодження 2.

SMTP.docmd(cmd, args='')

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

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

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

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

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

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

  If port is not changed from its default value of 0, the value of the `default_port` attribute is used.

  Викликає подію аудиту `smtplib.connect` з аргументами `self`, `host`, `port`.

SMTP.helo(name='')

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

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

SMTP.ehlo(name='')

  Ідентифікуйте себе на сервері ESMTP за допомогою `EHLO`. Аргумент імені хоста за замовчуванням відповідає повному доменному імені локального хосту. Перевірте відповідь для опції 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`

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

  Each of the authentication methods supported by `smtplib` are tried in turn if they are advertised as supported by the server. See `auth()` for a list of supported authentication methods. initial_response_ok is passed through to `auth()`.

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

  Змінено в версії 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` були встановлені на відповідні значення.

  User code does not normally need to call `auth` directly, but can instead call the `login()` method, which will try each of the above mechanisms in turn, in the order listed. `auth` is exposed to facilitate the implementation of authentication methods not (or not yet) supported directly by `smtplib`.

  Added in version 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: The deprecated keyfile and certfile parameters have been removed.

  `SMTPHeloError`

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

  `SMTPNotSupportedError`

    Сервер не підтримує розширення STARTTLS.

  `RuntimeError`

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

  Змінено в версії 3.3: додано контекст.

  Змінено в версії 3.4: The method now supports hostname check with `ssl.SSLContext.check_hostname` and Server Name Indicator (see `HAS_SNI`).

  Змінено в версії 3.5: Помилка, викликана відсутністю підтримки STARTTLS, тепер є підкласом `SMTPNotSupportedError` замість основного `SMTPException`.

SMTP.sendmail(from_addr, to_addrs, msg, mail_options=(), rcpt_options=())

  Send mail. The required arguments are an RFC 822 from-address string, a list of RFC 822 to-address strings (a bare string will be treated as a list with 1 address), and a message string. The caller may pass a list of ESMTP options (such as `"8bitmime"`) to be used in `MAIL FROM` commands as mail_options. ESMTP options (such as `DSN` commands) that should be used with all `RCPT` commands can be passed as rcpt_options. Each option should be passed as a string containing the full text of the option, including any potential key (for instance, `"NOTIFY=SUCCESS,FAILURE"`). (If you need to use different ESMTP options to different recipients you have to use the low-level methods such as `mail()`, `rcpt()` and `data()` to send the message.)

  Примітка

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

    All recipients were refused. Nobody got the mail.

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

  Added in version 3.2.

  Added in version 3.5: Підтримка інтернаціоналізованих адрес (`SMTPUTF8`).

SMTP.quit()

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

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

Additionally, an SMTP instance has the following attributes:

SMTP.helo_resp

  The response to the `HELO` command, see `helo()`.

SMTP.ehlo_resp

  The response to the `EHLO` command, see `ehlo()`.

SMTP.does_esmtp

  A boolean value indicating whether the server supports ESMTP, see `ehlo()`.

SMTP.esmtp_features

  A dictionary of the names of SMTP service extensions supported by the server, see `ehlo()`.

## Приклад 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()

Примітка

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