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

---

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

Новое в версии 2.2.

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

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

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

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

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

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

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

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

> **См. также**
>
> **Модуль [`smtplib`](https://python-all.ru/2.7/library/smtplib.html#module-smtplib)**
>
> Клиент протокола SMTP
>
> **Модуль [`nntplib`](https://python-all.ru/2.7/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–2.5 |
| `4.0` | Python 2.5 | Python 2.3–2.5 |

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

- Все модули переименованы в соответствии со стандартами [**PEP 8**](https://python-all.ru/2.7/library/email.html). Например, модуль версии 3 `email.Message` был переименован в [`email.message`](https://python-all.ru/2.7/library/email.message.html#module-email.message) в версии 4.
- Был добавлен новый подпакет [`email.mime`](https://python-all.ru/2.7/library/email.mime.html#module-email.mime), а все модули версии 3 `email.MIME*` были переименованы и размещены в подпакете [`email.mime`](https://python-all.ru/2.7/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/2.7/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/2.7/library/email.html), которые могут изменить типы возвращаемых значений для [`Message.get_param`](https://python-all.ru/2.7/library/email.message.html#email.message.Message.get_param) и связанных функций. При некоторых обстоятельствах значения, которые раньше возвращали кортеж из 3 элементов, теперь возвращают простые строки (в частности, если все сегменты расширенных параметров не закодированы, не ожидается обозначения языка и кодировки, поэтому тип возвращаемого значения теперь – простая строка). Кроме того, %-декодирование раньше применялось как к закодированным, так и к незакодированным сегментам; теперь это декодирование выполняется только для закодированных сегментов.

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

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

Вот различия между [`email`](https://python-all.ru/2.7/library/email.html#module-email) версии 2 и версии 1:

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

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

  Обратите внимание, что здесь обратная совместимость не могла быть полностью сохранена. Однако, если вы уже тестируете возвращаемый тип [`get_payload()`](https://python-all.ru/2.7/library/email.message.html#email.message.Message.get_payload), всё должно быть в порядке. Просто нужно убедиться, что ваш код не вызывает [`set_payload()`](https://python-all.ru/2.7/library/email.message.html#email.message.Message.set_payload) с экземпляром [`Message`](https://python-all.ru/2.7/library/email.message.html#email.message.Message) для контейнера с типом содержимого *message/rfc822*.
- Был добавлен аргумент *strict* конструктора [`Parser`](https://python-all.ru/2.7/library/email.parser.html#email.parser.Parser), а его методы [`parse()`](https://python-all.ru/2.7/library/email.parser.html#email.parser.Parser.parse) и [`parsestr()`](https://python-all.ru/2.7/library/email.parser.html#email.parser.Parser.parsestr) получили аргумент *headersonly*. Флаг *strict* также был добавлен к функциям [`email.message_from_file()`](https://python-all.ru/2.7/library/email.parser.html#email.message_from_file) и [`email.message_from_string()`](https://python-all.ru/2.7/library/email.parser.html#email.message_from_string).
- `Generator.__call__()` устарел; используйте [`Generator.flatten`](https://python-all.ru/2.7/library/email.generator.html#email.generator.Generator.flatten) вместо него. Класс [`Generator`](https://python-all.ru/2.7/library/email.generator.html#email.generator.Generator) также получил метод [`clone()`](https://python-all.ru/2.7/library/email.generator.html#email.generator.Generator.clone).
- Был добавлен класс [`DecodedGenerator`](https://python-all.ru/2.7/library/email.generator.html#email.generator.DecodedGenerator) в модуле [`email.generator`](https://python-all.ru/2.7/library/email.generator.html#module-email.generator).
- Были добавлены промежуточные базовые классы [`MIMENonMultipart`](https://python-all.ru/2.7/library/email.mime.html#email.mime.nonmultipart.MIMENonMultipart) и [`MIMEMultipart`](https://python-all.ru/2.7/library/email.mime.html#email.mime.multipart.MIMEMultipart), и они вставлены в иерархию классов для большинства других производных MIME-классов.
- Аргумент *\_encoder* конструктора [`MIMEText`](https://python-all.ru/2.7/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()`.

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

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

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

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

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

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

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

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

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

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

- Аргументы конструктора класса [`MIMEBase`](https://python-all.ru/2.7/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`](https://python-all.ru/2.7/library/rfc822.html#module-rfc822) в некоторых файловых системах, не различающих регистр.

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

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

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

Сноски

**[1](https://python-all.ru/2.7/library/email.html#id1)**

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