📚 email-cli
← Coms Communications Suite ↗Sullux.com ↗

@sullux/coms-email-cli

A standalone, lightweight Unix command-line interface wrapper for @sullux/coms-email. It is designed to pull remote IMAP mailbox records as structured JSON-Lines streams over stdout, and compile and transmit secure multipart SMTP emails from the terminal shell.

Technical Architecture & Unix Philosophy

This tool is 100% decoupled from the Coms Event Lake. It assumes no specific database, storage, or IPC server.

       [ IMAP Mail Server ]               [ SMTP Mail Server ]
                │                                  ▲
                ▼ (fetch --idle)                   │ (send)
     ┌─────────────────────────────────────────────────┐
     │              @sullux/coms-email-cli             │
     └──────────────────────┬──────────────────────────┘
                            │
                            ▼
         stdout (fd 1): [ JSON-Lines Stream ]
         stderr (fd 2): [ Diagnostics & Reconnections ]

Key Stream Properties:

  • Standard Output (stdout / FD 1): Reserved exclusively for structured, newline-delimited JSON messages fetched from the IMAP server. This guarantees that downstream pipeline commands (like jq, custom Python parsers, or databases) never receive log noise.
  • Standard Error (stderr / FD 2): Used for all connection progress, heartbeats, warnings, error dumps, and self-healing reconnection notifications.

Quick Start

1. Fetching Email Backlogs

Pulls all messages after the specified IMAP UID and exits:

coms-email fetch --config /path/to/config.json --last-uid 1450

2. Real-Time Streaming (--idle)

Retrieves any backlog since --last-uid, then enters a persistent IMAP IDLE state. Real-time incoming emails are instantly fetched and pushed to stdout as they arrive:

coms-email fetch --config /path/to/config.json --last-uid 1450 --idle

Manual

The complete reference manual of the CLI. This section is automatically kept in perfect lockstep with the native Unix man coms-email-cli documentation.

<!-- MAN_START -->

NAME

coms-email \- Standalone email command line interface

SYNOPSIS

coms-email [fetch|send] [options]

DESCRIPTION

coms-email is a zero-dependency, local-first UNIX CLI utility designed to bridge secure internet mail servers (SMTP and IMAP) directly with standard POSIX streams.

Following the UNIX design philosophy, the tool operates entirely independently of any centralized database, event store, or message broker. It outputs clean, structured, newline-delimited JSON-Lines directly to stdout (for easy streaming ingestion by tools like jq), and reserves stderr exclusively for logs, heartbeats, and connection progress.

OPTIONS

  • -c, --config path

Path to the JSON configuration file containing server credentials.

  • -u, --last-uid number

The last synchronized IMAP UID. Only mail with a UID greater than this will be fetched. Defaults to 0. (Only applicable to the fetch command).

  • -i, --idle

Enables persistent real-time streaming using IMAP IDLE. After pulling historical backlog, the command keeps the socket open and flushes incoming emails to stdout instantly. Logs and heartbeat indicators are output to stderr. (Only applicable to the fetch command).

  • -t, --to addresses

Comma-separated list of recipient email addresses. Required. (Only applicable to the send command).

  • -cc, --cc addresses

Comma-separated list of Carbon Copy (CC) recipients. (Only applicable to the send command).

  • -bcc, --bcc addresses

Comma-separated list of Blind Carbon Copy (BCC) recipients. (Only applicable to the send command).

  • -s, --subject string

Email subject line. (Only applicable to the send command).

  • -b, --body string

Email plaintext body. If set to -, the plaintext body is read from standard input (stdin). (Only applicable to the send command).

  • -H, --html string

Email HTML formatted body. If set to -, the HTML body is read from standard input (stdin). (Only applicable to the send command).

  • -f, --files paths

Comma-separated paths to local files to attach. The tool reads, base64 encodes, and structures attachments with correct MIME headers automatically. (Only applicable to the send command).

INLINE MEDIA AUTO-DISCOVERY

When compiling an HTML email body (-H, --html), the CLI parses standard image references (<img src="...">) to dynamically discover local file assets.

If an image src references a relative or absolute file path existing on the local file system (rather than a remote http:// or embedded data: URI), the CLI automatically:

  1. Encodes the image file in base64 format.
  2. Generates a content ID (CID) from the filename.
  3. Modifies the HTML src in transit to point to cid:<filename>.
  4. Packages and attaches the asset under the inline multipart/related MIME boundary.

This allows developers to compose and send HTML emails referencing local graphics without manual CID mapping.

CONFIGURATION & ENVIRONMENT

Configuration can be supplied via a JSON file (-c, --config), environment variables, or a hybrid of both. Following the Twelve-Factor App standard, environment variables take absolute precedence over JSON file configurations.

If no configuration file is passed, the CLI can run entirely off environment variables.

Supported environment variables:

  • COMS_EMAIL_CHANNEL_ID (corresponds to channelId)
  • COMS_EMAIL_EMAIL_ADDRESS (corresponds to emailAddress)
  • COMS_EMAIL_IMAP_HOST (corresponds to imap.host)
  • COMS_EMAIL_IMAP_PORT (corresponds to imap.port)
  • COMS_EMAIL_IMAP_USERNAME (corresponds to imap.username)
  • COMS_EMAIL_IMAP_PASSWORD (corresponds to imap.password)
  • COMS_EMAIL_SMTP_HOST (corresponds to smtp.host)
  • COMS_EMAIL_SMTP_PORT (corresponds to smtp.port)
  • COMS_EMAIL_SMTP_USERNAME (corresponds to smtp.username)
  • COMS_EMAIL_SMTP_PASSWORD (corresponds to smtp.password)
  • COMS_EMAIL_IMAP_REJECT_UNAUTHORIZED (corresponds to imap.rejectUnauthorized, set to false or 0 to bypass certificate validations)
  • COMS_EMAIL_SMTP_REJECT_UNAUTHORIZED (corresponds to smtp.rejectUnauthorized, set to false or 0 to bypass certificate validations)

EXAMPLES

Fetch historical inbox backlog after UID 120 using short flags:

coms-email fetch -c ./account.json -u 120

Establish a real-time email pipeline using environment variables instead of a config file:

export COMS_EMAIL_IMAP_HOST="imap.fastmail.com"
export COMS_EMAIL_IMAP_PORT="993"
export COMS_EMAIL_IMAP_USERNAME="charles@sullux.com"
export COMS_EMAIL_IMAP_PASSWORD="my-app-password"

coms-email fetch -i

Transmit a secure HTML newsletter with inline local images, piping the body from standard input:

cat newsletter.html | coms-email send \
  -c ./account.json \
  -t "Natasha <natasha@sullux.com>" \
  -s "Monthly Digest" \
  -H -

AUTHOR

Written by Charles Sullivan, Sullux LLC. <!-- MAN_END -->