Mail

@veloxts/mail provides email sending with type-safe React Email templates, supporting SMTP and Resend.

Installation

pnpm add @veloxts/mail

# For Resend (recommended)
pnpm add resend

Quick Start

import { mailPlugin } from '@veloxts/mail';

// Log driver - prints to console
app.register(mailPlugin({
  driver: 'log',
  from: { name: 'My App', email: 'noreply@myapp.com' },
}));

import { mailPlugin } from '@veloxts/mail';

app.register(mailPlugin({
  driver: 'resend',
  config: {
    apiKey: process.env.RESEND_API_KEY,
  },
  from: { name: 'My App', email: 'noreply@myapp.com' },
}));

import { mailPlugin } from '@veloxts/mail';

app.register(mailPlugin({
  driver: 'smtp',
  config: {
    host: process.env.SMTP_HOST,
    port: parseInt(process.env.SMTP_PORT || '587'),
    secure: process.env.SMTP_SECURE === 'true',
    auth: {
      user: process.env.SMTP_USER,
      pass: process.env.SMTP_PASS,
    },
  },
  from: { name: 'My App', email: 'noreply@myapp.com' },
}));

Define Templates

import { defineMail } from '@veloxts/mail';
import { z } from 'zod';
import { Html, Body, Text, Button } from '@react-email/components';

export const WelcomeEmail = defineMail({
  name: 'welcome',
  schema: z.object({
    name: z.string(),
    activationUrl: z.string().url(),
  }),
  subject: ({ name }) => `Welcome, ${name}!`,
  template: ({ name, activationUrl }) => (
    <Html>
      <Body>
        <Text>Hello {name}!</Text>
        <Button href={activationUrl}>Activate Account</Button>
      </Body>
    </Html>
  ),
});

Send Email

// Basic send
await ctx.mail.send(WelcomeEmail, {
  to: 'user@example.com',
  data: { name: 'Alice', activationUrl: 'https://...' },
});

// With CC/BCC
await ctx.mail.send(WelcomeEmail, {
  to: 'user@example.com',
  cc: ['manager@example.com'],
  bcc: ['archive@example.com'],
  data: { ... },
});

// With attachments
await ctx.mail.send(InvoiceEmail, {
  to: 'user@example.com',
  data: { invoice },
  attachments: [
    { filename: 'invoice.pdf', content: pdfBuffer },
  ],
});

Drivers

Log

Console output for development and testing.

Resend

Modern API with React Email integration.

SMTP

Traditional SMTP for any provider.

Production Deployment

Choosing a Provider

Provider	Best For
Resend	Simple API, React Email native
AWS SES	High volume, cost-effective
SendGrid	Enterprise features
Postmark	Transactional focus

Environment Variables

RESEND_API_KEY=re_xxxxxxxxxxxx

SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=your-username
SMTP_PASS=your-password

Production Checklist

Verify sending domain - SPF, DKIM, DMARC
Use environment variables - Never hardcode credentials
Verified From address - Use domain email
Handle bounces - Webhook for bounce/complaints
Queue emails - Use @veloxts/queue for background sending

Queue Emails (Recommended)

Don’t block requests with email sending:

const sendEmailJob = defineJob({
  name: 'email.send',
  schema: z.object({
    template: z.string(),
    to: z.string().email(),
    data: z.record(z.unknown()),
  }),
  handler: async ({ data, ctx }) => {
    const template = templates[data.template];
    await ctx.mail.send(template, { to: data.to, data: data.data });
  },
});

// Dispatch instead of sending directly
await ctx.queue.dispatch(sendEmailJob, {
  template: 'welcome',
  to: 'user@example.com',
  data: { name: 'Alice', activationUrl: '...' },
});

Queue - Background email sending
Ecosystem Overview - All packages