Email Technical Details

Configuration

The email module is configured in nuxt.config.ts. It supports multiple providers, queuing, rate limiting, and analytics.

Example configuration:

export default defineNuxtConfig({
  emailModule: {
    defaultFrom: 'info@example.com',
    defaultFromName: 'Your Company',
    providers: {
      primary: 'aws-ses', // Options: 'aws-ses', 'resend'
      fallback: 'resend',
    },
    queue: {
      enabled: true,
      batchSize: 50,
      cronSchedule: '* * * * *',
      maxRetries: 3,
    },
    rateLimit: {
      enabled: true,
      awsSes: { perMinute: 14 },
      resend: { perMinute: 10 },
    },
    analytics: {
      enabled: true,
      trackOpens: true,
      trackClicks: true,
    },
  },
})

Email Templates

Templates are Vue components located in the app/emails directory. This allows for dynamic content generation using Vue's template syntax.

Developer Note: Templates are created using code (Vue components), not a visual drag-and-drop editor. You can preview your coded templates in the admin panel, but creating or modifying the design requires developer intervention.

Example app/emails/welcome.vue:

<template>
  <e-html>
    <e-head />
    <e-body>
      <e-container>
        <e-heading>Welcome, {{ name }}!</e-heading>
        <e-text>Thanks for signing up.</e-text>
      </e-container>
    </e-body>
  </e-html>
</template>

<script setup>
defineProps({
  name: String,
})
</script>

Programmatic Sending

Emails are sent using the useEmail composable.

const { send } = useEmail()

await send({
  to: 'user@example.com',
  subject: 'Welcome!',
  template: 'welcome',
  props: {
    name: 'John Doe',
  },
})

Note: The module handles the email delivery infrastructure (queues, providers, templates). Business logic triggers (e.g., "Send welcome email on signup") are implemented in your application's service layer or event handlers, utilizing this sending capability.

Delivery and Engagement Tracking (AWS SES + SNS)

Opens, clicks, deliveries, bounces and spam complaints come back from Amazon SES through an SNS topic. They power Admin → Email → Analytics, per-campaign newsletter analytics and the automatic suppression list.

1. SNS topic: create a Standard topic in the same region as SES and set its message signature version to 2.
2. Configuration set: create one, then add an event destination with Sends, Deliveries, Bounces, Complaints, Rejects, Opens and Clicks, targeting the topic. Opens and clicks only exist with a configuration set.
3. Subscription: subscribe https://your-domain/api/email/webhooks/aws-ses over HTTPS with raw message delivery off. The app verifies the signed confirmation and confirms it automatically. Behind Cloudflare, skip bot and WAF rules for /api/email/webhooks/* first.
4. Environment:

AWS_SES_CONFIGURATION_SET=app-prod
NUXT_EMAIL_SNS_TOPIC_ARNS=arn:aws:sns:eu-central-1:123456789012:ses-events-prod

Every SNS message is checked against the AWS signing certificate (served from an sns.*.amazonaws.com host only) and the topic allow-list. Anything else is refused with 403. Each email carries a tracking-id message tag, so every event lands on the right email, template and campaign.

Test it with the SES mailbox simulator: sending to bounce@simulator.amazonses.com should show up as a bounce and add the address to Admin → Email → Suppressions.