SMTP Headless Engine ⚡️

A zero-dependency, serverless SMTP client designed for Node.js and Next.js.

Most email libraries require you to set up complex backend API routes or use paid 3rd-party transactional services (SendGrid, Mailgun). SMTP Headless Engine connects directly to your mail server (Gmail, Outlook, Zoho) from your code.

🚀 Supported Environments

| Environment | Support | Mode | | --- | --- | --- | | Node.js | ✅ Full | Direct TCP Socket (TLS) | | Next.js (App Dir) | ✅ Full | Zero-Config Server Actions | | React / Vite (SPA) | ❌ No | Requires a Proxy Bridge (See Legacy Docs) |

📦 Installation

npm install smtp-headless-engine

🛠 Usage 1: Next.js (The "Magic" Way)

If you are using Next.js 14+ (App Router), you do not need to create an API route. Just import the Server Action directly into your Client Component. The package handles the client-to-server tunneling automatically.

app/contact/page.jsx

'use client'; 
import { useState } from 'react';
// Import from the special '/next' submodule
import { sendMailServerAction } from 'smtp-headless-engine/next';

export default function ContactForm() {
  const [status, setStatus] = useState('Idle');

  const handleSend = async () => {
    setStatus('Sending...');
    
    // 🪄 This looks like frontend code, but it executes on the server!
    const res = await sendMailServerAction({
        host: "smtp.gmail.com",
        port: 465,
        user: "[email protected]", 
        pass: "your-app-password", 
        to: "[email protected]",
        from: "[email protected]",
        subject: "Next.js Magic",
        body: "Sent without writing a single API route."
    });

    if (res.success) setStatus('✅ Sent!');
    else setStatus('❌ Error: ' + res.error);
  };

  return <button onClick={handleSend}>{status}</button>;
}

Security Tip: In a production app, do not hardcode credentials in the Client Component. Instead, keep user and pass inside the Server Action or use Environment Variables on the server.

🛠 Usage 2: Standard Node.js

For CLI tools, Express backends, or Electron apps.

const { sendMail } = require('smtp-headless-engine');

async function main() {
  const result = await sendMail({
    host: "smtp.gmail.com",
    port: 465,
    user: process.env.MAIL_USER,
    pass: process.env.MAIL_PASS,
    to: "[email protected]",
    from: "[email protected]",
    subject: "Hello from Node",
    body: "Direct TCP connection successful."
  });

  console.log(result);
}

main();

🛡 Features

• Zero Dependencies: No heavy nodemailer bloat.
• Stealth Rate Limiter: Built-in local file ledger limits sending to 100 emails/day to prevent accidents during development.
• Native TLS: Uses Node.js tls module for secure, encrypted communication (Port 465).

⚠️ Important for Gmail Users

You cannot use your regular Gmail password. You must use an App Password:

1. Go to Google Account > Security.
2. Enable 2-Step Verification.
3. Search for App Passwords and generate one.
4. Use that 16-character code as the pass.

License

ISC