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

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.