@trovyx/razon 0.0.1 → 0.0.3

package/README.md

@@ -1,639 +1,371 @@
-# Razon - Advanced CLI Email Client
+# Razon
 
-A cutting-edge, enterprise-grade email automation platform developed by the **Razon Team**. Razon delivers unparalleled performance for bulk email campaigns, marketing automation, and professional email management with advanced templating, multi-provider support, and intelligent delivery optimization.
-
-## Features
-
-### 🚀 **Core Email Engine**
-- **Multi-Provider SMTP Support**: Seamlessly integrate with unlimited SMTP providers including Gmail, Outlook, SendGrid, Mailgun, Amazon SES, and custom servers
-- **Intelligent Failover System**: Automatic provider switching with health monitoring and performance optimization
-- **High-Performance Delivery**: Concurrent email processing with configurable parallel connections for maximum throughput
-- **Smart Rate Limiting**: Advanced throttling with hourly, daily, and per-minute limits to respect provider constraints
-
-### 📧 **Advanced Email Composition**
-- **Dynamic Template Engine**: Powerful HTML templating with 50+ built-in variables and custom tag support
-- **Multi-Format Attachments**: Support for PDF, HTML, Images (PNG/JPG), SVG, and EML files with dynamic generation
-- **Intelligent Content Processing**: Automatic image embedding, CSS inlining, and mobile-responsive optimization
-- **Personalization Engine**: Real-time content customization with fake data generation and company lookup integration
-
-### 🎯 **Campaign Management**
-- **Bulk Email Processing**: Efficient batch processing with BCC, CC, and TO distribution modes
-- **Test Mode Environment**: Safe testing with isolated recipient lists and comprehensive validation
-- **Campaign Analytics**: Real-time delivery tracking, bounce handling, and performance metrics
-- **Recipient Management**: CSV/TXT file support with advanced parsing and validation
-
-### 🔒 **Security & Privacy**
-- **Proxy Integration**: Full SOCKS5/HTTP proxy support for enhanced privacy and geographic distribution
-- **Secure Authentication**: OAuth2, API key, and traditional SMTP authentication methods
-- **Encrypted Attachments**: Password-protected PDF generation and secure file handling
-- **Audit Logging**: Comprehensive security logs with configurable retention policies
-
-### 🌐 **Enterprise Integration**
-- **Outlook Web Access (OWA)**: Native support for Office 365 and Exchange Online accounts
-- **Hunter.io Integration**: Automatic company name resolution and email verification
-- **API-First Design**: RESTful endpoints for seamless integration with existing systems
-- **CLI Interface**: Powerful command-line tools for automation and scripting
-
-### 📊 **Monitoring & Analytics**
-- **Real-Time Logging**: Multi-level logging with JSON, text, and structured formats
-- **Performance Metrics**: Delivery rates, response times, and provider performance analytics
-- **Error Handling**: Intelligent retry mechanisms with exponential backoff and dead letter queues
-- **Health Monitoring**: System health checks and automated alerting
+Advanced CLI email client with multi-provider support, dynamic templating, and intelligent delivery optimization.
 
 ## Installation
 
-### Prerequisites
-- Modern runtime environment
-- Version control system
-- Administrative privileges for installation
+```bash
+npm install -g @trovyx/razon
+```
 
-### Quick Setup
+## Quick Start
 
-1. **Clone the Razon repository**:
 ```bash
-git clone <repository-url>
-cd razon-email-client
+# 1. Authenticate
+razon login <your-access-token>
+
+# 2. Create config files
+razon init
+
+# 3. Configure your SMTP/OWA settings
+#    Edit config/smtp.jsonc with your provider credentials
+
+# 4. Send a test email
+razon test
+
+# 5. Send to all recipients
+razon send
 ```
 
