npm package: @minhajsadik/nextmailer
Description: NextMailer - Full-stack email infrastructure service with CLI. Send transactional emails at scale with built-in tracking, templates, analytics, and queue management. Features Postfix SMTP bridge, BullMQ queuing, Vercel Blob storage, and comprehensive obse
Author: Minhaj Sadik
Latest version: 2.0.0

# NextMailer

> Full-stack email infrastructure service with CLI. Self-hosted email platform with enterprise features.

[![npm version](https://img.shields.io/npm/v/@minhajsadik/nextmailer.svg)](https://www.npmjs.com/package/@minhajsadik/nextmailer)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/node/v/@minhajsadik/nextmailer.svg)](https://nodejs.org)

NextMailer is a comprehensive email infrastructure service that you can self-host. It provides everything you need to send transactional and marketing emails at scale, with built-in tracking, templates, analytics, and queue management.

## ✨ Features

- **🚀 Full Email Service**: Complete email infrastructure in a single package
- **📧 Multiple Providers**: SMTP, AWS SES, SendGrid, Postmark, Mailgun, Resend support
- **🔄 Queue Management**: BullMQ + Redis for reliable email delivery
- **💾 Storage**: Vercel Blob storage (preferred) or S3/MinIO
- **📊 Analytics**: Built-in tracking, opens, clicks, and bounce handling
- **🎨 Template Engine**: Mustache templates with live preview
- **🔐 Security**: JWT + API keys authentication (no external dependencies)
- **📈 Observability**: OpenTelemetry, Prometheus, Grafana, Loki integration
- **🖥️ Dashboard**: Next.js + Tailwind CSS admin interface
- **🛠️ CLI**: Powerful command-line interface for all operations
- **🏗️ Infrastructure**: PostgreSQL (Prisma ORM), Redis, optional ClickHouse for analytics

## 📦 Installation

### Local Installation (Recommended)

```bash
# Using pnpm (recommended)
pnpm add @minhajsadik/nextmailer

# Using npm
npm install @minhajsadik/nextmailer

# Using yarn
yarn add @minhajsadik/nextmailer
```

### Global Installation

```bash
# Install globally for system-wide CLI access
pnpm add -g @minhajsadik/nextmailer

# Or use directly without installation
pnpm dlx @minhajsadik/nextmailer --help
```

### Requirements

- Node.js >= 18.17.0
- PostgreSQL database
- Redis instance (Upstash Redis recommended for production)

## 🚀 Quick Start

### 1. Initialize Configuration

```bash
# Create initial configuration (coming soon)
nextmailer init

# For now, create .env manually
cp .env.example .env
```

### 2. Configure Environment

Edit `.env` with your settings:

```env
# Database (PostgreSQL)
DATABASE_URL=postgresql://user:password@localhost:5432/nextmailer
# Or use POSTGRES_URL for Vercel Postgres
POSTGRES_URL=postgresql://user:password@localhost:5432/nextmailer

# Redis (Required - Upstash recommended)
REDIS_URL=redis://localhost:6379
# For Upstash Redis:
UPSTASH_REDIS_REST_URL=https://your-instance.upstash.io
UPSTASH_REDIS_REST_TOKEN=your-token

# Storage (Vercel Blob preferred)
BLOB_READ_WRITE_TOKEN=your-vercel-blob-token

# Security
EMAILER_JWT_SECRET=your-secret-key-min-32-chars
EMAILER_ENCRYPTION_KEY=your-encryption-key-min-32-chars

# Server
PORT=3000
HOST=localhost

# SMTP Configuration (Optional - for sending emails)
SMTP_HOST=smtp.yourdomain.com
SMTP_PORT=587
SMTP_USER=noreply@yourdomain.com
SMTP_PASS=your-password
SMTP_FROM=noreply@yourdomain.com
```

### 3. Run Database Migrations

```bash
# Setup database schema
nextmailer migrate
```

### 4. Start the Service

```bash
# Start the server
nextmailer start

# Start with custom port
nextmailer start --port 4000

# Start with custom env file
nextmailer start --env-file .env.production
```

### 5. Access the Dashboard

Open http://localhost:3000 in your browser to access the admin dashboard.

## 🔧 CLI Commands

NextMailer provides a comprehensive CLI for managing your email infrastructure:

### Core Commands

```bash
# Start the service
nextmailer start [options]
  -p, --port [number]       Port to bind (default: 3000)
  -H, --host [host]        Host to bind (default: localhost)
  -e, --env-file [path]    Path to .env file
  --disable-telemetry      Disable Next.js telemetry

# Check configuration
nextmailer doctor [options]
  -e, --env-file [path]    Path to .env file

# Run database migrations
nextmailer migrate [options]
  -e, --env-file [path]    Path to .env file

# Show version
nextmailer --version

# Show help
nextmailer --help
```

## 📨 Sending Emails

### Via REST API

```bash
# Send a single email
curl -X POST http://localhost:3000/api/v1/email/send \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["recipient@example.com"],
    "subject": "Welcome to NextMailer",
    "html": "<h1>Hello!</h1><p>Welcome to our service.</p>",
    "text": "Hello! Welcome to our service.",
    "from": "noreply@yourdomain.com"
  }'
```

### Via JavaScript/TypeScript

```javascript
// Using fetch
async function sendEmail() {
  const response = await fetch('http://localhost:3000/api/v1/email/send', {
    method: 'POST',
    headers: {
      'X-API-Key': 'your-api-key',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      to: ['recipient@example.com'],
      subject: 'Welcome!',
      html: '<h1>Welcome!</h1>',
      text: 'Welcome!',
      from: 'hello@yourdomain.com',
      replyTo: 'support@yourdomain.com',
    }),
  });

  const result = await response.json();
  console.log('Email sent:', result);
}
```

### Bulk Email Sending

```javascript
// Send to multiple recipients with templates
const response = await fetch('http://localhost:3000/api/v1/email/send/bulk', {
  method: 'POST',
  headers: {
    'X-API-Key': 'your-api-key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    emails: [
      {
        to: ['user1@example.com'],
        subject: 'Welcome {{name}}!',
        html: '<h1>Hello {{name}}!</h1>',
        variables: { name: 'John' },
      },
      {
        to: ['user2@example.com'],
        subject: 'Welcome {{name}}!',
        html: '<h1>Hello {{name}}!</h1>',
        variables: { name: 'Jane' },
      },
    ],
    from: 'noreply@yourdomain.com',
  }),
});
```

## 🏗️ Architecture

NextMailer is built with modern, production-ready technologies aligned with your preferences:

- **Backend**: Next.js 15 with API routes
- **Queue**: BullMQ with Redis for reliable job processing
- **Database**: PostgreSQL with Prisma ORM
- **Storage**: Vercel Blob (preferred per your rules) or S3-compatible storage
- **Email Delivery**: Your own SMTP/Postfix setup to function like an email provider
- **Authentication**: JWT tokens and API keys (no external API key dependencies)
- **Monitoring**: Built-in health checks and metrics
- **UI**: React 19 with Tailwind CSS

## 🔄 Migration from @minhajsadik/emailer

If you're migrating from the old package name:

1. Update package.json:
   ```bash
   npm uninstall @minhajsadik/emailer
   npm install @minhajsadik/nextmailer
   ```

2. Update CLI commands:
   ```bash
   # Old
   emailer start
   
   # New
   nextmailer start
   ```

Note: The old `emailer` command will still work temporarily with a deprecation warning.

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## 📄 License

MIT © [Minhaj Sadik](https://github.com/MinhajSadik)

## 🔗 Links

- [GitHub Repository](https://github.com/MinhajSadik/Emailer)
- [npm Package](https://www.npmjs.com/package/@minhajsadik/nextmailer)
- [Issue Tracker](https://github.com/MinhajSadik/Emailer/issues)

---

Built with ❤️ by the NextMailer team