Message reference
Message fields, input types and validation limits.
EmailMessageInput is the encoded caller input. parseEmailMessage decodes it into an owned EmailMessage or fails with EmailInvalidMessage. It does not run provider preflight.
| Field | Input and constraint |
|---|---|
from |
One mailbox |
to |
One mailbox or a statically nonempty recipient array |
subject |
Nonempty string, at most 998 characters; no CR, LF or NUL |
body |
Nonempty text, html, or both; each representation is bounded |
cc, bcc, replyTo |
Optional nonempty recipient input |
headers |
Optional nonempty array of custom { name, value } entries |
tags |
Optional nonempty array of distinct-name { name, value } entries |
metadata |
Optional bounded string-to-string record |
attachments |
Optional nonempty array of canonical attachment inputs |
sendAt |
Optional absolute scheduled instant |
The common message permits at most 50 total to/cc/bcc recipients. Provider rules can be stricter, including one-recipient or distinct-recipient requirements. Unknown excess fields are refused rather than silently discarded.
Mailboxes
Use a conservative ASCII address, { address, name? }, or one bounded named mailbox string. Internationalized local parts and arbitrary RFC list syntax are unsupported. formatEmailMailbox formats an already decoded mailbox; it does not establish provider support.
Headers, tags and metadata
Headers cannot replace routing, authentication or MIME control fields. Names are bounded ASCII tokens and values exclude controls. Providers can further restrict names and repeated-name behavior.
Common tags require distinct names; provider tag count, alphabet and label formatting still apply. Common metadata permits bounded strings rather than nested JSON. Private executionMetadata belongs to operation options, not this provider-facing field.
Ownership and richer inputs
Decoding owns nested message values so later caller mutation cannot change the prepared message and options. Read attachments for byte and MIME selection, and scheduling for accepted instant forms and dispatch-time checks. The construction example demonstrates ordinary inputs without caller casts.