-2. **Install dependencies**:
+## Documentation
+
+Run `razon init` to generate configuration files and the complete user guide (`README.txt`). It covers every configuration option, all sending modes, attachment formats, template tags, calendar invites, DKIM setup, and more.
+
+## Features
+
+- **Multi-Provider SMTP** - Unlimited SMTP accounts with automatic failover and load balancing
+- **Outlook Web Access (OWA)** - Native Office 365 and Exchange Online support
+- **Dynamic Templates** - 50+ built-in tags for personalized HTML emails
+- **Attachments** - PDF, HTML, images (PNG/JPG), SVG, and EML with dynamic generation
+- **Password-Protected PDFs** - Generate encrypted PDF attachments on the fly
+- **Calendar Invites** - Attach .ics invites for Teams, Google Meet, Zoom, or custom events
+- **DKIM Signing** - Generate DKIM keys for improved inbox delivery
+- **Bulk & Batch Sending** - BCC, CC, and TO distribution modes with configurable batch sizes
+- **Smart Rate Limiting** - Hourly, daily, and per-minute throttling per provider
+- **Proxy Support** - SOCKS5 and HTTP proxies for geographic distribution
+- **Parallel Connections** - Concurrent email processing for maximum throughput
+- **Contact Enrichment** - Company name and logo lookup via Hunter.io
+- **Asset Caching** - Pre-generate PDFs, SVGs, and images before sending
+- **Custom Tags** - Define per-recipient variables from CSV/Excel columns
+- **Database Tracking** - Track sent emails, prevent duplicates, backup and restore
+- **Device Auth** - Multi-device authentication with PIN and security questions
+
+## Commands
+
+### Sending
+
 ```bash
-# Install required dependencies
-npm install
+razon send                              # Send to all recipients
+razon send 100                          # Send to first 100 recipients
+razon send -f                           # Force re-send to already-sent recipients
+razon send --throttle --delay 10        # Throttle with 10s delay between batches
+razon send --email-before-sleep 500     # Send 500 emails per batch
+razon send --randomize-servers          # Randomize SMTP server selection
+razon send --test-between               # Insert test emails during campaign
+razon send --email-before-test 200      # Send test email every 200 emails
 ```
 
-3. **Initialize configuration**:
+### Testing
+
 ```bash
-# Copy example configurations
-cp config/core.jsonc.example config/core.jsonc
-cp config/smtp.jsonc.example config/smtp.jsonc
-cp config/message.jsonc.example config/message.jsonc
+razon test                              # Send test emails (default: 5)
+razon test 10                           # Send 10 test emails
 ```
 
-4. **Build the project**:
+### Asset Caching
+
 ```bash
-# Build the application
-npm run build
+razon cache-only                        # Cache email assets without sending
+razon cache-only -f                     # Force regenerate cached assets
+razon cache-only --template my-template # Cache specific template assets
+razon cache-only --parallel 8           # Use 8 parallel threads
+razon cache-only --clean                # Remove existing assets before caching
+razon cache-only --clear-only           # Remove all cached assets
+razon cache-only --clear-only my-template  # Remove cache for specific template
 ```
 
-### Docker Installation (Alternative)
+### Contact Enrichment
 
 ```bash
-# Pull the official Razon image
-docker pull razon/email-client:latest
+razon cache leads.txt                   # Cache company names & logos
+razon cache leads.csv -a ./api.txt      # Specify Hunter.io API key file
+razon cache leads.csv -s                # Skip names, logos only
+razon cache leads.csv -b 20             # Process 20 domains per batch
+
+razon contacts leads.txt                # Enrich file with company data
+razon contacts data.csv -e 3 -c 5       # Email in col 3, company name to col 5
+razon contacts leads.xlsx -m file       # Download logo images to files
+razon contacts data.csv --skip-logo     # Company names only
+razon contacts leads.csv -o xlsx        # Force Excel output
+```
+
+### Email List Management
 
-# Run with volume mounting for configuration
-docker run -v $(pwd)/config:/app/config razon/email-client:latest
+```bash
+razon remove-dup emails.txt             # Remove duplicate emails
+razon remove-bad emails.txt             # Remove invalid emails
+razon remove-bad emails.csv -t provider -d gmail.com,yahoo.com  # Remove by provider
+razon remove-non-unique new.txt         # Remove emails already in database
+razon remove-unique all.txt             # Keep only emails in database
 ```
 
-## Quick Start
+### Tags
 
-### 🎯 **Getting Started in 5 Minutes**
-
-1. **Configure Your Email Provider**: 
-   Edit `config/smtp.jsonc` with your SMTP server credentials:
-   ```bash
-   # Configure your email provider settings
-   nano config/smtp.jsonc
-   ```
-
-2. **Design Your Email Campaign**: 
-   Configure `config/message.jsonc` with your email content and templates:
-   ```bash
-   # Set up your email template and content
-   nano config/message.jsonc
-   ```
-
-3. **Prepare Your Recipient List**: 
-   Create a recipient file with email addresses:
-   ```bash
-   # Create recipients file (supports .txt and .csv)
-   echo "recipient1@example.com" > recipients.txt
-   echo "recipient2@example.com" >> recipients.txt
-   ```
-
-4. **Launch Your Campaign**:
-   ```bash
-   # Start Razon CLI
-   npm start
-   
-   # Or run in test mode first
-   npm run test-mode
-   ```
-
-### 🧪 **Test Mode (Recommended for First Run)**
-
-Before sending to real recipients, always test your configuration:
+```bash
+razon tags                              # Show available template tags
+razon tags contacts.csv                 # Show tags from CSV/Excel columns
+```
+
+### DKIM
 
 ```bash
-# Enable test mode in config/core.jsonc
-{
-  "enableTestMode": true,
-  "testLeadsFile": "test-recipients.txt",
-  "testLeadsLimit": 5
-}
+razon dkim yourdomain.com               # Generate DKIM keys
+razon dkim yourdomain.com -s myselector # Custom selector name
+razon dkim yourdomain.com -o ./keys     # Custom output directory
+razon dkim                              # Show full DKIM help
+```
 
