☤CaduceusMail 3.7.0

CaduceusMail is a portable Microsoft 365 plus Cloudflare mail operations framework built for agent harnesses. It packages the skill bundle, bootstrap tooling, DNS and transport automation, sender identity controls, and verification flows needed to make one mailbox behave like a full control plane.

Version 3.7.0 separates publishable framework code from machine-local identity state. The repo now ships safe generic defaults, while live mailbox branding, personal names, footer data, and domain maps live in a local override file outside git.

What ships

The repo now includes:

• a root SKILL.md bundle that can be installed into agent harnesses
• a generic sender identity rules template
• Microsoft 365 and Cloudflare bootstrap + doctor tooling
• Exchange, Graph, DNS, and DKIM orchestration scripts
• a small npm package wrapper for skill installation and profile scaffolding
• credential templates, examples, docs, and regression tests

Two surfaces

Use the project in two clean layers:

1. Publishable framework The tracked repo, npm package, docs, templates, and skill bundle stay generic and safe to ship publicly.
2. Machine-local operations profile Names, domains, footer details, and live mailbox inventory belong in ~/.caduceusmail/sender_identity_rules.local.json or another file pointed to by CADUCEUSMAIL_SENDER_IDENTITY_RULES_PATH.

That split keeps public releases reusable while preserving a tuned live operator profile on a specific machine.

npm and skill install

Global install:

npm install -g @lmtlssss/caduceusmail

Initialize a local sender identity profile:

caduceusmail init-profile

Install the packaged skill into Codex:

caduceusmail install-skill --harness codex --force

You can also print the installed package root for custom harness wiring:

caduceusmail skill-path

Local identity customization

The tracked rules file at scripts/sender_identity_rules.json is a generic template.

Customize your live sender behavior in:

~/.caduceusmail/sender_identity_rules.local.json

The runtime resolves sender identity rules in this order:

1. CADUCEUSMAIL_SENDER_IDENTITY_RULES_PATH
2. ~/.caduceusmail/sender_identity_rules.local.json
3. ~/.config/caduceusmail/sender_identity_rules.local.json
4. bundled scripts/sender_identity_rules.json

That means the public package stays generic while your live machine can keep exact brand maps, reply names, footer blocks, and mailbox inventory.

Credentials and bootstrap

Copy the credential templates, fill them in locally, then run the wrapper:

cp credentials/entra.txt.template credentials/entra.txt
cp credentials/cloudflare.txt.template credentials/cloudflare.txt

bash ./scripts/caduceusmail.sh \
  --organization-domain "example.com" \
  --mailbox "[email protected]" \
  --bootstrap-auth-mode device

For headless daily operations after the trust ceremony:

bash ./scripts/caduceusmail.sh \
  --organization-domain "example.com" \
  --mailbox "[email protected]" \
  --skip-m365-bootstrap

Persistence is opt-in. The wrapper does not write secrets to disk unless you explicitly ask it to.

Doctor

Use the doctor to check runtime readiness:

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

Or through the npm bin:

caduceusmail doctor --json

It reports:

• required binaries
• credentials file presence and key coverage
• headless readiness
• skill frontmatter safety
• recommended bootstrap mode for the current host

Deliverability model

CaduceusMail coordinates four planes together:

1. Entra and Graph identity
2. Exchange transport and accepted domains
3. Cloudflare DNS for MX, SPF, DMARC, and DKIM selectors
4. sender identity + footer rendering through the local profile

New lane verification and send preflight now include DKIM, so subdomains are not treated as ready on MX/SPF/DMARC alone.

Agent harness notes

The bundle is shaped for skill-based agent runtimes:

• Codex can load the copied skill folder under ~/.codex/skills/caduceusmail
• OpenClaw can load the root SKILL.md directly and inject env through skills.entries.<skill>.env
• other harnesses can copy the same packaged bundle to any custom skill path

See:

• docs/openclaw.md
• docs/codex.md
• examples/openclaw.config.json5

Security

Do not track:

• live credentials
• local sender identity override files
• mailbox inventory snapshots
• generated intel artifacts

The repo intentionally keeps credential templates in git and real secrets out of git.

Testing

Smoke test:

bash ./scripts/caduceusmail-sandbox-smoke.sh

Full test suite:

PYTHONPATH=src python3 -m pytest -q

npm payload dry run:

npm pack --dry-run

Publishing

The repo now includes .github/workflows/npm-publish.yml for push-driven GitHub-to-npm publishing from main. It expects an NPM_TOKEN repository secret, runs the test/package checks on each push, and only publishes when the package.json version is not already present on npm.

License

MIT.