npm package: @rivtor/mail
Description: Production-ready email engine with lifecycle journeys and magic DNS
Author: Rivtor
Latest version: 1.0.1

# @rivtor/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

```bash
npm install @rivtor/mail
# or
yarn add @rivtor/mail
# or
pnpm add @rivtor/mail
```

## Quick Start

### 1. Configure Email Provider

```typescript
import { mail } from '@rivtor/mail/server';

mail.configure({
    provider: 'resend',
    apiKey: process.env.RESEND_API_KEY,
    fromEmail: 'noreply@yourapp.com',
    fromName: 'Your App',
    domain: 'mail.yourapp.com',
});
```

### 2. Send Transactional Email

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

### 3. Trigger Lifecycle Journey

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

### 4. View DNS Records

```tsx
import { VocoDNSRecords } from '@rivtor/mail/react';
import { mail } from '@rivtor/mail/server';

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

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

## API Reference

### Configuration

```typescript
import { mail } from '@rivtor/mail/server';

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

### Send Email

```typescript
// Send plain email
await mail.sendEmail({
    to: 'user@example.com',
    subject: 'Hello!',
    html: '<p>Welcome to our app!</p>',
    text: 'Welcome to our app!',
});

// Send with template
await mail.sendTemplateEmail(
    'template_id',
    'user@example.com',
    { userName: 'John' }
);

// Send transactional
await mail.sendTransactional('welcome', 'user@example.com', data);
```

### Email Journeys

```typescript
// 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

```typescript
// 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

```typescript
// 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

```typescript
// Get email logs
const logs = await mail.getEmailLogs({
    to: 'user@example.com',
    status: 'delivered',
    limit: 50,
});
```

### Process Queue

```typescript
// 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

```tsx
import { VocoMailProvider } from '@rivtor/mail/react';

export default function RootLayout({ children }) {
    return (
        <VocoMailProvider config={{
            provider: 'resend',
            fromEmail: 'noreply@yourapp.com',
        }}>
            {children}
        </VocoMailProvider>
    );
}
```

### VocoEmailTemplate

```tsx
import { VocoEmailTemplate } from '@rivtor/mail/react';

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

### VocoDNSRecords

```tsx
import { VocoDNSRecords } from '@rivtor/mail/react';

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

## License

MIT

---

Made with ❤️ by [Rivtor](https://rivtor.com)