Skills

e-mail-agent-cli

Installation
SKILL.md

e-mail-agent-cli

When to use

Use this skill when tasks require mailbox access from a local terminal workflow and the preferred interface is a CLI instead of a GUI.

Use it especially when an agent must:

  • authenticate against Microsoft 365 from the terminal,
  • search messages server-side,
  • read message bodies,
  • create and update drafts,
  • send messages safely,
  • archive or move messages without deleting them.

Preconditions

  • Treat e-mail-agent-cli as the product surface.
  • First check whether it is available on PATH:
    • verify: e-mail-agent-cli --help
    • if missing, treat that as "not installed yet"
    • preferred install path: npm install -g @codecell-germany/e-mail-agent-skill
    • install the skill payload only after the CLI itself exists:
      • e-mail-agent-skill install --force
  • Do not bypass the public CLI by probing repo-local dist/, hidden Codex tool folders, or old local shims.
  • Do not use Outlook cache files or local profile parsing as a fallback for this skill.

First-run detection

Run this check before any mailbox workflow:

e-mail-agent-cli auth status m365 --json
e-mail-agent-cli doctor --provider m365 --json

Treat the environment as "not fully set up" if any of these are true:

  • the CLI is missing
  • doctor cannot run
  • env.clientIdPresent is false and sessionCache.clientIdPresent is false
  • authenticated is false
  • sessionCache.available is false and no valid env token exists
  • sessionCache.autoRefreshReady is false when the current access token is expired
  • the user says this is the first Microsoft 365 setup
  • the user wants shared mailbox access that has not been verified yet

If setup is incomplete, switch into onboarding mode immediately. Do not attempt folders list, mail search, mail show, or raw Graph requests first.

Onboarding mode

This is the exact first-run order for a new or partially configured user:

  1. Tell the user setup is not complete yet.
  2. Print the built-in setup guide in the user's preferred language:
    • English: e-mail-agent-cli setup m365 --language en
    • German: e-mail-agent-cli setup m365 --language de
  3. Ask only for the static Microsoft values that may still be missing:
    • EMAIL_AGENT_M365_CLIENT_ID
    • EMAIL_AGENT_M365_TENANT
  4. Never ask for:
    • a client secret
    • an access token
    • a refresh token
  5. Once the user provides client ID and tenant ID, set or echo the static exports:
    • EMAIL_AGENT_PROVIDER=m365
    • EMAIL_AGENT_M365_CLIENT_ID=<client-id>
    • EMAIL_AGENT_M365_TENANT=<tenant-id-or-organizations>
  6. Start browser OAuth:
    • e-mail-agent-cli auth login m365 --persist
  7. The login command prints a Microsoft device-code prompt. The agent must relay the verification URL and the device code to the user explicitly and wait for confirmation before continuing.
  8. After the user confirms browser login, rerun:
    • e-mail-agent-cli doctor --provider m365 --json
  9. Only after doctor shows authenticated: true may the agent continue to mailbox operations.
  10. If the user needs a shared mailbox, verify it explicitly:
    • e-mail-agent-cli doctor --provider m365 --mailbox admin@codecell.de --json
  11. For normal mailbox commands after login, do not rerun the device-code flow again. The CLI reuses the persisted session automatically.
  12. Use auth export only when another shell process explicitly needs env exports:
    • e-mail-agent-cli auth export m365 --write-env-file ~/.config/e-mail-agent-cli/m365.env
  13. If Microsoft permissions changed and the user must re-consent, rerun login with:
    • e-mail-agent-cli auth login m365 --persist --force

Shared mailbox onboarding

If the task involves shared or delegated mailboxes, the agent must confirm both sides of access:

  • Microsoft Graph delegated permissions in the app registration:
    • Mail.ReadWrite.Shared
    • Mail.Send.Shared for sending
  • real Exchange mailbox rights for the signed-in Microsoft 365 user

If doctor --mailbox <address> fails with a permission error, stop and tell the user that shared-mailbox setup is still incomplete. Do not brute-force around that state with raw /users/... requests.

Core workflow

  1. Validate the environment:
  • e-mail-agent-cli auth status m365 --json
  • e-mail-agent-cli doctor --provider m365 --json
  • shared mailbox: e-mail-agent-cli doctor --provider m365 --mailbox admin@codecell.de --json
  1. Inspect folders:
  • e-mail-agent-cli folders list --provider m365 --json
  • shared mailbox: e-mail-agent-cli folders list --provider m365 --mailbox admin@codecell.de --json
  1. Search messages:
  • e-mail-agent-cli mail search --provider m365 --query "invoice" --limit 25 --body-format text --json
  • shared mailbox: e-mail-agent-cli mail search --provider m365 --mailbox admin@codecell.de --query "invoice" --limit 25 --body-format text --json
  1. Read one message:
  • e-mail-agent-cli mail show --provider m365 --id <message-id> --body-format text --json
  • shared mailbox: e-mail-agent-cli mail show --provider m365 --mailbox admin@codecell.de --id <message-id> --body-format text --json
  1. Use drafts for safer outbound workflows:
  • e-mail-agent-cli draft create ...
  • e-mail-agent-cli draft update ...
  • e-mail-agent-cli draft send --id <draft-id> --execute --confirm-send yes
  • shared mailbox drafts: pass --mailbox <address>

Guardrails

  • Read operations are safe by default.
  • Draft creation and update are allowed directly.
  • Sending requires explicit confirmation:
    • --execute --confirm-send yes
  • In first-run situations, onboarding beats productivity:
    • setup guide first
    • static values second
    • browser login third
    • doctor fourth
    • mailbox commands only after that
  • --mailbox is the preferred shared-mailbox switch. Prefer it over raw /users/... Graph paths.
  • Tokens can be exported into shell env files when explicitly requested. Never paste token values into issue trackers, chats, or agent prompts.
  • Normal CLI usage should rely on the persisted local session. Do not insist on eval "$( ... )" for every command.
  • auth login persists the session by default. auth export is the explicit bridge into shell env files.
  • Never ask the user for a client secret in the current Microsoft 365 CLI flow.
  • Keep permissions narrow when possible. If a tenant does not need shared mailboxes, it can override EMAIL_AGENT_M365_SCOPE with a narrower value.
  • Move, archive, and mark-read operations require:
    • --execute
  • Delete is intentionally not exposed in the first release.
  • Prefer high-level commands over raw Graph requests.
  • Use graph request only for diagnostics or unsupported edge cases.

References

  • Agent onboarding runbook: references/agent-onboarding.md
  • Main overview: references/overview.md
  • Command cheat sheet: references/command-cheatsheet.md
  • First-run Microsoft 365 setup: references/m365-first-run.md
  • Architecture: knowledge/ARCHITECTURE.md
  • Auth notes: knowledge/MICROSOFT_GRAPH_AUTH.md
  • Capability notes: knowledge/MICROSOFT_GRAPH_CAPABILITIES.md
Installs
1
Repository
codecell-german…nt-skill
First Seen
Apr 11, 2026