> **Источник:** https://python-all.ru/3.3/library/email.html
>
> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.

---

# 19.1. [`email`](https://python-all.ru/3.3/library/email.html#module-email) – пакет для обработки электронной почты и MIME

Пакет [`email`](https://python-all.ru/3.3/library/email.html#module-email) – это библиотека для управления сообщениями электронной почты, включая документы на основе MIME и других [**RFC 2822**](https://python-all.ru/3.3/library/email.html). Он специально *не* предназначен для отправки сообщений электронной почты на SMTP ([**RFC 2821**](https://python-all.ru/3.3/library/email.html)), NNTP или другие серверы; это задачи модулей, таких как [`smtplib`](https://python-all.ru/3.3/library/smtplib.html#module-smtplib) и [`nntplib`](https://python-all.ru/3.3/library/nntplib.html#module-nntplib). Пакет [`email`](https://python-all.ru/3.3/library/email.html#module-email) старается быть максимально совместимым с RFC, поддерживая, помимо [**RFC 2822**](https://python-all.ru/3.3/library/email.html), такие связанные с MIME RFC, как [**RFC 2045**](https://python-all.ru/3.3/library/email.html), [**RFC 2046**](https://python-all.ru/3.3/library/email.html), [**RFC 2047**](https://python-all.ru/3.3/library/email.html) и [**RFC 2231**](https://python-all.ru/3.3/library/email.html).

Основная отличительная особенность пакета [`email`](https://python-all.ru/3.3/library/email.html#module-email) заключается в том, что он разделяет разбор и формирование сообщений электронной почты и внутреннее *объектное представление* электронной почты. Приложения, использующие пакет [`email`](https://python-all.ru/3.3/library/email.html#module-email), работают в основном с объектами; можно добавлять подобъекты в сообщения, удалять подобъекты из сообщений, полностью перестраивать содержимое и т.д. Существует отдельный парсер и отдельный генератор, которые выполняют преобразование из плоского текста в объектную модель и обратно в плоский текст. Также есть удобные подклассы для некоторых распространённых типов MIME-объектов и несколько вспомогательных утилит, которые помогают в таких типовых задачах, как извлечение и разбор значений полей сообщений, создание дат, соответствующих RFC, и т.д.

В следующих разделах описывается функциональность пакета [`email`](https://python-all.ru/3.3/library/email.html#module-email). Порядок изложения соответствует прогрессии, которая должна быть типичной для приложений: сообщение электронной почты читается как плоский текст из файла или другого источника, текст парсится для получения объектной структуры сообщения, эта структура изменяется, и наконец, объектное дерево преобразуется обратно в плоский текст.

Вполне возможно создать объектную структуру с нуля – т.е. полностью с самого начала. После этого можно выполнить те же шаги, что описаны выше.

Также включены подробные спецификации всех классов и модулей, которые предоставляет пакет [`email`](https://python-all.ru/3.3/library/email.html#module-email), классы исключений, которые могут возникнуть при использовании пакета [`email`](https://python-all.ru/3.3/library/email.html#module-email), некоторые вспомогательные утилиты и несколько примеров. Для пользователей более старого пакета `mimelib` или предыдущих версий пакета [`email`](https://python-all.ru/3.3/library/email.html#module-email) предоставлен раздел о различиях и переносе.

Содержание документации пакета [`email`](https://python-all.ru/3.3/library/email.html#module-email):

- [19.1.1. `email.message`: Представление сообщения электронной почты](https://python-all.ru/3.3/library/email.message.html)
- [19.1.2. `email.parser`: Разбор сообщений электронной почты](https://python-all.ru/3.3/library/email.parser.html)

  - [19.1.2.1. API FeedParser](https://python-all.ru/3.3/library/email.parser.html#feedparser-api)
  - [19.1.2.2. API класса Parser](https://python-all.ru/3.3/library/email.parser.html#parser-class-api)
  - [19.1.2.3. Дополнительные примечания](https://python-all.ru/3.3/library/email.parser.html#additional-notes)
- [19.1.3. `email.generator`: Генерация MIME-документов](https://python-all.ru/3.3/library/email.generator.html)
- [19.1.4. `email.policy`: Объекты политики](https://python-all.ru/3.3/library/email.policy.html)
- [19.1.5. `email.headerregistry`: Пользовательские объекты заголовков](https://python-all.ru/3.3/library/email.headerregistry.html)
- [19.1.6. `email.mime`: Создание объектов email и MIME с нуля](https://python-all.ru/3.3/library/email.mime.html)
- [19.1.7. `email.header`: Интернационализированные заголовки](https://python-all.ru/3.3/library/email.header.html)
- [19.1.8. `email.charset`: Представление наборов символов](https://python-all.ru/3.3/library/email.charset.html)
- [19.1.9. `email.encoders`: Кодировщики](https://python-all.ru/3.3/library/email.encoders.html)
- [19.1.10. `email.errors`: Классы исключений и дефектов](https://python-all.ru/3.3/library/email.errors.html)
- [19.1.11. `email.utils`: Разные утилиты](https://python-all.ru/3.3/library/email.util.html)
- [19.1.12. `email.iterators`: Итераторы](https://python-all.ru/3.3/library/email.iterators.html)
- [19.1.13. `email`: Примеры](https://python-all.ru/3.3/library/email-examples.html)

> **См. также**
>
> **Модуль [`smtplib`](https://python-all.ru/3.3/library/smtplib.html#module-smtplib)**
>
> Клиент протокола SMTP
>
> **Модуль [`nntplib`](https://python-all.ru/3.3/library/nntplib.html#module-nntplib)**
>
> Клиент протокола NNTP

## 19.1.14. История пакета

Эта таблица описывает историю выпусков пакета email, соответствующую версии Python, с которой был выпущен пакет. Для целей данного документа: когда вы видите примечание об изменении или добавлении версий, оно относится к версии Python, в которой было сделано изменение, *не* к версии пакета email. Эта таблица также описывает совместимость с Python каждой версии пакета.

| Версия email | Распространяется с | Совместима с |
| --- | --- | --- |
| `1.x` | Python 2.2.0 – Python 2.2.1 | *больше не поддерживается* |
| `2.5` | Python 2.2.2+ и Python 2.3 | Python 2.1 – 2.5 |
| `3.0` | Python 2.4 | Python 2.3 to 2.5 |
| `4.0` | Python 2.5 | Python 2.3 to 2.5 |
| `5.0` | Python 3.0 и Python 3.1 | Python 3.0 – 3.2 |
| `5.1` | Python 3.2 | Python 3.0 – 3.2 |

Вот основные различия между пакетом [`email`](https://python-all.ru/3.3/library/email.html#module-email) версии 5.1 и версии 5.0:

- Снова стало возможным анализировать сообщения, содержащие не-ASCII байты, и воспроизводить такие сообщения, если данные, содержащие не-ASCII байты, не изменялись.
- Новые функции [`message_from_bytes()`](https://python-all.ru/3.3/library/email.parser.html#email.message_from_bytes) и [`message_from_binary_file()`](https://python-all.ru/3.3/library/email.parser.html#email.message_from_binary_file), а также новые классы [`BytesFeedParser`](https://python-all.ru/3.3/library/email.parser.html#email.parser.BytesFeedParser) и [`BytesParser`](https://python-all.ru/3.3/library/email.parser.html#email.parser.BytesParser) позволяют разбирать двоичные данные сообщений в объекты модели.
- При вводе байтов в модель [`get_payload()`](https://python-all.ru/3.3/library/email.message.html#email.message.Message.get_payload) по умолчанию будет декодировать тело сообщения, имеющее *Content-Transfer-Encoding* `8bit`, используя кодировку, указанную в MIME-заголовках, и возвращать результирующую строку.
- При вводе байтов в модель [`Generator`](https://python-all.ru/3.3/library/email.generator.html#email.generator.Generator) будет преобразовывать тела сообщений, имеющие *Content-Transfer-Encoding* 8bit, в 7bit Content-Transfer-Encoding.
- Новый класс [`BytesGenerator`](https://python-all.ru/3.3/library/email.generator.html#email.generator.BytesGenerator) выдает байты на выходе, сохраняя любые неизмененные не-ASCII данные, которые присутствовали во входных данных, использованных для построения модели, включая тела сообщений с *Content-Transfer-Encoding* 8bit.

Вот основные различия между пакетом [`email`](https://python-all.ru/3.3/library/email.html#module-email) версии 5.0 и версии 4:

- Все операции выполняются над строками Unicode. Текстовые входные данные должны быть строками, текстовые выходные данные – строками. Выходные данные ограничены набором символов ASCII, поэтому их можно кодировать в ASCII для передачи. Входные данные также ограничены ASCII; это признанное ограничение email 5.0, означающее, что его можно использовать только для разбора 7-битных чистых сообщений электронной почты.

Вот основные различия между пакетом [`email`](https://python-all.ru/3.3/library/email.html#module-email) версии 4 и версии 3:

- Все модули были переименованы в соответствии со стандартами [**PEP 8**](https://python-all.ru/3.3/library/email.html). Например, модуль версии 3 `email.Message` был переименован в [`email.message`](https://python-all.ru/3.3/library/email.message.html#module-email.message) в версии 4.
- Был добавлен новый подпакет [`email.mime`](https://python-all.ru/3.3/library/email.mime.html#module-email.mime), и все модули `email.MIME*` версии 3 были переименованы и перемещены в подпакет [`email.mime`](https://python-all.ru/3.3/library/email.mime.html#module-email.mime). Например, модуль версии 3 `email.MIMEText` был переименован в `email.mime.text`.

  *Обратите внимание, что имена версии 3 будут продолжать работать до Python 2.6*.
- Был добавлен модуль `email.mime.application`, который содержит класс [`MIMEApplication`](https://python-all.ru/3.3/library/email.mime.html#email.mime.application.MIMEApplication).
- Методы, которые были помечены как устаревшие в версии 3, были удалены. К ним относятся `Generator.__call__()`, `Message.get_type()`, `Message.get_main_type()`, `Message.get_subtype()`.
- Добавлены исправления для поддержки [**RFC 2231**](https://python-all.ru/3.3/library/email.html), которые могут изменить некоторые типы возвращаемых значений для [`Message.get_param`](https://python-all.ru/3.3/library/email.message.html#email.message.Message.get_param) и связанных с ним функций. При некоторых обстоятельствах значения, которые ранее возвращали кортеж из трёх элементов, теперь возвращают простую строку (в частности, если все расширенные сегменты параметров не были закодированы, ожидаемые обозначение языка и кодировка отсутствуют, поэтому тип возврата – простая строка). Кроме того, %-декодирование ранее применялось как к закодированным, так и к незакодированным сегментам; теперь оно выполняется только для закодированных сегментов.

Ниже приведены основные различия между [`email`](https://python-all.ru/3.3/library/email.html#module-email) версии 3 и версии 2:

- The [`FeedParser`](https://python-all.ru/3.3/library/email.parser.html#email.parser.FeedParser) class was introduced, and the [`Parser`](https://python-all.ru/3.3/library/email.parser.html#email.parser.Parser) class was implemented in terms of the [`FeedParser`](https://python-all.ru/3.3/library/email.parser.html#email.parser.FeedParser). All parsing therefore is non-strict, and parsing will make a best effort never to raise an exception. Problems found while parsing messages are stored in the message’s *defect* attribute.
- Все аспекты API, которые в версии 2 вызывали [`DeprecationWarning`](https://python-all.ru/3.3/library/exceptions.html#DeprecationWarning), были удалены. К ним относятся аргумент *\_encoder* конструктора [`MIMEText`](https://python-all.ru/3.3/library/email.mime.html#email.mime.text.MIMEText), метод `Message.add_payload()`, функция `Utils.dump_address_pair()`, а также функции `Utils.decode()` и `Utils.encode()`.
- Новые [`DeprecationWarning`](https://python-all.ru/3.3/library/exceptions.html#DeprecationWarning) добавлены для: `Generator.__call__()`, `Message.get_type()`, `Message.get_main_type()`, `Message.get_subtype()`, а также аргумента *strict* класса [`Parser`](https://python-all.ru/3.3/library/email.parser.html#email.parser.Parser). Предполагается, что они будут удалены в будущих версиях.
- Удалена поддержка версий Python ниже 2.3.

Ниже приведены различия между [`email`](https://python-all.ru/3.3/library/email.html#module-email) версии 2 и версии 1:

- Были добавлены модули `email.Header` и `email.Charset`.
- Формат pickle для экземпляров [`Message`](https://python-all.ru/3.3/library/email.message.html#email.message.Message) изменился. Поскольку он никогда (и до сих пор) не был формально определён, это не считается нарушением обратной совместимости. Однако если ваше приложение сериализует и десериализует экземпляры [`Message`](https://python-all.ru/3.3/library/email.message.html#email.message.Message), имейте в виду, что в [`email`](https://python-all.ru/3.3/library/email.html#module-email) версии 2 экземпляры [`Message`](https://python-all.ru/3.3/library/email.message.html#email.message.Message) теперь содержат приватные переменные *\_charset* и *\_default\_type*.
- Несколько методов класса [`Message`](https://python-all.ru/3.3/library/email.message.html#email.message.Message) объявлены устаревшими, либо изменились их сигнатуры. Также было добавлено много новых методов. Подробности см. в документации класса [`Message`](https://python-all.ru/3.3/library/email.message.html#email.message.Message). Изменения должны быть полностью обратно совместимы.
- Структура объектов изменилась для типов содержимого *message/rfc822*. В [`email`](https://python-all.ru/3.3/library/email.html#module-email) версии 1 такой тип представлялся скалярным содержимым, т.е. метод [`is_multipart()`](https://python-all.ru/3.3/library/email.message.html#email.message.Message.is_multipart) контейнерного сообщения возвращал false, а [`get_payload()`](https://python-all.ru/3.3/library/email.message.html#email.message.Message.get_payload) был не списком, а единственным экземпляром [`Message`](https://python-all.ru/3.3/library/email.message.html#email.message.Message).

  Эта структура была несовместима с остальной частью пакета, поэтому представление объектов для типов содержимого *message/rfc822* было изменено. В [`email`](https://python-all.ru/3.3/library/email.html#module-email) версии 2 контейнер *возвращает* `True` из [`is_multipart()`](https://python-all.ru/3.3/library/email.message.html#email.message.Message.is_multipart), а [`get_payload()`](https://python-all.ru/3.3/library/email.message.html#email.message.Message.get_payload) возвращает список, содержащий единственный элемент [`Message`](https://python-all.ru/3.3/library/email.message.html#email.message.Message).

  Обратите внимание, что это одно из мест, где обратную совместимость не удалось сохранить полностью. Однако если вы уже проверяете тип возвращаемого значения [`get_payload()`](https://python-all.ru/3.3/library/email.message.html#email.message.Message.get_payload), проблем быть не должно. Просто убедитесь, что ваш код не вызывает [`set_payload()`](https://python-all.ru/3.3/library/email.message.html#email.message.Message.set_payload) с экземпляром [`Message`](https://python-all.ru/3.3/library/email.message.html#email.message.Message) у контейнера с типом содержимого *message/rfc822*.
- В конструктор [`Parser`](https://python-all.ru/3.3/library/email.parser.html#email.parser.Parser) был добавлен аргумент *strict*, а его методы [`parse()`](https://python-all.ru/3.3/library/email.parser.html#email.parser.Parser.parse) и [`parsestr()`](https://python-all.ru/3.3/library/email.parser.html#email.parser.Parser.parsestr) получили аргумент *headersonly*. Флаг *strict* также был добавлен в функции [`email.message_from_file()`](https://python-all.ru/3.3/library/email.parser.html#email.message_from_file) и [`email.message_from_string()`](https://python-all.ru/3.3/library/email.parser.html#email.message_from_string).
- `Generator.__call__()` объявлен устаревшим; используйте вместо него [`Generator.flatten`](https://python-all.ru/3.3/library/email.generator.html#email.generator.Generator.flatten). Класс [`Generator`](https://python-all.ru/3.3/library/email.generator.html#email.generator.Generator) также получил метод [`clone()`](https://python-all.ru/3.3/library/email.generator.html#email.generator.Generator.clone).
- Был добавлен класс [`DecodedGenerator`](https://python-all.ru/3.3/library/email.generator.html#email.generator.DecodedGenerator) в модуле [`email.generator`](https://python-all.ru/3.3/library/email.generator.html#module-email.generator).
- Были добавлены промежуточные базовые классы [`MIMENonMultipart`](https://python-all.ru/3.3/library/email.mime.html#email.mime.nonmultipart.MIMENonMultipart) и [`MIMEMultipart`](https://python-all.ru/3.3/library/email.mime.html#email.mime.multipart.MIMEMultipart), которые встроены в иерархию классов для большинства других производных классов, связанных с MIME.
- Аргумент *\_encoder* конструктора [`MIMEText`](https://python-all.ru/3.3/library/email.mime.html#email.mime.text.MIMEText) объявлен устаревшим. Кодирование теперь происходит неявно на основе аргумента *\_charset*.
- Следующие функции в модуле `email.Utils` объявлены устаревшими: `dump_address_pairs()`, `decode()` и `encode()`. В модуль добавлены следующие функции: `make_msgid()`, `decode_rfc2231()`, `encode_rfc2231()` и `decode_params()`.
- Была добавлена непубличная функция `email.Iterators._structure()`.

## 19.1.15. Отличия от `mimelib`

Пакет [`email`](https://python-all.ru/3.3/library/email.html#module-email) изначально был прототипом отдельной библиотеки под названием [mimelib](https://python-all.ru/3.3/library/email.html). Были внесены изменения, чтобы названия методов стали более согласованными, а некоторые методы или модули были добавлены или удалены. Семантика некоторых методов также изменилась. По большей части любая функциональность, доступная в `mimelib`, по-прежнему доступна в пакете [`email`](https://python-all.ru/3.3/library/email.html#module-email), хотя часто иным способом. Обратная совместимость между пакетом `mimelib` и пакетом [`email`](https://python-all.ru/3.3/library/email.html#module-email) не была приоритетом.

Ниже приводится краткое описание различий между пакетами `mimelib` и [`email`](https://python-all.ru/3.3/library/email.html#module-email), а также советы по переносу ваших приложений.

Разумеется, самое заметное различие между двумя пакетами заключается в том, что имя пакета изменено на [`email`](https://python-all.ru/3.3/library/email.html#module-email). Кроме того, на верхнем уровне пакета имеются следующие отличия:

- `messageFromString()` переименован в [`message_from_string()`](https://python-all.ru/3.3/library/email.parser.html#email.message_from_string).
- `messageFromFile()` переименован в [`message_from_file()`](https://python-all.ru/3.3/library/email.parser.html#email.message_from_file).

Класс [`Message`](https://python-all.ru/3.3/library/email.message.html#email.message.Message) имеет следующие отличия:

- Метод `asString()` был переименован в [`as_string()`](https://python-all.ru/3.3/library/email.message.html#email.message.Message.as_string).
- Метод `ismultipart()` был переименован в [`is_multipart()`](https://python-all.ru/3.3/library/email.message.html#email.message.Message.is_multipart).
- Метод [`get_payload()`](https://python-all.ru/3.3/library/email.message.html#email.message.Message.get_payload) получил необязательный аргумент *decode*.
- Метод `getall()` был переименован в [`get_all()`](https://python-all.ru/3.3/library/email.message.html#email.message.Message.get_all).
- Метод `addheader()` был переименован в [`add_header()`](https://python-all.ru/3.3/library/email.message.html#email.message.Message.add_header).
- Метод `gettype()` был переименован в `get_type()`.
- Метод `getmaintype()` был переименован в `get_main_type()`.
- Метод `getsubtype()` был переименован в `get_subtype()`.
- Метод `getparams()` был переименован в [`get_params()`](https://python-all.ru/3.3/library/email.message.html#email.message.Message.get_params). Кроме того, если `getparams()` возвращал список строк, то [`get_params()`](https://python-all.ru/3.3/library/email.message.html#email.message.Message.get_params) возвращает список кортежей из двух элементов – фактически пары ключ/значение параметров, разделённых знаком `'='`.
- Метод `getparam()` был переименован в [`get_param()`](https://python-all.ru/3.3/library/email.message.html#email.message.Message.get_param).
- Метод `getcharsets()` был переименован в [`get_charsets()`](https://python-all.ru/3.3/library/email.message.html#email.message.Message.get_charsets).
- Метод `getfilename()` был переименован в [`get_filename()`](https://python-all.ru/3.3/library/email.message.html#email.message.Message.get_filename).
- Метод `getboundary()` был переименован в [`get_boundary()`](https://python-all.ru/3.3/library/email.message.html#email.message.Message.get_boundary).
- Метод `setboundary()` был переименован в [`set_boundary()`](https://python-all.ru/3.3/library/email.message.html#email.message.Message.set_boundary).
- Метод `getdecodedpayload()` был удалён. Чтобы получить похожую функциональность, передайте значение 1 флагу *decode* метода [`get_payload()`](https://python-all.ru/3.3/library/email.message.html#email.message.Message.get_payload).
- Метод `getpayloadastext()` был удалён. Похожая функциональность поддерживается классом [`DecodedGenerator`](https://python-all.ru/3.3/library/email.generator.html#email.generator.DecodedGenerator) в модуле [`email.generator`](https://python-all.ru/3.3/library/email.generator.html#module-email.generator).
- Метод `getbodyastext()` был удалён. Похожую функциональность можно получить, создав итератор с помощью [`typed_subpart_iterator()`](https://python-all.ru/3.3/library/email.iterators.html#email.iterators.typed_subpart_iterator) в модуле [`email.iterators`](https://python-all.ru/3.3/library/email.iterators.html#module-email.iterators).

Класс [`Parser`](https://python-all.ru/3.3/library/email.parser.html#email.parser.Parser) не имеет различий в своём публичном интерфейсе. Однако он обладает дополнительной логикой для распознавания сообщений типа *message/delivery-status*, которые он представляет в виде экземпляра [`Message`](https://python-all.ru/3.3/library/email.message.html#email.message.Message), содержащего отдельные [`Message`](https://python-all.ru/3.3/library/email.message.html#email.message.Message) подчасти для каждого заголовочного блока в уведомлении о состоянии доставки [\[1\]](https://python-all.ru/3.3/library/email.html#id2).

Класс [`Generator`](https://python-all.ru/3.3/library/email.generator.html#email.generator.Generator) не имеет различий в своём публичном интерфейсе. Однако в модуле [`email.generator`](https://python-all.ru/3.3/library/email.generator.html#module-email.generator) появился новый класс [`DecodedGenerator`](https://python-all.ru/3.3/library/email.generator.html#email.generator.DecodedGenerator), который предоставляет большую часть функциональности, ранее доступной в методе `Message.getpayloadastext()`.

Были изменены следующие модули и классы:

- Аргументы конструктора класса [`MIMEBase`](https://python-all.ru/3.3/library/email.mime.html#email.mime.base.MIMEBase) *\_major* и *\_minor* изменились на *\_maintype* и *\_subtype* соответственно.
- Класс/модуль `Image` был переименован в `MIMEImage`. Аргумент *\_minor* был переименован в *\_subtype*.
- Класс/модуль `Text` был переименован в `MIMEText`. Аргумент *\_minor* был переименован в *\_subtype*.
- Класс/модуль `MessageRFC822` был переименован в `MIMEMessage`. Обратите внимание, что более ранняя версия `mimelib` называла этот класс/модуль `RFC822`, но это вызывало конфликт с модулем стандартной библиотеки Python `rfc822` на некоторых файловых системах, нечувствительных к регистру.

  Кроме того, класс [`MIMEMessage`](https://python-all.ru/3.3/library/email.mime.html#email.mime.message.MIMEMessage) теперь представляет любой тип MIME-сообщения с основным типом *message*. Он принимает необязательный аргумент *\_subtype*, который используется для установки MIME-подтипа. По умолчанию *\_subtype* равен *rfc822*.

`mimelib` предоставлял некоторые вспомогательные функции в своих модулях `address` и `date`. Все эти функции были перемещены в модуль [`email.utils`](https://python-all.ru/3.3/library/email.util.html#module-email.utils).

Класс/модуль `MsgReader` был удалён. Его функциональность наиболее близко поддерживается функцией [`body_line_iterator()`](https://python-all.ru/3.3/library/email.iterators.html#email.iterators.body_line_iterator) в модуле [`email.iterators`](https://python-all.ru/3.3/library/email.iterators.html#module-email.iterators).

Сноски

| [\[1\]](https://python-all.ru/3.3/library/email.html#id1) | Уведомления о статусе доставки (DSN) определены в [**RFC 1894**](https://python-all.ru/3.3/library/email.html). |
| --- | --- |