@vocoweb/mail

Production-ready email engine with lifecycle journeys and magic DNS

Features

• Magic DNS: Auto-generate SPF/DKIM records for email deliverability
• Pre-Built Journeys: Welcome, Nudge, Invoice, and Recovery email sequences
• Template Editor: Visual template editor with live preview
• Transaction Support: Easy transactional email sending
• Multi-Provider: Support for SendGrid, SES, Resend, Postmark, Mailgun, and custom providers

Installation

npm install @vocoweb/mail
# or
yarn add @vocoweb/mail
# or
pnpm add @vocoweb/mail

Quick Start

1. Configure Email Provider

import { mail } from '@vocoweb/mail/server';

mail.configure({
    provider: 'resend',
    apiKey: process.env.RESEND_API_KEY,
    fromEmail: '[email protected]',
    fromName: 'Your App',
    domain: 'mail.yourapp.com',
});

2. Send Transactional Email

// Send welcome email
await mail.sendTransactional(
    'welcome',
    '[email protected]',
    {
        userName: 'John',
        appName: 'MyApp',
        brandColor: '#3b82f6',
        actionUrl: 'https://app.example.com/get-started',
    }
);

3. Trigger Lifecycle Journey

// Trigger welcome journey when user signs up
await mail.triggerJourney('welcome', userId, {
    userName: 'John',
    appName: 'MyApp',
});

4. View DNS Records

import { VocoDNSRecords } from '@vocoweb/mail/react';
import { mail } from '@vocoweb/mail/server';

export default async function SettingsPage() {
    const verification = await mail.getDNSRecords('mail.yourapp.com');

    return <VocoDNSRecords verification={verification} />;
}

API Reference

Configuration

import { mail } from '@vocoweb/mail/server';

mail.configure({
    provider: 'resend', // | 'sendgrid' | 'ses' | 'postmark' | 'mailgun' | 'custom'
    apiKey: 're_xxx',
    fromEmail: '[email protected]',
    fromName: 'Your App',
    replyTo: '[email protected]',
    domain: 'mail.yourapp.com',
    endpoint: 'https://your-custom-endpoint.com', // For custom provider
});

Send Email

// Send plain email
await mail.sendEmail({
    to: '[email protected]',
    subject: 'Hello!',
    html: '<p>Welcome to our app!</p>',
    text: 'Welcome to our app!',
});

// Send with template
await mail.sendTemplateEmail(
    'template_id',
    '[email protected]',
    { userName: 'John' }
);

// Send transactional
await mail.sendTransactional('welcome', '[email protected]', data);

Email Journeys

// Create custom journey
await mail.createJourney({
    name: 'Product Onboarding',
    type: 'welcome',
    trigger: { type: 'user_signup' },
    steps: [
        {
            id: 'step_1',
            delay: 0,
            templateId: 'welcome_1',
        },
        {
            id: 'step_2',
            delay: 24 * 60 * 60, // 1 day later
            templateId: 'welcome_2',
        },
    ],
    active: true,
});

// Trigger journey
await mail.triggerJourney('welcome', userId, data);

Templates

// Get template
const template = await mail.getTemplate('welcome_email');

// Create/update template
await mail.upsertTemplate({
    name: 'custom_email',
    subject: 'Hello {{userName}}!',
    html: '<p>Welcome {{userName}}!</p>',
    variables: ['userName'],
});

DNS Records

// Get DNS records for verification
const verification = await mail.getDNSRecords('mail.yourapp.com');

console.log(verification);
// {
//   domain: 'mail.yourapp.com',
//   spf: { type: 'TXT', name: '@', value: 'v=spf1 include:resend.com -all' },
//   dkim: { type: 'CNAME', name: 'resend._domainkey', value: '...' },
//   returnPath: { type: 'CNAME', name: 's1._domainkey', value: '...' },
//   mx: [],
//   verified: false
// }

Email Logs

// Get email logs
const logs = await mail.getEmailLogs({
    to: '[email protected]',
    status: 'delivered',
    limit: 50,
});

Process Queue

// Process pending emails (for cron jobs)
const processed = await mail.processEmailQueue();
console.log(`Processed ${processed} emails`);

Pre-Built Journeys

The package includes these pre-configured journeys:

• welcome: 3-email onboarding series
• nudge: Re-engagement for inactive users
• invoice: Payment confirmation with invoice
• reminder: Payment failure recovery sequence
• renewal: Subscription renewal notice
• cancellation: Cancellation feedback and win-back

React Components

VocoMailProvider

import { VocoMailProvider } from '@vocoweb/mail/react';

export default function RootLayout({ children }) {
    return (
        <VocoMailProvider config={{
            provider: 'resend',
            fromEmail: '[email protected]',
        }}>
            {children}
        </VocoMailProvider>
    );
}

VocoEmailTemplate

import { VocoEmailTemplate } from '@vocoweb/mail/react';

export default function TemplateEditor() {
    return (
        <VocoEmailTemplate
            onSave={(template) => console.log(template)}
        />
    );
}

VocoDNSRecords

import { VocoDNSRecords } from '@vocoweb/mail/react';

export default function DNSSettings() {
    return <VocoDNSRecords verification={verification} />;
}

License

MIT

Made with ❤️ by VocoWeb