@razmatinyan/nuxt-email 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Razmik Matinyan <razmatinyan28@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,272 @@
+# nuxt-email
+
+Transactional email for Nuxt 4: a provider-agnostic API, Vue-powered templates, and type-safe server composables.
+
+- 📨 **One API, many providers** — Resend, SendGrid, Postmark, SMTP, and a console provider for local dev
+- 🧩 **Vue email templates** — author emails as `.vue` files, rendered on the server and CSS-inlined
+- 🔒 **Server-only & type-safe** — credentials stay private; `useEmail()` is auto-imported in your server routes
+- 📎 **Attachments, CC/BCC, reply-to, headers, tags, and scheduling**
+- 🔁 **Automatic retries** on transient failures, plus batch sending with a concurrency limit
+- 🛠 **Nuxt DevTools tab** — browse templates, live-preview them, send a test, and watch a send log
+
+## Quick Setup
+
+```bash
+npm install @razmatinyan/nuxt-email
+```
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ['@razmatinyan/nuxt-email'],
+  email: {
+    provider: 'console', // logs to the terminal during development
+    from: 'App <noreply@myapp.com>',
+  },
+})
+```
+
+Send your first email from any server route:
+
+```ts
+// server/api/register.post.ts
+export default defineEventHandler(async (event) => {
+  const { sendEmail } = useEmail() // auto-imported on the server
+
+  const result = await sendEmail({
+    to: 'user@example.com',
+    subject: 'Welcome!',
+    html: '<h1>Welcome!</h1><p>Thanks for signing up.</p>',
+  })
+
+  if (!result.success) {
+    console.error('Email failed:', result.error)
+  }
+
+  return result
+})
+```
+
+## Providers
+
+All providers share the same API — switch by changing `provider` in `nuxt.config.ts`, no code changes.
+
+| Provider   | Transport          | Extra dependency        |
+|------------|--------------------|-------------------------|
+| `console`  | Logs to stdout     | —                       |
+| `resend`   | REST (`$fetch`)    | —                       |
+| `sendgrid` | REST (`$fetch`)    | —                       |
+| `postmark` | REST (`$fetch`)    | —                       |
+| `smtp`     | `nodemailer`       | `npm install nodemailer` (optional peer dependency) |
+
+The REST providers use Nitro's built-in `$fetch`, so no SDKs are added to your dependency tree. SMTP needs `nodemailer`, which is an optional peer dependency you install only if you use it.
+
+```ts
+export default defineNuxtConfig({
+  email: {
+    provider: 'resend',
+    from: 'Acme <hello@acme.com>',
+    apiKey: process.env.NUXT_EMAIL_API_KEY,
+  },
+})
+```
+
+```ini
+# .env
+NUXT_EMAIL_API_KEY=re_your_key_here
+```
+
+For SMTP:
+
+```ts
+email: {
+  provider: 'smtp',
+  from: 'Acme <hello@acme.com>',
+  smtp: {
+    host: 'smtp.example.com',
+    port: 587,
+    user: process.env.SMTP_USER,
+    pass: process.env.SMTP_PASS,
+    secure: false, // true for port 465
+  },
+}
+```
+
+### Multiple providers
+
+Give each provider its own credentials with the optional `providers` map. Each entry overrides the top-level `apiKey` / `smtp` / `from` for that provider, so you can switch providers per call without reconfiguring:
+
+```ts
+email: {
+  provider: 'resend', // the default
+  from: 'Acme <hello@acme.com>',
+  providers: {
+    resend: { apiKey: process.env.RESEND_API_KEY },
+    postmark: { apiKey: process.env.POSTMARK_API_KEY, from: 'Acme <tx@acme.com>' },
+    smtp: { smtp: { host: 'smtp.example.com', user: process.env.SMTP_USER, pass: process.env.SMTP_PASS } },
+  },
+}
+```
+
+```ts
+// uses the matching credentials from `providers.postmark`
+await sendEmail({ to, subject, template, props }, { provider: 'postmark' })
+```
+
+If you only use one provider, the top-level `apiKey`/`smtp` is all you need — `providers` is optional.
+
+## Vue email templates
+
+Drop a `.vue` file into `server/emails/` (configurable via `templateDir`) and reference it by filename:
+
+```vue
+<!-- server/emails/welcome.vue -->
+<script setup lang="ts">
+defineProps<{ name: string, verifyUrl: string }>()
+</script>
+
+<template>
+  <div style="font-family: sans-serif; padding: 24px;">
+    <h1>Welcome, {{ name }}!</h1>
+    <p>Please confirm your email address.</p>
+    <a :href="verifyUrl">Verify</a>
+  </div>
+</template>
+```
+
+```ts
+await sendEmail({
+  to: user.email,
+  subject: 'Welcome to Acme!',
+  template: 'welcome',
+  props: { name: user.name, verifyUrl: 'https://acme.com/verify?token=abc' },
+})
+```
+
+The template is rendered to HTML on the server, CSS is inlined for email-client compatibility, and a plain-text fallback is generated automatically. Style with inline `style` attributes or `<style>` blocks inside the `<template>` — SFC `<style>` blocks are stripped during compilation and won't be inlined.
+
+### Preview data
+
+Export `previewProps` from a plain `<script>` block to give the dev preview and DevTools sample data:
+
+```vue
+<script lang="ts">
+export const previewProps = {
+  name: 'Jane Doe',
+  verifyUrl: 'https://example.com/verify',
+}
+</script>
+```
+
+## Sending options
+
+```ts
+await sendEmail({
+  to: ['a@example.com', 'b@example.com'],
+  cc: 'manager@example.com',
+  bcc: 'audit@example.com',
+  replyTo: 'support@example.com',
+  from: 'Billing <billing@acme.com>', // overrides the default `from`
+  subject: 'Your invoice',
+  template: 'invoice',
+  props: { total: '$99.00' },
+  headers: { 'X-Entity-Ref-Id': 'inv_123' },
+  tags: { category: 'billing' },          // resend, sendgrid, postmark
+  scheduledAt: new Date(Date.now() + 3600_000), // resend, sendgrid
+  attachments: [
+    {
+      filename: 'invoice.pdf',
+      content: pdfBuffer,           // string or Buffer
+      contentType: 'application/pdf',
+    },
+  ],
+})
+```
+
+Every send returns a structured result (never throws from a provider):
+
+```ts
+interface EmailResponse {
+  success: boolean
+  messageId?: string
+  error?: string
+  provider: string
+  duration: number // ms
+}
+```
+
+`tags` and `scheduledAt` are applied by the providers that support them and ignored by the rest.
+
+### Batch sending
+
+```ts
+const { sendBatch } = useEmail()
+
+const results = await sendBatch(
+  users.map(u => ({ to: u.email, subject: 'Newsletter', template: 'newsletter', props: { name: u.name } })),
+  { concurrency: 10 }, // default 5
+)
+
+const failed = results.filter(r => !r.success)
+```
+
+### Per-call provider override
+
+Override the configured provider for a single send (handy for testing). The override reuses the same credentials, so only providers whose credentials are configured will succeed — `console` always works:
+
+```ts
+await sendEmail({ to: 'me@example.com', subject: 'Test', template: 'welcome', props }, { provider: 'console' })
+```
+
+## Reliability & validation
+
+- **Retries** — failures that look transient (HTTP 429/5xx, timeouts, connection resets) are retried up to `retries` times with a growing delay. Client errors (4xx) are not retried.
+- **Validation** — recipient addresses (`to`/`cc`/`bcc`/`replyTo`) and `from` are validated, `"Name <email>"` form is accepted, and newlines are rejected to prevent header injection. Attachments must have a `filename` and `content`.
+- **Prerendering** — sends are skipped during `nuxi generate` / prerendering and return a no-op success.
+
+## DevTools
+
+In dev, an **Email** tab appears in Nuxt DevTools. From it you can browse discovered templates, live-preview them (using their `previewProps`), pick a provider and send a test email, and watch an in-session send log. The panel follows the DevTools light/dark theme.
+
+These dev-only routes back the tab (and are handy on their own):
+
+| Route                          | Purpose                                  |
+|--------------------------------|------------------------------------------|
+| `GET /_email/preview/:template`| Render a template to HTML                |
+| `GET /_email/templates`        | List templates and their preview props   |
+| `POST /_email/send-test/:template` | Send a test email                    |
+| `GET /_email/log`              | Recent sends from this dev session       |
+| `GET /_email/config`           | Configured provider and available list   |
+
+Set `preview: false` to disable them.
+
+## Configuration
+
+| Option        | Type      | Default           | Description                          |
+|---------------|-----------|-------------------|--------------------------------------|
+| `provider`    | string    | `'console'`       | `console` · `resend` · `sendgrid` · `postmark` · `smtp` |
+| `from`        | string    | —                 | Default sender (`"Name <email>"` or `email`) |
+| `apiKey`      | string    | —                 | API key for the REST providers       |
+| `smtp`        | object    | —                 | `{ host, port?, user?, pass?, secure? }` |
+| `providers`   | object    | —                 | Per-provider credentials, e.g. `{ resend: { apiKey }, smtp: { smtp: {...} } }` |
+| `templateDir` | string    | `'server/emails'` | Directory scanned for `.vue` templates |
+| `preview`     | boolean   | `true`            | Enable dev preview routes + DevTools tab |
+| `retries`     | number    | `2`               | Retry attempts on transient failures |
+| `retryDelay`  | number    | `1000`            | Base delay between retries (ms)      |
+
+Keep secrets in `.env` and read them via `process.env` in `nuxt.config.ts`, as shown above. Provider credentials live in private runtime config and are never exposed to the client.
+
+## Development
+
+```bash
+npm install              # install dependencies
+npm run dev:prepare      # build module stubs (run once after cloning)
+npm run dev              # playground at http://localhost:3000
+npm run test:unit        # fast unit tests
+npm run test:integration # boots Nuxt, slower
+npx tsc --noEmit         # type-check
+```
+
+## License
+
+[MIT](./LICENSE)

package/dist/module.d.mts

@@ -0,0 +1,7 @@
+import * as _nuxt_schema from '@nuxt/schema';
+import { EmailModuleOptions } from '../dist/runtime/types/index.js';
+export { EmailAttachment, EmailModuleOptions, EmailPayload, EmailProvider, EmailResponse, NormalizedPayload } from '../dist/runtime/types/index.js';
+
+declare const _default: _nuxt_schema.NuxtModule<EmailModuleOptions, EmailModuleOptions, false>;
+
+export { _default as default };

package/dist/module.json

@@ -0,0 +1,12 @@
+{
+  "name": "nuxt-email",
+  "configKey": "email",
+  "compatibility": {
+    "nuxt": ">=4.0.0"
+  },
+  "version": "0.1.0",
+  "builder": {
+    "@nuxt/module-builder": "1.0.2",
+    "unbuild": "3.6.1"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,190 @@
+import { existsSync, readdirSync } from 'node:fs';
+import { resolve, join, relative } from 'node:path';
+import { defineNuxtModule, useLogger, createResolver, addTemplate, addServerImports, addServerHandler, addTypeTemplate } from '@nuxt/kit';
+import { addCustomTab } from '@nuxt/devtools-kit';
+import vuePlugin from 'unplugin-vue/rollup';
+
+const MODULE_NAME = "nuxt-email";
+const CONFIG_KEY = "email";
+const VALID_PROVIDERS = ["console", "resend", "sendgrid", "postmark", "smtp"];
+function flattenProviders(providers) {
+  if (!providers) return void 0;
+  const result = {};
+  for (const [name, opts] of Object.entries(providers)) {
+    if (!opts) continue;
+    result[name] = {
+      apiKey: opts.apiKey,
+      from: opts.from,
+      smtpHost: opts.smtp?.host,
+      smtpPort: opts.smtp?.port,
+      smtpUser: opts.smtp?.user,
+      smtpPass: opts.smtp?.pass,
+      smtpSecure: opts.smtp?.secure
+    };
+  }
+  return result;
+}
+function scanTemplates(dir) {
+  if (!existsSync(dir)) return [];
+  const found = [];
+  const walk = (current) => {
+    for (const entry of readdirSync(current, { withFileTypes: true })) {
+      const full = join(current, entry.name);
+      if (entry.isDirectory()) {
+        walk(full);
+      } else if (entry.isFile() && entry.name.endsWith(".vue")) {
+        const name = relative(dir, full).replace(/\\/g, "/").replace(/\.vue$/, "");
+        found.push({ name, absPath: full });
+      }
+    }
+  };
+  walk(dir);
+  return found;
+}
+const module$1 = defineNuxtModule({
+  meta: {
+    name: MODULE_NAME,
+    configKey: CONFIG_KEY,
+    compatibility: {
+      nuxt: ">=4.0.0"
+    }
+  },
+  defaults: {
+    provider: "console",
+    from: void 0,
+    templateDir: "server/emails",
+    preview: true,
+    retries: 2,
+    retryDelay: 1e3
+  },
+  setup(options, nuxt) {
+    const logger = useLogger(MODULE_NAME);
+    const { resolve: resolve$1 } = createResolver(import.meta.url);
+    if (!VALID_PROVIDERS.includes(options.provider)) {
+      throw new Error(
+        `[nuxt-email] Unknown provider "${options.provider}". Valid options: ${VALID_PROVIDERS.join(", ")}`
+      );
+    }
+    if (options.provider !== "console" && !options.from) {
+      logger.warn(
+        "`email.from` is not set. Emails will fail unless `from` is passed per-call. Set `email.from` in nuxt.config.ts."
+      );
+    }
+    const runtimeConfig = nuxt.options.runtimeConfig;
+    runtimeConfig._email = {
+      provider: options.provider,
+      apiKey: options.apiKey ?? "",
+      from: options.from ?? "",
+      smtpHost: options.smtp?.host ?? "",
+      smtpPort: options.smtp?.port ?? 587,
+      smtpUser: options.smtp?.user ?? "",
+      smtpPass: options.smtp?.pass ?? "",
+      smtpSecure: options.smtp?.secure ?? false,
+      retries: options.retries,
+      retryDelay: options.retryDelay,
+      providers: flattenProviders(options.providers)
+    };
+    const templatesDir = resolve(
+      nuxt.options.rootDir,
+      options.templateDir
+    );
+    const templatesFile = addTemplate({
+      filename: "nuxt-email/templates.mjs",
+      write: true,
+      getContents: () => {
+        const templates = scanTemplates(templatesDir);
+        const imports = templates.map(
+          (t, i) => `import * as t${i} from ${JSON.stringify(t.absPath.replace(/\\/g, "/"))}`
+        ).join("\n");
+        const entries = templates.map(
+          (t, i) => `  ${JSON.stringify(t.name)}: t${i}.default,`
+        ).join("\n");
+        const previewEntries = templates.map((t, i) => `  ${JSON.stringify(t.name)}: __pp(t${i}),`).join("\n");
+        return `${imports}
+
+const __pp = m => (m && m.previewProps) ? m.previewProps : {}
+
+export const templates = {
+${entries}
+}
+
+export const previewProps = {
+${previewEntries}
+}
+`;
+      }
+    });
+    const templatesFilePath = templatesFile.dst.replace(/\\/g, "/");
+    const templatesDirPath = templatesDir.replace(/\\/g, "/");
+    const onNitroConfig = nuxt.hook;
+    onNitroConfig("nitro:config", (config) => {
+      config.alias = config.alias || {};
+      config.alias["#nuxt-email/templates"] = templatesFilePath;
+      config.externals = config.externals || {};
+      config.externals.inline = config.externals.inline || [];
+      config.externals.inline.push(templatesFilePath, templatesDirPath);
+      config.rollupConfig = config.rollupConfig || {};
+      config.rollupConfig.plugins = config.rollupConfig.plugins || [];
+      config.rollupConfig.plugins.push(vuePlugin());
+    });
+    addServerImports([
+      {
+        name: "useEmail",
+        from: resolve$1("./runtime/server/composables/useEmail")
+      }
+    ]);
+    if (nuxt.options.dev && options.preview) {
+      addServerHandler({
+        route: "/_email/preview/:template",
+        handler: resolve$1("./runtime/server/api/preview")
+      });
+      addServerHandler({
+        route: "/_email/send-test/:template",
+        method: "post",
+        handler: resolve$1("./runtime/server/api/send-test.post")
+      });
+      addServerHandler({
+        route: "/_email/templates",
+        method: "get",
+        handler: resolve$1("./runtime/server/api/templates.get")
+      });
+      addServerHandler({
+        route: "/_email/log",
+        method: "get",
+        handler: resolve$1("./runtime/server/api/log.get")
+      });
+      addServerHandler({
+        route: "/_email/config",
+        method: "get",
+        handler: resolve$1("./runtime/server/api/config.get")
+      });
+      addServerHandler({
+        route: "/_email/devtools",
+        handler: resolve$1("./runtime/server/api/devtools")
+      });
+      addCustomTab({
+        name: "nuxt-email",
+        title: "Email",
+        icon: "carbon:email",
+        view: { type: "iframe", src: "/_email/devtools" }
+      });
+    }
+    addTypeTemplate({
+      filename: "types/nuxt-email.d.ts",
+      getContents: () => `
+import type { EmailRuntimeConfig } from '${resolve$1("./runtime/types/index.js")}'
+
+declare module 'nitropack' {
+  interface NitroRuntimeConfig {
+    _email: EmailRuntimeConfig
+  }
+}
+
+export {}
+`
+    });
+    logger.success(`nuxt-email ready (provider: ${options.provider})`);
+  }
+});
+
+export { module$1 as default };

package/dist/runtime/server/api/config.get.d.ts

@@ -0,0 +1,5 @@
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, {
+    provider: string;
+    providers: ("resend" | "sendgrid" | "postmark" | "smtp" | "console")[];
+}>;
+export default _default;

package/dist/runtime/server/api/config.get.js

@@ -0,0 +1,10 @@
+import { defineEventHandler } from "h3";
+import { useRuntimeConfig } from "nitropack/runtime";
+import { VALID_PROVIDERS } from "../utils/providers/index.js";
+export default defineEventHandler(() => {
+  const config = useRuntimeConfig()._email;
+  return {
+    provider: config.provider,
+    providers: VALID_PROVIDERS
+  };
+});

package/dist/runtime/server/api/devtools.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Response>;
+export default _default;