@sullux/coms-email

A pure, zero-dependency, programmatic email engine for Node.js. It features robust, state-machine TLS clients for secure SMTP transmissions and IMAP sync/listening operations alongside a pure recursive MIME compiler.

Architectural Role

@sullux/coms-email contains no binaries and is entirely decoupled from any CLI wrappers or Event Lake storage mechanics. It is designed to be imported directly into other JS/TS applications (like CLI commands, web services, or background daemons) that require robust email protocol capability with zero third-party dependencies.

       [ Client JS Application ]
          │                  │
   (Instantiates)      (Instantiates)
          ▼                  ▼
     [ SMTP Client ]    [ IMAP Client ]

Core Capabilities:

Zero SaaS Intermediaries: Implements standard SMTP and IMAP handshakes using Node's native node:tls capabilities, avoiding heavy packages like nodemailer.
Stateful IMAP IDLE: Houses a resilient, reconnectable socket state machine to enter and monitor IMAP IDLE streams.
Recursive MIME Compiler: Generates clean, RFC-compliant multipart email streams—combining plaintext, HTML, inline visual references (multipart/related), and physical file attachments (multipart/mixed) inside a single pure utility function.

Quick Start

1. Installation

yarn add @sullux/coms-email

2. Composing and Sending via SMTP

const { Smtp } = require('@sullux/coms-email')

const smtp = Smtp({
  host: 'smtp.fastmail.com',
  port: 465,
  username: 'charles@sullux.com',
  password: 'my-app-password',
})

async function sendMail() {
  const receipt = await smtp.send({
    from: 'charles@sullux.com',
    to: 'natasha@sullux.com',
    cc: 'support@sullux.com',
    subject: 'Status Report',
    text: 'Hello world',
    html: '<h3>Hello world</h3>',
  })
  console.log('Transmitted! Message-ID:', receipt.messageId)
}
sendMail()

API Reference

`Imap(config)`

Provides state-machine connectivity to secure IMAP servers.

sync({ folder = 'INBOX', lastUid = 0 }): Queries, fetches, unfolds, and structures headers and bodies of all messages with a UID greater than lastUid. Returns Promise<Array<Message>>.
listen({ onNewMail, folder = 'INBOX' }): Opens a persistent socket connection and registers IMAP IDLE. Whenever a new email arrives, onNewMail() is called. Handles internal heartbeats and self-healing reconnections. Returns { close() }.

`Smtp(config)`

A secure SMTP client.

send(email): Sequentially transmits envelope headers (RCPT TO for To, CC, and BCC lists) to ensure BCC stealth, builds the MIME payload, and pipes it through the TLS socket. Returns Promise<{ messageId }>.

`compiledMimeMessage(options)`

A pure function that compiles a standardized JS email object into a raw RFC-compliant MIME string.

const { compiledMimeMessage } = require('@sullux/coms-email')

const rawMime = compiledMimeMessage({
  from: 'Charles <charles@sullux.com>',
  to: 'Natasha <natasha@sullux.com>',
  subject: 'Docs',
  text: 'Hello',
  files: [{
    fileId: 'doc-1',
    filename: 'statement.pdf',
    mimeType: 'application/pdf',
    disposition: 'attachment',
    base64: '...'
  }]
})