nuxt-generation-emails 0.1.43 → 0.2.1

package/README.md

@@ -3,7 +3,7 @@
 [![License][license-src]][license-href]
 [![Nuxt][nuxt-src]][nuxt-href]
 
-A Nuxt module for authoring, previewing, and sending transactional email templates — all from inside your Nuxt app.
+A production-ready Nuxt module that turns your app into a complete email workflow: build Vue-powered templates, preview them live, auto-generate typed API endpoints, and optionally deliver through providers like SendGrid via a Nitro hook. From local development to real sends, everything stays in one place.
 
 ## ✨ Features
 
@@ -254,13 +254,23 @@ The module generates `POST` endpoints for every template that render the email H
 
 Create a file at `server/plugins/gen-emails.ts` in your project:
 
+`data` in the hook payload uses this shape:
+
+```ts
+type NuxtGenEmailsSendData<TAdditional extends Record<string, unknown> = Record<string, unknown>> = {
+  to?: string
+  from?: string
+  subject?: string
+} & TAdditional
+```
+
 ```ts
 // server/plugins/gen-emails.ts
 export default defineNitroPlugin((nitro) => {
-  nitro.hooks.hook('nuxt-gen-emails:send', async ({ html, data }: { html: string, data: Record<string, unknown> }) => {
+  nitro.hooks.hook('nuxt-gen-emails:send', async ({ html, data }: { html: string, data: { to?: string, from?: string, subject?: string } & Record<string, unknown> }) => {
     // Your email sending logic here.
     // `html` is the fully rendered email HTML string.
-    // `data` is the original request body (includes template props + `to`, `subject`, `from`, etc.)
+    // `data` is `sendData` from the request body.
     console.log('Sending email to:', data.to)
   })
 })
@@ -289,7 +299,7 @@ import sgMail from '@sendgrid/mail'
 export default defineNitroPlugin((nitro) => {
   sgMail.setApiKey(process.env.SENDGRID_API_KEY!)
 
-  nitro.hooks.hook('nuxt-gen-emails:send', async ({ html, data }: { html: string, data: Record<string, unknown> }) => {
+  nitro.hooks.hook('nuxt-gen-emails:send', async ({ html, data }: { html: string, data: { to?: string, from?: string, subject?: string } & Record<string, unknown> }) => {
     const msg = {
       to: data.to as string,
       from: (data.from as string) || 'noreply@yourdomain.com',
@@ -315,23 +325,33 @@ export default defineNitroPlugin((nitro) => {
 
 When a `POST` request hits an email endpoint (e.g., `/api/emails/v1/order-confirmation`):
 
-1. The request body is read and passed as props to the Vue email template
+1. `templateData` from the request body is passed as props to the Vue email template
 2. `@vue-email/render` renders the template to an HTML string
-3. The Nitro hook `nuxt-gen-emails:send` is called with `{ html, data }` — your plugin handles the actual sending
+3. The Nitro hook `nuxt-gen-emails:send` is called with `{ html, data }` where `data` is `sendData`
 4. The response always returns `{ success: true, html: "..." }` so you can inspect the rendered output
 
+### Sending behavior
+
+- If you configure a Nitro plugin that listens to `nuxt-gen-emails:send`, the module passes your `sendData` to that hook and your plugin can send the email through your provider (SendGrid, SES, etc.).
+- If you do not configure that Nitro hook plugin, the endpoint still renders the email template and returns the rendered HTML in the `POST` response.
+- In both cases, the API response includes the rendered `html` so you can preview/debug the final output.
+
 ### Example API call
 
 ```bash
 curl -X POST http://localhost:3000/api/emails/v1/order-confirmation \
   -H "Content-Type: application/json" \
   -d '{