-# Create test recipients
-echo "test@yourdomain.com" > test-recipients.txt
+### Database & Backups
 
-# Run test campaign
-npm run test
+```bash
+razon count-total                       # Show emails sent per provider
+razon summary                           # Full system summary
+razon summary --smtp                    # SMTP summary only
+razon summary --owa                     # OWA summary only
+
+razon backup                            # Create database backup
+razon backup my-backup                  # Named backup
+razon list-backups                      # List available backups
+razon restore my-backup                 # Restore from backup
+razon restore my-backup -c              # Clear database before restore
+razon clear --confirm                   # Clear entire database (irreversible)
 ```
 
-### 📊 **Monitor Your Campaign**
+### Authentication
 
 ```bash
-# View real-time logs
-tail -f mailer.log
+razon login <token>                     # Authenticate with access token
+razon logout                            # Log out current device
+
+razon auth list                         # List registered devices
+razon auth device <id>                  # Show device details
+razon auth pin                          # Change your PIN
+razon auth reset-pin <token>            # Reset PIN via security questions
+razon auth add-security                 # Add a security question
+```
 
-# Check delivery status
-npm run status
+### System
 
-# View campaign analytics
-npm run analytics
+```bash
+razon init                              # Create config files
+razon init -f                           # Force overwrite existing config
+razon install                           # Install Chromium for PDF/image generation
+razon install-pdf                       # Install PDF conversion binary
+razon check-update                      # Check for available updates
+razon upgrade                           # Upgrade Razon to latest version
+razon upgrade -f                        # Force reinstall
+razon version                           # Show version
 ```
 
 ## Configuration
 
-Razon uses a modular JSONC configuration system that provides maximum flexibility and maintainability. All configuration files are located in the `config/` directory and support comments for better documentation.
+Run `razon init` to generate all config files in a `config/` folder:
+
+| File                    | Purpose                                                          |
+| ----------------------- | ---------------------------------------------------------------- |
+| `core.jsonc`            | Global settings, test mode, proxy, parallel connections, logging |
+| `smtp.jsonc`            | SMTP provider accounts and rate limits                           |
+| `message.jsonc`         | Email subject, body, recipients, calendar invites                |
+| `attachments.jsonc`     | PDF, image, HTML, SVG, and EML attachment settings               |
+| `addon/owa.jsonc`       | Outlook Web Access accounts                                      |
+| `eml/attachments.jsonc` | EML-specific attachment settings                                 |
+
+All config files use JSONC format (JSON with comments).
+
+## Template Tags
 
-### 📁 **Configuration Structure**
+Razon has 80+ built-in tags that resolve dynamically across every part of your email — subject, body, from name, attachment content, attachment filenames, EML headers, calendar invites, and disclaimer text. Tags work everywhere, automatically.
+
+### How Tags Flow
+
+Tags are resolved using a **multi-pass recursive engine**. If a tag resolves to a value that itself contains another tag, Razon resolves that too — up to 3 levels deep. This means tags can nest naturally without any special syntax.
+
+Tags flow through every layer of your email:
 
 ```
-config/
-├── core.jsonc              # Core application settings and global preferences
-├── smtp.jsonc              # SMTP server configurations and provider settings
-├── message.jsonc           # Email message templates and content settings
-├── attachments.jsonc       # Attachment configurations and processing rules
-├── addon/
-│   └── owa.jsonc          # Outlook Web Access integration settings
-└── eml/
-    └── attachments.jsonc  # EML-specific attachment configurations
+Subject          →  "Hello {FIRST_NAME}, your invoice {UNIQUE_ID}"
+From Name        →  "{FAKE_FULL_NAME}"
+Body HTML        →  All tags replaced, including {PDF_PASSWORD}
+Attachment HTML  →  Tags replaced before converting to PDF/Image
+Attachment Name  →  "Invoice_{UNIQUE_ID}.pdf"
+EML Subject      →  Tags replaced independently
+EML Headers      →  Custom headers with tags
+EML Body         →  Full tag replacement inside nested email
+Calendar Invite  →  Tags in title, description, attendee fields
 ```
 
-### ⚙️ **Core Configuration (`config/core.jsonc`)**
+A single `{PDF_PASSWORD}` generated in the body is automatically shared across all attachments and nested EML content in the same email — so the password in the body always matches the password on the PDF.
 
-The central configuration file that controls Razon's core functionality and global behavior:
+### Custom Tags from CSV/Excel (Highest Priority)
 
