caduseusmail

☤CaduceusMail 4.2.1

Inbox-reliability optimization engine: automates sender trust hardening, identity rotation, and scale-ready outreach/support flows designed to keep your mail out of junk.

☤CaduceusMail lets your OpenClaw automate an enterprise-level communications stack with one domain/mailbox combo.

What it does

• Bootstraps a Microsoft 365 + Exchange + Cloudflare mail stack from a terminal session.
• Provisions, verifies, retires, and audits alias-based mail lanes.
• Runs an environment doctor that checks commands, credentials, filesystem permissions, and bootstrap mode.
• Ships secure-by-default helpers that write state and result artifacts with owner-only permissions.
• Includes both source-level Node wrappers and shell/Python operational scripts.

Repository layout

src/        Node CLI entrypoints and thin runtime wrappers
scripts/    Operational bash + Python tooling
credentials/ Strict credential templates

Key entrypoints:

• scripts/install.sh: one-line installer for local operator use
• scripts/caduceusmail.sh: stack bootstrap and orchestration entrypoint
• scripts/caduceusmail-doctor.py: readiness diagnostics
• scripts/email_alias_fabric_ops.py: alias fabric operations
• scripts/send_mail_graph.py: Graph sendMail helper
• src/cli.ts: packaged Node CLI wrapper

Requirements

For live operations:

• bash
• python3
• jq
• pwsh for full Microsoft 365 bootstrap

For source builds and tests:

• Node.js 18+
• npm

If pwsh is unavailable, the bootstrap flow still supports --simulate-bootstrap for CI and dry-run validation.

Install

Option 1: one-line installer

curl -fsSL https://raw.githubusercontent.com/lmtlssss/caduceusmail/main/scripts/install.sh | bash

This installs the repo into ~/.local/share/caduceusmail and creates:

• ~/.local/bin/caduseusmail
• ~/.local/bin/caduceusmail
• ~/.local/bin/caduceusmail-doctor

The preferred command is caduseusmail. The legacy alias caduceusmail still works. If you want the subcommand-style Node CLI shown later in this README, build the project from source with npm run build.

If ~/.local/bin is not on your PATH yet:

export PATH="$HOME/.local/bin:$PATH"

Option 2: run from source

git clone https://github.com/lmtlssss/caduceusmail.git
cd caduceusmail
npm install
npm run build

After the build:

node dist/cli.js help

Credentials and state

CaduceusMail reads strict credential files from credentials/ by default. The first non-empty line must be:

CADUCEUSMAIL_CREDENTIALS_V1

Example credentials/entra.txt:

CADUCEUSMAIL_CREDENTIALS_V1
ENTRA_TENANT_ID=<your-entra-tenant-id>
ENTRA_CLIENT_ID=<your-entra-app-client-id>
EXCHANGE_DEFAULT_MAILBOX=<[e-mail]>
ENTRA_CLIENT_SECRET=<entra-client-secret>
EXCHANGE_ORGANIZATION=<tenant-primary.onmicrosoft.com>
ORGANIZATION_DOMAIN=<your-root-domain>

Example credentials/cloudflare.txt:

CADUCEUSMAIL_CREDENTIALS_V1
CLOUDFLARE_API_TOKEN=<cloudflare-api-token>
CLOUDFLARE_ZONE_ID=<cloudflare-zone-id>

Runtime state defaults to:

• ~/.caduceusmail/.env
• ~/.caduceusmail/intel/

The tooling attempts to keep these owner-only (600 files, 700 directories).

Quick start

1. Run diagnostics

From a source checkout:

python3 scripts/caduceusmail-doctor.py --json --base-dir .

From an installed environment:

caduceusmail-doctor --json

2. Bootstrap the stack

bash scripts/caduceusmail.sh \
  --organization-domain example.com \
  --mailbox [e-mail] \
  --bootstrap-auth-mode device

Useful bootstrap flags:

• --dry-run to audit without mutation
• --simulate-bootstrap for CI or sandbox validation
• --skip-m365-bootstrap to skip PowerShell auth/bootstrap
• --persist-env to save non-secret runtime values
• --persist-secrets to save secrets as well

If you used the one-line installer, the equivalent command is:

caduseusmail \
  --organization-domain example.com \
  --mailbox [e-mail] \
  --bootstrap-auth-mode device

3. Provision a mail lane

python3 scripts/email_alias_fabric_ops.py provision-lane \
  --mailbox [e-mail] \
  --local support \
  --domain example.com \
  --ttl 300

Or through the packaged CLI:

node dist/cli.js provision-lane \
  --mailbox [e-mail] \
  --local support \
  --domain example.com

4. Verify or retire a lane

node dist/cli.js verify-lane \
  --mailbox [e-mail] \
  --alias-email [e-mail] \
  --domain example.com

node dist/cli.js retire-lane \
  --mailbox [e-mail] \
  --alias-email [e-mail] \
  --dry-run

5. Send mail through Graph

node dist/cli.js send \
  --from [e-mail] \
  --mailbox [e-mail] \
  --to [e-mail] \
  --subject "Test" \
  --body "Hello from CaduceusMail" \
  --dry-run

Commands

After npm run build, the Node CLI at node dist/cli.js exposes:

• doctor: run readiness diagnostics
• bootstrap: run the bootstrap script
• provision-lane: create a new alias lane and optional DNS records
• verify-lane: verify an existing lane
• retire-lane: remove a lane, with optional fallback mailbox handling
• awareness: list current awareness data for domains and mailbox state
• control-json: execute one or more operations from JSON
• send: send mail through Microsoft Graph
• self-test: run the fabric self-test

Dashboard and native mail lanes

The hosted shell at https://caduseus.pro is only a control surface. Mail stays on the operator machine running caduseusmail dashboard or caduseusmail codex, and the browser talks straight to that local or tunneled gateway with header-token auth.

Typical admin flow:

npm install -g caduseusmail
caduseusmail codex
caduseusmail token

Then:

• open https://caduseus.pro
• paste the local gateway URL and owner token from the terminal
• sign into Microsoft 365 once in the browser
• create alias-scoped shared logins from the dashboard

Each shared login gets:

• a pseudo login like [e-mail]
• a rotated password/token for native mail clients
• POP3 inbox access for that alias lane
• SMTP submission locked to that alias sender

The owner keeps the full terminal surface. Shared logins only see their scoped inbox plus the optional chat-style host session when the owner enables it.

If you already have older docs or wrappers, caduceusmail still works as a compatibility alias.

• smoke: run the sandbox smoke test
• version
• help

JSON control example

control-json accepts either one object or a list of objects:

node dist/cli.js control-json --dry-run --ops-json '[
  {"action":"stack.audit","domain":"example.com","mailbox":"[e-mail]"},
  {"action":"stack.optimize","domain":"example.com","mailbox":"[e-mail]"}
]'

Development

Install dependencies and build:

npm install
npm run build

Run tests:

npm test

Run the sandbox smoke test:

bash scripts/caduceusmail-sandbox-smoke.sh

Notes

• The repo mixes Node wrappers with bash/Python operational code by design. The Node CLI forwards commands into the bundled scripts.
• The current source version is 4.2.1, as declared in VERSION, src/version.ts, and scripts/caduceusmail/version.py.
• doctor will recommend --bootstrap-auth-mode device automatically in headless, SSH, CI, and sandbox-like environments.

License

MIT. See LICENSE.