Email Frontmatter
Frontmatter holds email metadata. Use it for message-level settings such as subject, preheader, recipients, headers, and delivery defaults. Keep the rendered structure in the Markdown body and keep input validation in the embedded schema block.
Minimal example
---
subject: "Welcome {{ name }}"
preheader: Finish setting up your account
layout: transactional
---
# Welcome, {{ name }}
Frontmatter is optional, but most emails will set at least subject.
Supported keys
| Key | Use it for |
|---|---|
subject | Message subject. Supports interpolation. |
preheader | Inbox preview text. |
layout | Select a named email layout. |
locale | Attach locale metadata to the message. When you use email i18n, the locale folder controls variant selection and this field stays message metadata. |
category | Classify the email for app-level grouping. |
from | Override the default sender for this email. |
replyTo | Set the reply-to address. |
headers | Attach custom message headers. |
metadata | Attach provider-portable metadata. |
delivery | Set provider-level delivery options. |
envelope | Define default recipients and envelope fields. |
text | Override the generated plain-text body. |
Recipient defaults
Use envelope when the email definition itself should carry defaults for to, cc, bcc, or related envelope values.
envelope:
to:
- max@example.com
cc:
- team@example.com
Send-time options can still override these values when you call sendEmail(...).
Message metadata
Use frontmatter for stable metadata that belongs to the email definition itself.
subject: "Invoice {{ invoiceNumber }}"
headers:
X-Customer-Tier: enterprise
metadata:
campaign: billing
flow: invoice-reminder
Use the Markdown body for content and the embedded schema block for validation.
For locale-specific files, ICU formatting, and Nuxt request-locale reuse, see Email i18n.
Delivery settings
Put shared delivery defaults in delivery when the provider mapping should travel with the email definition.
delivery:
labels:
- onboarding
template:
key: welcome-template
Provider pages describe how those shared fields map onto Resend, SendGrid, and Postmark.
Recommended split
- Frontmatter: message metadata and default delivery settings.
- Embedded schema block: input validation and TypeScript inference.
- Embedded CSS block: author-authored styles that should be inlined into the final email HTML.
- Markdown body: email structure and content.
For the validation flow, see Input Schemas.