# Razon

Advanced CLI email client with multi-provider support, dynamic templating, and intelligent delivery optimization.

## Installation

```bash
npm install -g @trovyx/razon
```

## Quick Start

```bash
# 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
```

## 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
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
```

### Testing

```bash
razon test                              # Send test emails (default: 5)
razon test 10                           # Send 10 test emails
```

### Asset Caching

```bash
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
```

### Contact Enrichment

```bash
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

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

### Tags

```bash
razon tags                              # Show available template tags
razon tags contacts.csv                 # Show tags from CSV/Excel columns
```

### DKIM

```bash
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
```

### Database & Backups

```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 extension listen                  # Listen for Webmail Bridge OWA/Outlook captures
razon extension download all            # Package Chrome/Firefox Webmail Bridge extensions

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)
```

### Authentication

```bash
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
```

### System

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

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/accounts.jsonc`  | Webmail Bridge accounts                                          |
| `eml/attachments.jsonc` | EML-specific attachment settings                                 |

All config files use JSONC format (JSON with comments).

## Template Tags

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:

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

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.

### Custom Tags from CSV/Excel (Highest Priority)

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}
```

Use `razon tags` to inspect available tags for your recipient file.

### Built-in Tags

**Recipient & Domain**

| 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 |

**Personalization (Fake Data)**

| 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 |

**Dates & Time**

| 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) |

**Random & Unique**

| 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 |

**Encoding**

| 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 |

**Special**

| Tag | Output |
| --- | ------ |
| `{PAGE_LINK}` | Dynamic page link from config |
| `{PDF_PASSWORD}` | Auto-generated password (shared across entire email) |
| `{LOCAL_IMAGE}` | Embedded local image |

## 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)

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

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.

### Pre-caching Assets

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

## Calendar Invites

Attach calendar invites to emails with support for Microsoft Teams, Google Meet, Zoom, and standard ICS format.

Add a `calendar` block in `config/message.jsonc`:

```jsonc
{
  "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",
  },
}
```

Time formats: `"now"`, `"+30minutes"`, `"+2hours"`, `"+1week"`, `"+1month"`

## License

Proprietary. A license is required to use this software.