-    "customerName": "Jane Doe",
-    "orderNumber": "ORD-123456",
-    "orderDate": "February 17, 2026",
-    "totalAmount": 89.99,
-    "to": "jane@example.com",
-    "subject": "Your Order is Confirmed!"
+    "templateData": {
+      "customerName": "Jane Doe",
+      "orderNumber": "ORD-123456",
+      "orderDate": "February 17, 2026",
+      "totalAmount": 89.99
+    },
+    "sendData": {
+      "to": "jane@example.com",
+      "subject": "Your Order is Confirmed!"
+    }
   }'
 ```
 
@@ -349,7 +369,7 @@ Full config key: `nuxtGenerationEmails`
 
 | Hook                      | Payload                                      | Description                                  |
 |---------------------------|-----------------------------------------------|----------------------------------------------|
-| `nuxt-gen-emails:send`    | `{ html: string, data: Record<string, unknown> }` | Called after rendering; wire your send logic here |
+| `nuxt-gen-emails:send`    | `{ html: string, data: { to?: string, from?: string, subject?: string } & Record<string, unknown> }` | Called after rendering; wire your send logic here |
 
 ---
 

package/dist/module.d.mts

@@ -1,11 +1,20 @@
 import * as _nuxt_schema from '@nuxt/schema';
 
 /** Payload passed to the `nuxt-gen-emails:send` Nitro runtime hook. */
-interface NuxtGenEmailsSendPayload {
+type NuxtGenEmailsSendData<TAdditional extends Record<string, unknown> = Record<string, unknown>> = {
+    /** Recipient email address. */
+    to?: string;
+    /** Sender email address. */
+    from?: string;
+    /** Email subject line. */
+    subject?: string;
+} & TAdditional;
+/** Payload passed to the `nuxt-gen-emails:send` Nitro runtime hook. */
+interface NuxtGenEmailsSendPayload<TSendData extends Record<string, unknown> = NuxtGenEmailsSendData> {
     /** The rendered HTML string of the email template. */
     html: string;
-    /** Arbitrary data forwarded from the request body (e.g. `to`, `subject`). */
-    data: Record<string, unknown>;
+    /** Send data forwarded from `sendData` in the request body (e.g. `to`, `subject`). */
+    data: TSendData;
 }
 interface ModuleOptions {
     /** Directory containing email templates; resolved from srcDir when relative. */
@@ -14,4 +23,4 @@ interface ModuleOptions {
 declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
 
 export { _default as default };
-export type { ModuleOptions, NuxtGenEmailsSendPayload };
+export type { ModuleOptions, NuxtGenEmailsSendData, NuxtGenEmailsSendPayload };

package/dist/module.d.ts

@@ -1,11 +1,20 @@
 import * as _nuxt_schema from '@nuxt/schema';
 
 /** Payload passed to the `nuxt-gen-emails:send` Nitro runtime hook. */
-interface NuxtGenEmailsSendPayload {
+type NuxtGenEmailsSendData<TAdditional extends Record<string, unknown> = Record<string, unknown>> = {
+    /** Recipient email address. */
+    to?: string;
+    /** Sender email address. */
+    from?: string;
+    /** Email subject line. */
+    subject?: string;
+} & TAdditional;
+/** Payload passed to the `nuxt-gen-emails:send` Nitro runtime hook. */
+interface NuxtGenEmailsSendPayload<TSendData extends Record<string, unknown> = NuxtGenEmailsSendData> {
     /** The rendered HTML string of the email template. */
     html: string;
-    /** Arbitrary data forwarded from the request body (e.g. `to`, `subject`). */
-    data: Record<string, unknown>;
+    /** Send data forwarded from `sendData` in the request body (e.g. `to`, `subject`). */
+    data: TSendData;
 }
 interface ModuleOptions {
     /** Directory containing email templates; resolved from srcDir when relative. */
@@ -14,4 +23,4 @@ interface ModuleOptions {
 declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
 
 export { _default as default };
-export type { ModuleOptions, NuxtGenEmailsSendPayload };
+export type { ModuleOptions, NuxtGenEmailsSendData, NuxtGenEmailsSendPayload };

package/dist/module.json

@@ -4,7 +4,7 @@
   "compatibility": {
     "nuxt": ">=4.0.0"
   },
-  "version": "0.1.43",
+  "version": "0.2.01",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/module.mjs

@@ -195,6 +195,20 @@ import { useNitroApp } from '#imports'
 import { render } from '@vue-email/render'
 import EmailTemplate from '~/emails/${emailPath}.vue'
 
+type SendData<TAdditional extends Record<string, unknown> = Record<string, unknown>> = {
+  to?: string
+  from?: string
+  subject?: string
+} & TAdditional
+
+type NuxtGenEmailsApiBody<
+  TTemplateData extends Record<string, unknown> = Record<string, unknown>,
+  TSendData extends Record<string, unknown> = SendData,
+> = {
+  templateData: TTemplateData
+  sendData: TSendData
+}
+
 defineRouteMeta({
   openAPI: {
     tags: ['nuxt-generation-emails'],
@@ -206,9 +220,26 @@ defineRouteMeta({
         'application/json': {
           schema: {
             type: 'object',
-            example: ${examplePayload},
-            additionalProperties: true,
-            description: '${emailName} props payload',
+            description: '${emailName} request payload',
+            properties: {
+              templateData: {
+                type: 'object',
+                description: '${emailName} props payload',
+                additionalProperties: true,
+                example: ${examplePayload},
+              },
+              sendData: {
+                type: 'object',
+                description: 'Send provider metadata (to/from/subject and any additional fields)',
+                additionalProperties: true,
+                properties: {
+                  to: { type: 'string', example: 'test@example.com' },
+                  from: { type: 'string', example: 'test@example.com' },
+                  subject: { type: 'string', example: 'Sending with Twilio SendGrid is Fun' },
+                },
+              },
+            },
+            required: ['templateData', 'sendData'],
           },
         },
       },
@@ -250,14 +281,17 @@ defineRouteMeta({
 })
 
 export default defineEventHandler(async (event) => {
-  const body = await readBody<Record<string, unknown>>(event)
+  const body = await readBody<NuxtGenEmailsApiBody>(event)
+
+  const templateData = body?.templateData ?? {}
+  const sendData = body?.sendData ?? {}
 
   try {
-    const html = await render(EmailTemplate, body, { pretty: true })
+    const html = await render(EmailTemplate, templateData, { pretty: true })
 
     const nitro = useNitroApp()
     // @ts-ignore - custom hook
-    await nitro.hooks.callHook('nuxt-gen-emails:send', { html, data: body })
+    await nitro.hooks.callHook('nuxt-gen-emails:send', { html, data: sendData })
 
     return { success: true, message: 'Email rendered successfully', html }
   }
@@ -328,7 +362,21 @@ const module$1 = defineNuxtModule({
       getContents: () => `
 export interface NuxtGenEmailsSendPayload {
   html: string
-  data: Record<string, unknown>
+  data: NuxtGenEmailsSendData
+}
+
+export type NuxtGenEmailsSendData<TAdditional extends Record<string, unknown> = Record<string, unknown>> = {
+  to?: string
+  from?: string
+  subject?: string
+} & TAdditional
+
+export interface NuxtGenEmailsApiBody<
+  TTemplateData extends Record<string, unknown> = Record<string, unknown>,
+  TSendData extends Record<string, unknown> = NuxtGenEmailsSendData,
+> {
+  templateData: TTemplateData
+  sendData: TSendData
 }
 
 declare module 'nitropack' {

package/dist/runtime/components/ApiTester.vue

@@ -35,7 +35,10 @@ async function testApi() {
   try {
     const result = await $fetch(apiEndpoint.value, {
       method: "POST",
-      body: props.dataObject
+      body: {
+        templateData: props.dataObject,
+        sendData: {}
+      }
     });
     responseData.value = result;
     response.value = JSON.stringify(result, null, 2);
@@ -55,9 +58,11 @@ async function sendTestEmail() {
   }
   lastUsedEmail.value = testEmailTo.value.trim();
   const payload = {
-    ...props.dataObject,
-    to: lastUsedEmail.value,
-    subject: `Test email ${Date.now()}`
+    templateData: props.dataObject,
+    sendData: {
+      to: lastUsedEmail.value,
+      subject: `Test email ${Date.now()}`
+    }
   };
   isLoading.value = true;
   sendStatus.value = "sending";

package/dist/types.d.mts

@@ -1,3 +1,3 @@
 export { default } from './module.mjs'
 
-export { type ModuleOptions, type NuxtGenEmailsSendPayload } from './module.mjs'
+export { type ModuleOptions, type NuxtGenEmailsSendData, type NuxtGenEmailsSendPayload } from './module.mjs'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-generation-emails",
-  "version": "0.1.43",
+  "version": "0.2.01",
   "description": "A Nuxt module for authoring, previewing, and sending transactional email templates with Vue Email.",
   "author": "nullcarry@icloud.com",
   "repository": {