-```json
-{
-    "name": "Razon Advanced Email Client",
-    "enableTestMode": false,
-    "testLeadsFile": "test-leads.txt",
-    "testLeadsLimit": 5,
-    "useBulkSending": false,
-    "bulkSending": {
-        "batchSize": 50,
-        "useBccForSending": true,
-        "useCcForSending": false,
-        "useToForSending": false
-    },
-    "enableSleepBetweenEmails": false,
-    "delayDurationInSeconds": 10,
-    "emailsBeforeSleep": 1000,
-    "randomizeEmailServers": true,
-    "proxy": {
-        "useProxy": false,
-        "host": "localhost",
-        "port": 8080,
-        "user": "user",
-        "pass": "pass",
-        "protocol": "socks5",
-        "useAuthentication": false
-    },
-    "parallel": {
-        "parallelConnections": 10,
-        "enableParallelSending": true
-    },
-    "logging": {
-        "enabled": true,
-        "level": "info",
-        "logFile": "mailer.log",
-        "format": "text",
-        "logFailed": true,
-        "logSuccess": true
-    },
-    "HUNTER_API_KEY": [
-        "your-hunter-api-key"
-    ]
-}
+When using a CSV or Excel file as your recipient list, column headers automatically become tags. Custom tags are resolved **before** built-in tags, so you can override any built-in tag with per-recipient data.
+
+```
+CSV: Email, First Name, Company, Deal Size
+  →  {FIRST_NAME}, {COMPANY}, {DEAL_SIZE}
 ```
 
-### 📧 **SMTP Configuration (`config/smtp.jsonc`)**
+Use `razon tags` to inspect available tags for your recipient file.
 
-Configure multiple email providers with intelligent load balancing and failover capabilities:
+### Built-in Tags
 
-```json
-{
-    "randomizeEmailServers": true,
-    "accounts": [
-        {
-            "useMe": true,
-            "host": "smtp.resend.com",
-            "port": 587,
-            "secure": false,
-            "user": "resend",
-            "pass": "your-api-key",
-            "fromEmail": "campaigns@yourdomain.com",
-            "fromName": "Your Campaign Name",
-            "useAuth": true,
-            "dailyLimit": 10000,
-            "retryFailed": false,
-            "retryCount": 2,
-            "useProxy": false,
-            "options": {
-                "enableHourlyLimit": false,
-                "sendPerHour": 100,
-                "enableMinuteLimit": false,
-                "sendPer10Minutes": 10
-            },
-            "advance": {
-                "pool": false,
-                "maxConnections": 5,
-                "maxMessages": 100
-            }
-        }
-    ]
-}
-```
+**Recipient & Domain**
 
-### 📝 **Message Configuration (`config/message.jsonc`)**
+| Tag | Output |
+| --- | ------ |
+| `{EMAIL_ADDRESS}` / `{EMAIL}` | Recipient's email |
+| `{USERNAME}` | Local part of email |
+| `{DOMAIN}` | Domain of email |
+| `{COMPANY_NAME}` | Company name derived from domain |
+| `{COMPANY_NAME_CAPITALIZED}` | Capitalized variant |
+| `{REAL_COMPANY_NAME}` | Real company name via Hunter.io |
+| `{REAL_COMPANY_LOGO}` / `{REAL_COMPANY_LOGO_URL}` | Company logo |
 
-Design sophisticated email campaigns with dynamic content and advanced personalization:
+**Personalization (Fake Data)**
 
-```json
-{
-    "subject": "Your Personalized Campaign Subject",
-    "fromEmail": "campaigns@yourdomain.com",
-    "priority": "normal",
-    "fromName": "",
-    "yourLinks": [],
-    "linksFromFile": "../links.txt",
-    "useLinkFromFile": false,
-    "subjects": {
-        "enabled": false,
-        "subjectsPath": "subject.txt",
-        "offset": 0,
-        "mode": "sequence",
-        "countBeforeSubject": 500,
-        "startFresh": false
-    },
-    "fromNames": {
-        "enabled": false,
-        "namesPath": "from-names.txt",
-        "offset": 0,
-        "mode": "sequence",
-        "countBeforeName": 500,
-        "startFresh": false
-    },
-    "recipient_file": "recipients.txt",
-    "body": {
-        "useHTML": true,
-        "latterPath": "letter.html",
-        "image": {
-            "embedInLetter": false,
-            "imagePath": "image.png",
-            "alt": "Campaign Image",
-            "strictMode": true,
-            "style": {
-                "useStyle": false,
-                "width": "100%",
-                "height": "100%",
-                "marginTop": "0px",
-                "marginBottom": "0px",
-                "marginLeft": "0px",
-                "marginRight": "0px",
-                "paddingTop": "0px",
-                "paddingBottom": "0px",
-                "paddingLeft": "0px",
-                "paddingRight": "0px",
-                "borderRadius": "0px"
-            }
-        }
-    }
-}
-```
+| Tag | Output |
+| --- | ------ |
+| `{FAKE_FIRST_NAME}` / `{FAKE_LAST_NAME}` / `{FAKE_FULL_NAME}` | Random names |
+| `{FAKE_COMPANY_NAME}` / `{FAKE_COMPANY_EMAIL}` | Random company |
+| `{FAKE_EMAIL}` | Random email |
+| `{FAKE_PHONE_NUMBER}` | Random phone |
+| `{FAKE_ADDRESS}` / `{FAKE_CITY}` / `{FAKE_STATE}` / `{FAKE_ZIP_CODE}` / `{FAKE_COUNTRY}` | Random address |
 
-# Calendar Invites (Production)
+**Dates & Time**
 
-Use this guide to attach calendar invites to your emails so recipients can add events directly to their calendars. Supports Microsoft Teams, Google Meet, Zoom, and a generic standard format.
+| Tag | Output |
+| --- | ------ |
+| `{DATE}` / `{TIME}` | Current date/time |
+| `{TODAY_DATE}` / `{TODAY_DATE_SHORT}` / `{TODAY_DATE_LONG}` / `{TODAY_DATE_FULL}` | Date in multiple formats |
+| `{TOMORROW_DATE}` / `{YESTERDAY_DATE}` | Relative dates (also with short/long/full variants) |
 
-## Scope
-- Single-recipient sending with SMTP mode only
-- Either attach an existing `.ics` file or generate one dynamically from configuration
-- ICS stores times in UTC; email body displays times using the configured timezone
+**Random & Unique**
 
-## Requirements
-- Single-recipient send flow enabled
-- Valid meeting links for your chosen platform
-- `.ics` file (if using an existing invite)
-- Optional `.txt` file for description content
+| Tag | Output |
+| --- | ------ |
+| `{UNIQUE_ID}` / `{UUID}` | Unique identifiers |
+| `{RANDOM_STRING}` / `{RANDOM_50_CHAR_STRING}` / `{RANDOM_100_CHAR_STRING}` | Random strings |
+| `{RANDOM_N_DIGIT_NUMBER}` | Random number with N digits (any length) |
+| `{RANDOM_N_TEXTNUMBER}` | Random alphanumeric string of length N |
 
-## Configuration
-Place a `calendar` block in your message configuration. Tags are supported for dynamic values:
-- `@from` uses the sender’s email or name
-- `@to` uses the recipient’s email (not valid in batch mode)
-- `@email` uses the attendee’s email as display name
+**Encoding**
 
-```jsonc
-{
-  "calendar": {
-    "use": true,
-    "icsPath": "../tmp/meeting.ics",
-    "useIcsPath": false,
-    "useMainMessageBody": false,
+| Tag | Output |
+| --- | ------ |
+| `{BASE64_EMAIL_ADDRESS}` / `{BASE64_EMAIL}` | Base64-encoded email |
+| `{BASE64_USERNAME}` / `{BASE64_DOMAIN}` | Base64-encoded parts |
+| `{BASE64_COMPANY_NAME}` / `{BASE64_UUID}` | Base64-encoded values |
 
-    // Required
-    "organizerEmail": "@from",
-    "attendeeEmail": "@to",
-    "start": "now",
-    "end": "+1hours",
+**Special**
 
-    // Optional
-    "type": "teams",                // "teams" | "google" | "zoom" | "standard"
-    "appName": "mister-man",        // UID suffix; default "razon" when empty
-    "title": "Project Kickoff",
-    "organizerName": "@from",
-    "attendeeName": "@email",
+| Tag | Output |
+| --- | ------ |
+| `{PAGE_LINK}` | Dynamic page link from config |
+| `{PDF_PASSWORD}` | Auto-generated password (shared across entire email) |
+| `{LOCAL_IMAGE}` | Embedded local image |
 
-    // Platform-specific links
-    "teamsLink": "https://teams.microsoft.com/l/meetup-join/...",
-    "googleLink": "https://meet.google.com/abc-defg-hij",
-    "zoomLink": "https://zoom.us/j/1234567890",
-    "zoomMeetingId": "123 456 7890",
-    "zoomPasscode": "",
-
-    // Fallback/metadata
-    "location": "HQ Boardroom",     // default "Online" when empty
-    "importance": "high",           // "high" | "normal"
-    "description": "Agenda:\n- Intro\n- Timeline\n- Next steps",
-    "descriptionPath": "../tmp/description.txt",
-    "useDescriptionPath": false,
-    "timezone": "Africa/Lagos"      // pretty HTML timezone; default "UTC" when empty
-  }
-}
-```
+## Attachments
+
+Razon converts HTML templates into multiple attachment formats on the fly, with full tag replacement in every format. Configure in `config/attachments.jsonc`.
+
+### Supported Formats
+
+| Format    | Description |
+| --------- | ----------- |
+| **PDF**   | Generate from HTML. Password protection, landscape/portrait, custom margins, A4/Letter page sizes. |
+| **Image** | Convert HTML to JPEG or PNG. Configurable quality, fit-to-paper modes, background rendering. |
+| **HTML**  | Attach raw HTML files with full tag replacement. |
+| **SVG**   | Attach SVG vector graphics with tag replacement. |
+| **TXT**   | Plain text attachments. |
+| **EML**   | Full email-within-email — see below. |
+
+### Key Capabilities
+
+- **Multiple attachments per email** - Any combination of formats in a single email
+- **Dynamic filenames** - Tags in filenames: `Invoice_{UNIQUE_ID}_{COMPANY_NAME}.pdf`
+- **Tag replacement in content** - All 80+ tags resolve inside attachment HTML before conversion
+- **Password-protected PDFs** - Use `{PDF_PASSWORD}` in your body, and the same password encrypts the PDF
+- **Inline attachments** - Embed PDFs or images directly in the email body
+- **Asset pre-caching** - Pre-generate all attachments with `razon cache-only` for faster campaign sends
+
+### EML Attachments (Email-within-Email)
 
-## Key Behaviors
-- Enable with `use: true` in single-recipient SMTP mode
-- Use an existing `.ics` by setting `useIcsPath: true` and `icsPath` to your file; other calendar fields are ignored
-- `useMainMessageBody: true` uses your main email body as the calendar description (auto-enabled when `useIcsPath` is true)
-- Time inputs for `start` and `end`:
-  - `"now"`
-  - Relative time like `"+30minutes"`, `"+2hours"`, `"-3days"`, `"+1week"`, `"+1month"`, `"+1year"`
-- `attendeeName`:
-  - Empty → `"Attendee"`
-  - `@email` → attendee email becomes the display name
-- `importance`:
-  - `"high"` highlights priority in some clients
-  - `"normal"` standard priority
-- `location` defaults to `"Online"` if not provided
-- `timezone` formats human-readable times in the email body; ICS stays in UTC
-
-## Platform Notes
-- Microsoft Teams
-  - Provide a valid Teams link; recipients can use the “Join your Teams meeting” flow from the email
-- Google Meet
-  - Use the `https://meet.google.com/xxx-yyyy-zzz` format
-  - Guests must be invited or admitted by the host
-- Zoom
-  - Browsers may prompt to open the Zoom app
-  - Recipients can join via the Zoom Workplace app or the web if prompts don’t appear
-
-## Operational Tips
-- Prefer dynamic generation when you need consistent formatting and platform-specific buttons in the email body
-- Prefer `useIcsPath` when integrating with external scheduling systems that already provide `.ics`
-- In non-batch sending, `@to` simplifies attendee assignment
-- Keep meeting IDs and passcodes out of logs; treat them as sensitive
+EML is one of Razon's most powerful features. An EML attachment is a fully-formed email (.eml file) attached inside your main email. It has its own sender, subject, body, headers, and can even contain its own attachments.
+
+**What makes EML powerful:**
+
+- **Own identity** - Each EML has its own `fromEmail`, `fromName`, `subject`, and `priority` — all with tag replacement
+- **Custom headers** - Add any RFC headers (`X-Mailer`, `Reply-To`, etc.) with dynamic tags
+- **CC recipients** - EML attachments can include CC recipients with display names
+- **Nested attachments** - An EML can contain PDF, Image, HTML, SVG, TXT, or even another EML inside it
+- **Full tag flow** - Tags resolve independently in EML content, but `{PDF_PASSWORD}` propagates from the parent email so passwords stay consistent
+- **Separate attachment config** - EML attachments use their own config (`config/eml/attachments.jsonc`), giving you independent control over what goes inside the nested email
+
+**Nesting example:**
+
+```
+Main Email
+├── Body HTML (tags replaced, {PDF_PASSWORD} generated)
+├── Attachment: Invoice_{UNIQUE_ID}.pdf (password-protected)
+└── Attachment: forwarded-message.eml
+    ├── From: {FAKE_FULL_NAME} <{FAKE_EMAIL}>
+    ├── Subject: "Re: {COMPANY_NAME} Proposal"
+    ├── Headers: X-Original-Sender: {EMAIL_ADDRESS}
+    ├── Body HTML (tags replaced, same PDF password)
+    └── Nested Attachment: proposal_{UNIQUE_ID}.pdf
 ```
 
