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

---

# 18.1. [`email`](https://python-all.ru/3.2/library/email.html#module-email) – Пакет для работы с email и MIME

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

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

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

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

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

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

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

  - [18.1.2.1. FeedParser API](https://python-all.ru/3.2/library/email.parser.html#feedparser-api)
  - [18.1.2.2. API класса Parser](https://python-all.ru/3.2/library/email.parser.html#parser-class-api)
  - [18.1.2.3. Дополнительные замечания](https://python-all.ru/3.2/library/email.parser.html#additional-notes)
- [18.1.3. `email.generator`: Генерация MIME-документов](https://python-all.ru/3.2/library/email.generator.html)
- [18.1.4. `email.mime`: Создание объектов электронной почты и MIME с нуля](https://python-all.ru/3.2/library/email.mime.html)
- [18.1.5. `email.header`: Интернационализированные заголовки](https://python-all.ru/3.2/library/email.header.html)
- [18.1.6. `email.charset`: Представление наборов символов](https://python-all.ru/3.2/library/email.charset.html)
- [18.1.7. `email.encoders`: Кодировщики](https://python-all.ru/3.2/library/email.encoders.html)
- [18.1.8. `email.errors`: Классы исключений и дефектов](https://python-all.ru/3.2/library/email.errors.html)
- [18.1.9. `email.utils`: Разные утилиты](https://python-all.ru/3.2/library/email.util.html)
- [18.1.10. `email.iterators`: Итераторы](https://python-all.ru/3.2/library/email.iterators.html)
- [18.1.11. `email`: Примеры](https://python-all.ru/3.2/library/email-examples.html)

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

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

Эта таблица описывает историю выпусков пакета 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.2/library/email.html#module-email) версии 5.1 и версии 5.0:

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

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

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

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

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

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

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

- Был введен класс `FeedParser`, а класс `Parser` был реализован на основе `FeedParser`. Поэтому весь разбор теперь нестрогий, и при разборе будут приложены все усилия, чтобы никогда не вызывать исключение. Проблемы, найденные при разборе сообщений, сохраняются в атрибуте сообщения *defect*.
- Все аспекты API, которые вызывали [`DeprecationWarning`](https://python-all.ru/3.2/library/exceptions.html#DeprecationWarning) в версии 2, были удалены. К ним относятся аргумент *\_encoder* конструктора `MIMEText`, метод `Message.add_payload()`, функция `Utils.dump_address_pair()`, а также функции `Utils.decode()` и `Utils.encode()`.
- Новые [`DeprecationWarning`](https://python-all.ru/3.2/library/exceptions.html#DeprecationWarning) были добавлены для: `Generator.__call__()`, `Message.get_type()`, `Message.get_main_type()`, `Message.get_subtype()`, и аргумента *strict* класса `Parser`. Ожидается, что они будут удалены в будущих версиях.
- Удалена поддержка версий Python ниже 2.3.

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

- Были добавлены модули `email.Header` и `email.Charset`.
- Формат pickle для экземпляров `Message` изменился. Поскольку он никогда (и до сих пор не был) формально определён, это не считается нарушением обратной совместимости. Однако если ваше приложение сериализует и десериализует экземпляры `Message`, имейте в виду, что в [`email`](https://python-all.ru/3.2/library/email.html#module-email) версии 2 экземпляры `Message` теперь имеют приватные переменные *\_charset* и *\_default\_type*.
- Несколько методов в классе `Message` устарели, или их сигнатуры изменились. Кроме того, добавлено много новых методов. Подробности см. в документации класса `Message`. Изменения должны быть полностью обратно совместимы.
- The object structure has changed in the face of *message/rfc822* content types. In [`email`](https://python-all.ru/3.2/library/email.html#module-email) version 1, such a type would be represented by a scalar payload, i.e. the container message’s `is_multipart()` returned false, `get_payload()` was not a list object, but a single `Message` instance.

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

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

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

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

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

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

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

Класс `Message` имеет следующие отличия:

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

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

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

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

- Аргументы конструктора класса `MIMEBase` – *\_major* и *\_minor* – были изменены на *\_maintype* и *\_subtype* соответственно.
- Класс/модуль `Image` был переименован в `MIMEImage`. Аргумент *\_minor* был переименован в *\_subtype*.
- Класс/модуль `Text` был переименован в `MIMEText`. Аргумент *\_minor* был переименован в *\_subtype*.
- Класс/модуль `MessageRFC822` был переименован в `MIMEMessage`. Обратите внимание, что более ранняя версия `mimelib` называла этот класс/модуль `RFC822`, но это вызывало конфликт с модулем стандартной библиотеки Python `rfc822` на некоторых файловых системах, нечувствительных к регистру.

  Кроме того, класс `MIMEMessage` теперь представляет любой вид MIME-сообщения с основным типом *message*. Он принимает необязательный аргумент *\_subtype*, который используется для установки MIME-подтипа. По умолчанию *\_subtype* равен *rfc822*.

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

The `MsgReader` class/module has been removed. Its functionality is most closely supported in the `body_line_iterator()` function in the [`email.iterators`](https://python-all.ru/3.2/library/email.iterators.html#module-email.iterators) module.

Сноски

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