Python `email` crosswalk
This crosswalk compares Mail API with Python’s standard
library email package.
email provides an RFC-oriented message and MIME object model; it deliberately
does not send messages. That makes it a strong fit for constructing or parsing
the Mail API message model, while HTTP submission remains a separate concern.
Python EmailMessage concept |
Mail API field | Mapping observation |
|---|---|---|
Address headers (From, To, Cc, Bcc, Reply-To) |
from, to, cc, bcc, replyTo |
A strong mapping after parsing display names and addresses. |
Subject header |
subject |
Direct correspondence. |
set_content() |
text |
Direct mapping for a plain-text body. |
add_alternative() |
html |
A natural mapping for the HTML member of a multipart alternative message. |
add_attachment() |
attachments |
The attachment bytes, filename, and MIME type can be mapped to the API’s Base64 attachment representation. |
| Other message headers | headers |
Preserve supplemental and repeatable headers, without duplicating structured fields. |
Limits and transport boundary
Section titled “Limits and transport boundary”- The
emailpackage is intentionally not a delivery mechanism. A Python application needs an HTTP client to submit the resulting JSON toPOST /v1/messages; this does not diminish the message-model mapping. - Existing code that passes an
EmailMessagetosmtplibstill has SMTP envelope semantics to account for. In particular, the envelope sender and recipients may differ from visible headers. See the SMTP crosswalk. - Inline MIME parts referenced by content IDs have no Mail API
v1equivalent. They require a documented transformation or rejection policy. - Mail API
202indicates asynchronous acceptance, while200indicates completion within an applied wait. Neither confirms recipient delivery.