-### 📎 **Attachment Configuration (`config/attachments.jsonc`)**
+Every layer gets full tag replacement. The PDF password generated in the main body flows through to every nested attachment, so a single `{PDF_PASSWORD}` tag keeps everything in sync.
 
-Configure sophisticated file attachments with dynamic generation and multi-format support:
+### Pre-caching Assets
 
-```json
-{
-    "useAttachment": true,
-    "throwErrorOnInvalidAttachment": true,
-    "replaceTagsInAttachment": true,
-    "attachments": [{
-        "useMe": true,
-        "format": "PDF",
-        "attachmentPath": "letterAttachment.html",
-        "attachmentNameWithPlaceholders": "Document_{UNIQUE_ID}.pdf",
-        "pdf": {
-            "usePassword": false,
-            "password": "secret",
-            "inlineAttachment": false,
-            "landscape": false,
-            "printBackground": true,
-            "format": "A4",
-            "margin": {
-                "top": 1,
-                "left": 1,
-                "bottom": 1,
-                "right": 1
-            }
-        },
-        "image": {
-            "inlineAttachment": false,
-            "type": "jpeg",
-            "format": "A4",
-            "landscape": true,
-            "margin": {
-                "top": 0,
-                "left": 0,
-                "bottom": 0,
-                "right": 0
-            },
-            "printBackground": true,
-            "fitToPaperMode": "Default",
-            "optimizeForSpeed": true,
-            "quality": 80
-        },
-        "eml": {
-            "useMessageConfig": true,
-            "fromEmail": "campaigns@yourdomain.com",
-            "fromName": "Campaign Team",
-            "subject": "Attached Email Message",
-            "priority": "normal",
-            "attachment": {
-                "useAttachment": false,
-                "throwErrorOnInvalidAttachment": false
-            },
-            "headers": {
-                "X-Mailer": "Razon Email Client"
-            }
-        }
-    }]
-}
+For large campaigns, pre-generate all attachments before sending:
+
+```bash
+razon cache-only                        # Generate all assets
+razon cache-only --parallel 8           # Use 8 threads for faster generation
+razon cache-only --template invoice     # Cache specific template only
+razon send                              # Send with pre-cached assets
 ```
 
-### 🌐 **OWA Configuration (`config/addon/owa.jsonc`)**
+## Calendar Invites
 
-Configure Outlook Web Access integration for seamless Office 365 and Exchange Online email sending:
+Attach calendar invites to emails with support for Microsoft Teams, Google Meet, Zoom, and standard ICS format.
 
-```json
+Add a `calendar` block in `config/message.jsonc`:
+
+```jsonc
 {
-    "randomizeEmailServers": true,
-    "accounts": [{
-        "useMe": false,
-        "senderEmail": "your-email@company.com",
-        "webmail_url": "https://outlook.office.com/mail/",
-        "cookie_string": "your-session-cookies",
-        "deleteOnSent": true,
-        "dailyLimit": 10000,
-        "retryFailed": false,
-        "retryCount": 2,
-        "useProxy": false,
-        "options": {
-            "enableHourlyLimit": false,
-            "sendPerHour": 100,
-            "enableMinuteLimit": false,
-            "sendPer10Minutes": 10
-        }
-    }]
+  "calendar": {
+    "use": true,
+    "type": "teams", // "teams" | "google" | "zoom" | "standard"
+    "title": "Project Kickoff",
+    "start": "now",
+    "end": "+1hours",
+    "organizerEmail": "@from",
+    "attendeeEmail": "@to",
+    "teamsLink": "https://teams.microsoft.com/l/meetup-join/...",
+    "timezone": "America/New_York",
+  },
 }
 ```
 
