defineEmail

Declare a template subject or authored plain-text alternative from script setup.

defineEmail(options) declares metadata for the current email render. Import it only in an email template.

app/emails/welcome.vue

<script setup lang="ts">
import { defineEmail } from '@lupinum/nuxt-email/define-email'

const props = defineProps<{
  firstName: string
}>()

defineEmail({
  subject: () => `Welcome aboard, ${props.firstName}`,
  text: () => `Welcome aboard, ${props.firstName}. Your account is ready.`,
})
</script>

Signature

type EmailMetadataValue = string | (() => string)

type DefineEmailOptions
  = | { subject: EmailMetadataValue, text?: EmailMetadataValue }
    | { subject?: EmailMetadataValue, text: EmailMetadataValue }

function defineEmail(options: DefineEmailOptions): void

At least one of subject or text is required. Extra keys and other value types fail. Functions take no arguments, run synchronously after HTML rendering, and can close over the template's real defineProps() value. An asynchronous function is not supported.

Metadata precedence

Metadata	Result
`subject` declared	`RenderedEmail.subject` contains the resolved string.
`subject` absent	`RenderedEmail.subject` is absent. No subject is derived.
`text` declared	`RenderedEmail.text` contains the authored string.
`text` absent	`RenderedEmail.text` is derived from the final HTML.

Call defineEmail() once per template render. It may run before or after a top-level await in <script setup>. Calling it outside an email render throws DefineEmailOutsideRenderError; calling it twice in one render throws DuplicateEmailDefinitionError.

Entry-point exports

Import from @lupinum/nuxt-email/define-email:

Export	Kind
`defineEmail`	Runtime function
`DefineEmailOutsideRenderError`	Runtime error class
`DuplicateEmailDefinitionError`	Runtime error class
`DefineEmailOptions`	Type only

See subject and authored text for task-oriented examples and error types for recovery guidance.