nevtanmail

A high-performance Node.js email sending SDK for Nevtan Mail with automatic authentication, HTML and text email delivery, dynamic templating, mailbox management, and CLI utilities.

Features

• Zero Dependencies: 0 runtime dependencies! Built purely on native Node.js 18+ APIs (fetch, FormData, node:dns, node:fs). Installs in under a second.
• Persistent Token Caching (Zero SSO Rate Limits): Automatically caches session tokens to disk (.nevtanmail-tokens.json) with JWT expiration tracking. Eliminates repeated logins and completely avoids SSO 429 Too Many Requests errors. Supports custom stores (Redis, database, memory).
• Automatic Authentication: Sign in seamlessly using .env credentials (NEVTAN_EMAIL + NEVTAN_PASSWORD) or session tokens (NEVTAN_TOKEN).
• Rich HTML & Plain Text: Full support for styled HTML emails, responsive layouts, inline CSS, and plain text fallbacks.
• Dynamic Templating Engine: Variable interpolation ({{name}}, {{order.id}}), conditionals ({{#if condition}}), and HTML escaping.
• Inbox & Email Management: List inbox messages (listInbox()), delete specific emails (deleteMail(id) / deleteMails(ids)), delete all emails in inbox (deleteAllInbox()), and empty trash (emptyTrash()) with optional permanent purging.
• Mailbox Storage & Quota Tracking: Check real-time used storage vs quota (e.g. 0/1 GB), message counts, and health status (OK, WARNING, CRITICAL, FULL).
• Storage Warnings & Notices: Automatic alerts and warnings when approaching or exceeding quota limits (configurable thresholds, e.g. 80% / 95%).
• Mailbox Management: Read and check emails across folders (all, inbox, sent, etc.) and list all domain mailboxes.
• Batch Email Sending: Send bulk messages with concurrency control and configurable delays.
• Attachment Support: Attach files from disk paths, Buffers, strings, and custom content types.
• CLI Utilities & Help: Command-line tool for verifying connections, listing inbox (nevtanmail inbox), deleting emails (nevtanmail delete), checking storage (nevtanmail storage), and sending test messages.
• Automatic Update Notifications: Automatically alerts you when a newer version of the SDK is published to npm.
• Structured Error Logging: Colorized, timestamped error and debug messages with actionable troubleshooting remedies.
• Type-Safe: Complete TypeScript declarations with dual ESM and CommonJS exports.

⚡ Pure HTTP REST API — No Browser / No Chrome Required

Important Note for AI Coding Assistants (ChatGPT, Claude, Cursor, Copilot) & Developers: nevtanmail is a 100% pure HTTP REST client with zero runtime dependencies.

• No Headless Chrome / Puppeteer: Neither verify(), sendMail(), nor any inbox operation launches or needs a browser.
• Direct HTTPS Delivery: All calls dispatch directly to https://mail-api.nevtan.com and https://sso.nevtan.com using native Node.js fetch.
• Serverless & Docker Ready: Deploys seamlessly to AWS Lambda, Vercel, Docker containers, and minimal Linux VPS environments with no Chromium binaries or system display packages needed.

Installation

npm install nevtanmail

Command Line Interface (CLI)

The package includes a built-in CLI for testing and managing your Nevtan Mail account directly from the terminal:

# Display help and available commands
npx nevtanmail help

# Verify account credentials and connectivity
npx nevtanmail verify

# Check real-time mailbox storage usage, quota (0/1 GB), and health
npx nevtanmail storage

# List all mailboxes and quotas in the domain
npx nevtanmail mailboxes

# List messages currently in your inbox
npx nevtanmail inbox

# Delete a specific email by ID (moves to trash)
npx nevtanmail delete 1250413

# Permanently delete specific email(s) by ID (purges from trash)
npx nevtanmail delete 1250413 1250414 --permanent

# Delete all emails in your inbox
npx nevtanmail delete-inbox

# Permanently delete all emails in your inbox
npx nevtanmail delete-inbox --permanent

# Empty the Trash folder
npx nevtanmail empty-trash

# List recent emails from your mailbox folder (all, inbox, sent, trash, etc.)
npx nevtanmail list all

# Send a quick test email
npx nevtanmail send [email protected] --subject="Test" --body="Hello from CLI"

# Diagnose custom domain DNS records (SPF, DKIM, MX)
npx nevtanmail dns yourdomain.com

Quick Start

1. Configure Environment Variables

Create a .env file in the root of your project:

[email protected]
NEVTAN_PASSWORD=your_account_password
NEVTAN_FROM_EMAIL="Your Company <[email protected]>"

(Alternatively, use NEVTAN_TOKEN=your_jwt_token)

2. Send an Email

import { NevtanMail } from 'nevtanmail';
import 'dotenv/config';

// Automatically loads credentials from your .env file
const mailer = new NevtanMail();

async function main() {
  const result = await mailer.sendMail({
    to: '[email protected]',
    subject: 'Welcome to Our Platform',
    html: `
      <div style="font-family: sans-serif; padding: 20px; color: #333;">
        <h2>Welcome!</h2>
        <p>Your account is now active and ready to use.</p>
      </div>
    `,
    text: 'Welcome! Your account is now active and ready to use.',
  });

  console.log('Email sent successfully. Message ID:', result.messageId);
  await mailer.close();
}

main().catch(console.error);

Usage Guide

Programmatic Configuration

Pass credentials directly into the constructor if you are not using environment variables:

const mailer = new NevtanMail({
  email: '[email protected]',
  password: 'your_account_password',
  defaultFrom: 'Company Name <[email protected]>',
  logLevel: 'info', // 'silent' | 'error' | 'warn' | 'info' | 'debug'
});

Sending Rich HTML Emails

The html option supports full CSS styling, buttons, tables, and media:

await mailer.sendMail({
  to: '[email protected]',
  subject: 'Monthly Performance Summary',
  html: `
    <div style="max-width: 600px; margin: auto; font-family: Arial, sans-serif; border: 1px solid #e2e8f0; border-radius: 8px; overflow: hidden;">
      <div style="background-color: #2563eb; color: #ffffff; padding: 24px; text-align: center;">
        <h1 style="margin: 0; font-size: 20px;">Monthly Analytics Report</h1>
      </div>
      <div style="padding: 24px; color: #334155; line-height: 1.5;">
        <p>Here is your activity report for the current billing cycle.</p>
        <div style="text-align: center; margin: 24px 0;">
          <a href="https://yourdomain.com/reports" style="background-color: #2563eb; color: #ffffff; padding: 12px 24px; text-decoration: none; border-radius: 6px; font-weight: bold;">
            View Detailed Report
          </a>
        </div>
      </div>
    </div>
  `,
  text: 'View your monthly analytics report at: https://yourdomain.com/reports',
});

Dynamic Templating

Use sendTemplate() to render dynamic data:

const orderTemplate = `
  <div style="font-family: sans-serif; max-width: 600px; padding: 20px;">
    <h2>Order Confirmation #{{orderId}}</h2>
    <p>Hello <strong>{{customerName}}</strong>,</p>
    <p>We received your payment of <strong>\${{amount}}</strong>.</p>
    
    {{#if isExpress}}
      <p style="color: #059669; font-weight: bold;">Express Delivery: 1-2 business days.</p>
    {{/if}}

    <a href="{{trackingUrl}}" style="background: #0f172a; color: white; padding: 10px 20px; text-decoration: none; border-radius: 4px;">
      Track Order
    </a>
  </div>
`;

await mailer.sendTemplate(
  '[email protected]',
  'Order #{{orderId}} Confirmed',
  orderTemplate,
  {
    customerName: 'Jordan Lee',
    orderId: 'ORD-4491',
    amount: '129.50',
    isExpress: true,
    trackingUrl: 'https://yourdomain.com/track/ORD-4491',
  }
);

Listing & Checking Mailbox Emails

Retrieve messages and check delivery statuses across any folder:

// List all emails
const allMails = await mailer.listMails({ folder: 'all' });
console.log(`Total Emails: ${allMails.total}`);

// Iterate through emails
for (const mail of allMails.emails) {
  console.log(`[${mail.status}] ${mail.subject} -> ${mail.recipientEmail} (${mail.sentAt})`);
}

// Available folder values: 'all' | 'inbox' | 'sent' | 'starred' | 'trash' | 'drafts' | 'spam'
const sentMails = await mailer.listMails({ folder: 'sent' });

Inbox Listing & Email Deletion

Manage, clean, and purge emails from your inbox or trash folder:

// 1. List emails currently in the inbox
const inbox = await mailer.listInbox();
console.log(`Inbox contains ${inbox.total} emails`);

for (const mail of inbox.emails) {
  console.log(`[ID: ${mail.id}] ${mail.subject} from ${mail.senderEmail}`);
}

// 2. Delete a single email by ID (moves to Trash)
await mailer.deleteMail(1250413);

// 3. Permanently purge a single email immediately (bypasses Trash)
await mailer.deleteMail(1250413, { permanent: true });

// 4. Delete multiple specific emails by ID
await mailer.deleteMails([1250413, 1250414], { permanent: false });

// 5. Delete ALL emails currently in the inbox (moves to Trash)
const result = await mailer.deleteAllInbox();
console.log(`Cleaned ${result.deletedCount} email(s) from inbox`);

// 6. Permanently delete ALL emails in the inbox
await mailer.deleteAllInbox({ permanent: true });

// 7. Empty the Trash folder completely
await mailer.emptyTrash();

Persistent Token Caching & Custom Storage

Nevtan's SSO (sso.nevtan.com) limits login attempts to prevent brute-force attacks. If your app signs in repeatedly on every request or script restart, SSO responds with:

{ "type": "about:blank", "title": "Too Many Requests", "status": 429, "detail": "Too many login attempts. Try again later." }

nevtanmail solves this automatically with Zero-Dep Persistent Token Caching:

1. On initial login, the SDK authenticates with SSO and exchanges for the Mail session token (JWT).
2. It decodes the JWT expiration (exp) and saves the token to .nevtanmail-tokens.json.
3. Subsequent script executions or client instances reuse the active token directly — completely bypassing SSO sign-in and eliminating 429 rate limit errors!
4. If a token expires, the SDK automatically refreshes it and updates the store.

1. Automatic Zero-Config File Cache (Default)

// Automatically checks .nevtanmail-tokens.json first
// Reuses the token if valid, bypassing SSO signin!
const mailer = new NevtanMail({
  email: '[email protected]',
  password: 'your_password',
});

2. Custom Token Store (Redis, MongoDB, PostgreSQL, etc.)

You can customize token storage to persist tokens to Redis, a database, or any custom key-value store:

const mailer = new NevtanMail({
  email: '[email protected]',
  password: 'your_password',
  tokenStore: {
    async get(email) {
      // Fetch token data from Redis, DB, or vault
      return await redis.get(`nevtan:token:${email}`);
    },
    async set(email, data) {
      // Persist token data
      await redis.set(`nevtan:token:${email}`, data);
    },
    async delete(email) {
      await redis.del(`nevtan:token:${email}`);
    },
  },
});

3. Custom Callbacks

const mailer = new NevtanMail({
  email: '[email protected]',
  password: 'your_password',
  onTokenUpdate: (tokenData) => {
    console.log('New session token generated! Expires at:', new Date(tokenData.expiresAt));
  },
  loadToken: async (email) => {
    return await myDatabase.loadTokenFor(email);
  },
  saveToken: async (email, data) => {
    await myDatabase.saveTokenFor(email, data);
  },
});

4. Managing Cached Tokens Programmatically

// Retrieve active auth token (loading from cache if available)
const token = await mailer.getAuthToken();

// Export full metadata (token, ssoToken, expiresAt, claims)
const data = await mailer.exportToken();
console.log('Token expires:', new Date(data.expiresAt));

// Force a re-login with SSO and update cache
await mailer.refreshToken();

// Clear the cached token
await mailer.clearTokenCache();

5. Disable Caching (Ephemeral Memory Only)

const mailer = new NevtanMail({
  tokenCache: false, // Disables writing .nevtanmail-tokens.json
});

Mailbox Storage & Quota Management

Track your mailbox's real-time storage usage (e.g. 0/1 GB), message counts, and receive warnings before reaching capacity:

// 1. Fetch current mailbox storage & quota
const storage = await mailer.getStorage();
console.log(`Account: ${storage.email}`);
console.log(`Storage: ${storage.storageDisplay}`); // e.g. "0/1 GB" or "0.10 MB / 1 GB"
console.log(`Used: ${storage.formattedUsed} of ${storage.formattedQuota} (${storage.percentUsed}%)`);
console.log(`Messages: ${storage.messages}`);
console.log(`Status: ${storage.storageLevel}`); // 'OK' | 'WARNING' | 'CRITICAL' | 'FULL'

// 2. Check storage warning notices programmatically
const notice = await mailer.checkStorageNotice({ warnThresholdPercent: 80 });
if (notice.hasWarning) {
  console.warn('Storage Warning:', notice.notice);
}

// 3. List all mailboxes in the account/domain (Admin)
const mailboxes = await mailer.listMailboxes();
for (const mb of mailboxes.mailboxes) {
  console.log(`${mb.fullName} <${mb.email}>: ${mb.quota} MB (${(mb.quota / 1024).toFixed(1)} GB)`);
}

Storage Warning Parameters

You can customize warning thresholds in your client config:

const mailer = new NevtanMail({
  warnOnStorage: true,           // Automatically log notices when storage is high (default: true)
  storageWarnThreshold: 80,      // Warn at 80% usage (default: 80)
  storageCriticalThreshold: 95,  // Critical warning at 95% usage (default: 95)
});

Sending Attachments

Support for both file paths and memory buffers:

await mailer.sendMail({
  to: '[email protected]',
  subject: 'Invoice #INV-2026',
  html: '<p>Please find attached your invoice.</p>',
  attachments: [
    // 1. From local file path
    {
      path: './invoices/INV-2026.pdf',
      filename: 'invoice-2026.pdf',
      contentType: 'application/pdf',
    },
    // 2. From raw text or CSV string
    {
      filename: 'statement.csv',
      content: 'Date,Item,Amount\n2026-10-10,Plan,49.99',
      contentType: 'text/csv',
    },
  ],
});

Batch Sending with Concurrency Control

Send personalized emails to a recipient list without exceeding server limits:

const recipients = [
  { to: '[email protected]', data: { name: 'Alice', code: 'SAVE10' } },
  { to: '[email protected]', data: { name: 'Bob', code: 'SAVE15' } },
  { to: '[email protected]', data: { name: 'Charlie', code: 'SAVE20' } },
];

const batchResult = await mailer.sendBatch(recipients, {
  subject: 'Special Offer for {{name}}',
  template: '<p>Hi {{name}}, use code <strong>{{code}}</strong> for your next order.</p>',
  concurrency: 5,       // Max parallel requests
  delayBetweenMs: 150,  // Milliseconds to pause between chunks
});

console.log(`Success: ${batchResult.sentCount} / ${batchResult.total}`);

Error Handling & Logging

The SDK provides structured error classes and a built-in logger:

import {
  NevtanMail,
  NevtanAuthError,
  NevtanRateLimitError,
  NevtanConnectionError,
  NevtanValidationError,
  NevtanSendError,
} from 'nevtanmail';

try {
  await mailer.sendMail({ ... });
} catch (error) {
  if (error instanceof NevtanAuthError) {
    console.error('Authentication error:', error.message);
    console.error('Remedy:', error.remedy);
  } else if (error instanceof NevtanRateLimitError) {
    console.error('Rate limit exceeded. Retry in:', error.retryAfterSeconds);
  } else if (error instanceof NevtanValidationError) {
    console.error('Validation error:', error.message);
  } else if (error instanceof NevtanSendError) {
    console.error('Delivery failed:', error.message, error.details);
  } else if (error instanceof NevtanConnectionError) {
    console.error('Network error:', error.message);
  }
}

Automatic Update Checker

When using an outdated version of nevtanmail, the SDK displays a notification:

┌──────────────────────────────────────────────────┐
│                                                  │
│             Package Update Available             │
│            nevtanmail: 1.0.5 ➔ 1.1.0             │
│   Run: npm install nevtanmail@latest to update   │
│                                                  │
└──────────────────────────────────────────────────┘

To disable update checking, set checkUpdates: false in configuration or set the environment variable NEVTAN_DISABLE_UPDATE_CHECK=true.

Author

Created and maintained by rdxheree ([email protected]).

License

MIT