-#### **OWA Integration Features:**
-- **Native Office 365 Support**: Direct integration with Microsoft Outlook Web Access
-- **Session Management**: Automatic cookie handling and session persistence
-- **Enterprise Security**: Maintains corporate security policies and compliance
-- **Bulk Operations**: Efficient handling of large-scale email campaigns
-- **Rate Limiting**: Respects Exchange Online throttling policies
-- **Auto-cleanup**: Optional sent item deletion for storage management
-
-#### **Setting Up OWA Integration:**
-1. **Obtain Session Cookies**: Login to your Outlook Web Access and extract session cookies
-2. **Configure Account**: Add your corporate email and webmail URL
-3. **Set Limits**: Configure daily and hourly sending limits per your organization's policies
-4. **Test Connection**: Verify connectivity before launching campaigns
-
-## Template System
-
-### HTML Templates
-
-Create rich HTML email templates with dynamic content:
-
-```html
-<!DOCTYPE html>
-<html>
-<head>
-    <meta charset="UTF-8">
-    <title>{SUBJECT}</title>
-    <style>
-        body { font-family: Arial, sans-serif; }
-        .header { background-color: #f0f0f0; padding: 20px; }
-        .content { padding: 20px; }
-        .footer { background-color: #333; color: white; padding: 10px; }
-    </style>
-</head>
-<body>
-    <div class="header">
-        <h1>Welcome {FAKE_FIRST_NAME}!</h1>
-    </div>
-    
-    <div class="content">
-        <p>Dear {FAKE_FIRST_NAME} {FAKE_LAST_NAME},</p>
-        
-        <p>Thank you for your interest in our services. This email was sent on {DATE} at {TIME}.</p>
-        
-        <p>Your unique reference ID is: <strong>{UNIQUE_ID}</strong></p>
-        
-        <p>Company: {FAKE_COMPANY_NAME}</p>
-        <p>Phone: {FAKE_PHONE_NUMBER}</p>
-        <p>Address: {FAKE_ADDRESS}</p>
-        
-        <a href="{PAGE_LINK}" style="background-color: #007cba; color: white; padding: 10px 20px; text-decoration: none; border-radius: 5px;">
-            Visit Our Website
-        </a>
-    </div>
-    
-    <div class="footer">
-        <p>© 2024 Your Company. All rights reserved.</p>
-        <p>Random Number: {RANDOM_NUMBER_5}</p>
-    </div>
-</body>
-</html>
-```
-
-## Tag System
-
-The application includes a powerful tag replacement system with 50+ built-in tags for dynamic content generation.
-
-### Basic Tags
-
-| Tag | Description | Example Output |
-|-----|-------------|----------------|
-| `{EMAIL_ADDRESS}` | Recipient's email address | `john.doe@example.com` |
-| `{UNIQUE_ID}` | Unique identifier | `abc123def456` |
-| `{DATE}` | Current date | `2024-01-15` |
-| `{TIME}` | Current time | `14:30:25` |
-| `{TOMORROW_DATE}` | Tomorrow's date | `2024-01-16` |
-| `{YESTERDAY_DATE}` | Yesterday's date | `2024-01-14` |
-
-### Fake Data Tags
-
-| Tag | Description | Example Output |
-|-----|-------------|----------------|
-| `{FAKE_FIRST_NAME}` | Random first name | `John` |
-| `{FAKE_LAST_NAME}` | Random last name | `Smith` |
-| `{FAKE_FULL_NAME}` | Random full name | `John Smith` |
-| `{FAKE_COMPANY_NAME}` | Random company name | `Tech Solutions Inc` |
-| `{FAKE_EMAIL}` | Random email address | `john.smith@example.com` |
-| `{FAKE_PHONE_NUMBER}` | Random phone number | `+1-555-123-4567` |
-| `{FAKE_ADDRESS}` | Random street address | `123 Main Street` |
-| `{FAKE_CITY}` | Random city name | `New York` |
-| `{FAKE_STATE}` | Random state name | `California` |
-| `{FAKE_ZIP_CODE}` | Random ZIP code | `90210` |
-| `{FAKE_COUNTRY}` | Random country name | `United States` |
-
-### Random Number Tags
-
-| Tag | Description | Example Output |
-|-----|-------------|----------------|
-| `{RANDOM_NUMBER_3}` | 3-digit random number | `847` |
-| `{RANDOM_NUMBER_5}` | 5-digit random number | `92847` |
-| `{RANDOM_NUMBER_8}` | 8-digit random number | `38472951` |
-
-### Special Tags
-
-| Tag | Description | Example Output |
-|-----|-------------|----------------|
-| `{PAGE_LINK}` | Dynamic page link | `https://example.com` |
-| `{REAL_COMPANY_NAME}` | Real company from domain | `Google Inc` |
-
-## Best Practices
-
-### 1. SMTP Security
-- Use environment variables for sensitive credentials
-- Enable two-factor authentication where possible
-- Regularly rotate passwords and API keys
-
-### 2. Rate Limiting
-- Monitor your SMTP provider's rate limits
-- Configure appropriate delays between emails
-- Use multiple SMTP accounts for load balancing
-
-### 3. Content Management
-- Test email templates in multiple clients
-- Use inline CSS for better compatibility
-- Optimize images to keep email size manageable
-
-### 4. Attachment Management
-- Limit attachment size and number
-- Use cloud storage links for large files
-- Encrypt sensitive attachments when necessary
-
-### 5. Logging and Monitoring
-- Enable comprehensive logging for troubleshooting
-- Monitor logs for delivery failures
-- Implement log rotation to manage disk usage
+Time formats: `"now"`, `"+30minutes"`, `"+2hours"`, `"+1week"`, `"+1month"`
 
 ## License
 
-MIT License - Feel free to use this project in your own applications, both personal and commercial.
+Proprietary. A license is required to use this software. Visit [Trovyx](https://trovyx.pro) to obtain a license.
 
 ---
 
-**Made with ❤️ by Razon Team**
+**Razon** by [Trovyx](https://trovyx.pro)