Public Guardian schemas, exported from @tundraconnect/cloudflare-email/schemas.

import {
  AttachmentSchemaObject,
  EmailAddressSchemaObject,
  SendEmailRequestSchemaObject,
  SendEmailResultSchemaObject,
} from '@tundraconnect/cloudflare-email/schemas';

The wire shape: to, cc and bcc are always arrays here. The schema accepts a single address for any of them and normalizes it first, so only the array form reaches Cloudflare.

Every address field (from, to, cc, bcc, reply_to) is an EmailAddressSchema. A "Name <address>" string is parsed into { address, name } before validation; a plain address and a named object pass through unchanged.

That normalization is a single top-level Guardian.preprocess wrapping the whole object, never a per-field one. A Guardian.preprocess used as a Guardian.object() field's value silently skips its transform, so the raw string would reach the array check unconverted — see CONVENTIONS.md for the full write-up.

Cross-field rules are not enforced here, because an object schema can't express them. CloudflareEmail.send checks both before sending:

• at least one of html / text
• to + cc + bcc within MAX_RECIPIENTS

string | { address: string; name?: string } — exactly what Cloudflare's REST API accepts for each address. It validates the wire shape only, so on its own it rejects a "Name <address>" string; the parsing into the named object is SendEmailRequestSchemaObject's job. The object's key is address, not the Workers binding's email.

Every field is optional and unknown keys pass through. Email Sending is a beta API whose result shape has already gained a field between the REST guide and the API reference (suppressed_recipients). Pinning a closed shape would turn any additive vendor change into a RESPONSE_ERROR on a send that actually succeeded — the wrong trade for a call that has already had a real-world side effect by the time the body is parsed.

content is validated as base64 and passed through verbatim — it is never decoded. The most common mistake is supplying a data: URI or raw bytes, which the validator rejects up front instead of letting Cloudflare fail with an opaque schema error.

Guardian coerces string-coercible primitives rather than rejecting them, so a numeric custom header value ({ 'X-Count': 5 }) validates and becomes '5' — convenient here, since header values must be strings on the wire. A value that cannot be coerced, such as a nested object, is rejected.

← Back to CloudflareEmail