{"_id":"@codecell-germany/e-mail-agent-skill","_rev":"5-47fe276169c2607d921e45206952ea5e","name":"@codecell-germany/e-mail-agent-skill","dist-tags":{"latest":"0.1.4"},"versions":{"0.1.0":{"name":"@codecell-germany/e-mail-agent-skill","version":"0.1.0","keywords":["email","microsoft-graph","outlook","agent","codex-skill","cli"],"author":{"name":"Nikolas Gottschol"},"license":"MIT","_id":"@codecell-germany/e-mail-agent-skill@0.1.0","maintainers":[{"name":"codecell-germany","email":"admin@codecell.de"}],"homepage":"https://github.com/codecell-germany/e-mail-agent-skill#readme","bugs":{"url":"https://github.com/codecell-germany/e-mail-agent-skill/issues"},"bin":{"e-mail-agent-cli":"dist/index.js","e-mail-agent-skill":"dist/installer.js"},"dist":{"shasum":"daa2e0673277ad265fcaf54d5e6a3222bcfda7cb","tarball":"https://registry.npmjs.org/@codecell-germany/e-mail-agent-skill/-/e-mail-agent-skill-0.1.0.tgz","fileCount":36,"integrity":"sha512-4TASmtkP6UJjxvrK4j6e4ldcljZbauI/Qg0g4UcShF8/Drd1aGZl1yufOwQ+CK7ovT3qU59FNliUIF4oBNOffw==","signatures":[{"sig":"MEQCICer1tPOyGPRNe7NNjY6gvrgBPIWz4reQjezTBGpZNF1AiB+p5p3dzFgFmGE5v1kpZFm2OpNGV503Rg/hgZJyrHRJg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":111090},"engines":{"node":">=20"},"gitHead":"2ae9be848a1397e84a256770203af2cae1d4e552","private":false,"scripts":{"test":"vitest run tests/unit","build":"npm run clean && tsc -p tsconfig.json && node scripts/ensure-executable.js","clean":"node scripts/clean.js","prepack":"npm run build && npm run test","test:all":"vitest run","test:unit":"vitest run tests/unit","typecheck":"tsc --noEmit","test:integration":"vitest run tests/integration"},"_npmUser":{"name":"codecell-germany","email":"admin@codecell.de"},"repository":{"url":"git+https://github.com/codecell-germany/e-mail-agent-skill.git","type":"git"},"_npmVersion":"11.12.1","description":"Agent-focused Microsoft-first email CLI in TypeScript","directories":{},"_nodeVersion":"25.9.0","dependencies":{"commander":"^14.0.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.0.7","typescript":"^5.9.2","@types/node":"^25.2.3"},"_npmOperationalInternal":{"tmp":"tmp/e-mail-agent-skill_0.1.0_1775813259218_0.48590079207784265","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@codecell-germany/e-mail-agent-skill","version":"0.1.1","keywords":["email","microsoft-graph","outlook","agent","codex-skill","cli"],"author":{"name":"Nikolas Gottschol"},"license":"MIT","_id":"@codecell-germany/e-mail-agent-skill@0.1.1","maintainers":[{"name":"codecell-germany","email":"admin@codecell.de"}],"homepage":"https://github.com/codecell-germany/e-mail-agent-skill#readme","bugs":{"url":"https://github.com/codecell-germany/e-mail-agent-skill/issues"},"bin":{"e-mail-agent-cli":"dist/index.js","e-mail-agent-skill":"dist/installer.js"},"dist":{"shasum":"94ca0d8bdc05f8d281d4e8c6cbb4f48136c6e472","tarball":"https://registry.npmjs.org/@codecell-germany/e-mail-agent-skill/-/e-mail-agent-skill-0.1.1.tgz","fileCount":37,"integrity":"sha512-eXFL7oc6EACeNPNJpl2C/rgzGkiDiZ8ziyCQfE2IDAuilxI0sfvmKE6qsxLCpV5oU9sCoTheozUbL/L9Lhx45Q==","signatures":[{"sig":"MEUCIQDSGdEGCau1uSHwgfC15pMIy6/eR1znmlW4icCwt4n+rgIgeeeyj2YofmFcEyYEkUG0gBRdMp/Ypt2FO2iVRblGZuA=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":114046},"engines":{"node":">=20"},"gitHead":"506f07aee1ec1114cd6c54030a824662a8d3abab","private":false,"scripts":{"test":"vitest run tests/unit","build":"npm run clean && tsc -p tsconfig.json && node scripts/ensure-executable.js","clean":"node scripts/clean.js","prepack":"npm run build && npm run test","test:all":"vitest run","test:unit":"vitest run tests/unit","typecheck":"tsc --noEmit","test:integration":"vitest run tests/integration"},"_npmUser":{"name":"codecell-germany","email":"admin@codecell.de"},"repository":{"url":"git+https://github.com/codecell-germany/e-mail-agent-skill.git","type":"git"},"_npmVersion":"11.12.1","description":"Agent-focused Microsoft-first email CLI in TypeScript","directories":{},"_nodeVersion":"25.9.0","dependencies":{"commander":"^14.0.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.0.7","typescript":"^5.9.2","@types/node":"^25.2.3"},"_npmOperationalInternal":{"tmp":"tmp/e-mail-agent-skill_0.1.1_1775814326478_0.9276701981848166","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@codecell-germany/e-mail-agent-skill","version":"0.1.2","keywords":["email","microsoft-graph","outlook","agent","codex-skill","cli"],"author":{"name":"Nikolas Gottschol"},"license":"MIT","_id":"@codecell-germany/e-mail-agent-skill@0.1.2","maintainers":[{"name":"codecell-germany","email":"admin@codecell.de"}],"homepage":"https://github.com/codecell-germany/e-mail-agent-skill#readme","bugs":{"url":"https://github.com/codecell-germany/e-mail-agent-skill/issues"},"bin":{"e-mail-agent-cli":"dist/index.js","e-mail-agent-skill":"dist/installer.js"},"dist":{"shasum":"8ceb022b0c2b728d901f81e5e9596d9baa9d0e8e","tarball":"https://registry.npmjs.org/@codecell-germany/e-mail-agent-skill/-/e-mail-agent-skill-0.1.2.tgz","fileCount":38,"integrity":"sha512-EpMxFP4buUCiHMANm7FIHxRqcySZOXG8rtaVgSeEokZ1AAsbGBz8Cv6oBQXUdXbCe45IwisDz0uM7ZQRdlMtfw==","signatures":[{"sig":"MEQCIAgi6Wl0c28p+ZqKK4E+6gfcdU0c5XfqlJQmGYnXpL9jAiBsW4tMEGBZjKRY6O+JRu9TGfSFfrk4hDpRDDF8w1xI6g==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":123998},"engines":{"node":">=20"},"gitHead":"aadd2be46ca708e3b111d91de4787c252e69c2c1","private":false,"scripts":{"test":"vitest run tests/unit","build":"npm run clean && tsc -p tsconfig.json && node scripts/ensure-executable.js","clean":"node scripts/clean.js","prepack":"npm run build && npm run test","test:all":"vitest run","test:unit":"vitest run tests/unit","typecheck":"tsc --noEmit","test:integration":"vitest run tests/integration"},"_npmUser":{"name":"codecell-germany","email":"admin@codecell.de"},"repository":{"url":"git+https://github.com/codecell-germany/e-mail-agent-skill.git","type":"git"},"_npmVersion":"11.12.1","description":"Agent-focused Microsoft-first email CLI in TypeScript","directories":{},"_nodeVersion":"25.9.0","dependencies":{"commander":"^14.0.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.0.7","typescript":"^5.9.2","@types/node":"^25.2.3"},"_npmOperationalInternal":{"tmp":"tmp/e-mail-agent-skill_0.1.2_1775820649943_0.2698129430968348","host":"s3://npm-registry-packages-npm-production"}},"0.1.3":{"name":"@codecell-germany/e-mail-agent-skill","version":"0.1.3","keywords":["email","microsoft-graph","outlook","agent","codex-skill","cli"],"author":{"name":"Nikolas Gottschol"},"license":"MIT","_id":"@codecell-germany/e-mail-agent-skill@0.1.3","maintainers":[{"name":"codecell-germany","email":"admin@codecell.de"}],"homepage":"https://github.com/codecell-germany/e-mail-agent-skill#readme","bugs":{"url":"https://github.com/codecell-germany/e-mail-agent-skill/issues"},"bin":{"e-mail-agent-cli":"dist/index.js","e-mail-agent-skill":"dist/installer.js"},"dist":{"shasum":"09bf1a9f89ba485a8758b19abf8236af35e50502","tarball":"https://registry.npmjs.org/@codecell-germany/e-mail-agent-skill/-/e-mail-agent-skill-0.1.3.tgz","fileCount":38,"integrity":"sha512-psM0dSrCOCEvEMa2gYslVcfuGA1IqF5BQUERnEW1xVi+3HsMYyyw0Pyj4CJwHqzv+GuH8xSuQMuWsZCj4GaOVg==","signatures":[{"sig":"MEQCIFAzLQ0B5BKZDjg10uPC8I9Zle3wxiAbPnN74ryEbruVAiBQGEVg0g3LaCfxZMVmPCXwRzldtftxXtvIy+kY2TY0jg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":124283},"engines":{"node":">=20"},"gitHead":"22334b2cfa39c85208c7910ca352b6795865128e","private":false,"scripts":{"test":"vitest run tests/unit","build":"npm run clean && tsc -p tsconfig.json && node scripts/ensure-executable.js","clean":"node scripts/clean.js","prepack":"npm run build && npm run test","test:all":"vitest run","test:unit":"vitest run tests/unit","typecheck":"tsc --noEmit","test:integration":"vitest run tests/integration"},"_npmUser":{"name":"codecell-germany","email":"admin@codecell.de"},"repository":{"url":"git+https://github.com/codecell-germany/e-mail-agent-skill.git","type":"git"},"_npmVersion":"11.12.1","description":"Agent-focused Microsoft-first email CLI in TypeScript","directories":{},"_nodeVersion":"25.9.0","dependencies":{"commander":"^14.0.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.0.7","typescript":"^5.9.2","@types/node":"^25.2.3"},"_npmOperationalInternal":{"tmp":"tmp/e-mail-agent-skill_0.1.3_1775820765070_0.3607579629415296","host":"s3://npm-registry-packages-npm-production"}},"0.1.4":{"name":"@codecell-germany/e-mail-agent-skill","version":"0.1.4","private":false,"description":"Agent-focused Microsoft-first email CLI in TypeScript","keywords":["email","microsoft-graph","outlook","agent","codex-skill","cli"],"license":"MIT","author":{"name":"Nikolas Gottschol"},"repository":{"type":"git","url":"git+https://github.com/codecell-germany/e-mail-agent-skill.git"},"homepage":"https://github.com/codecell-germany/e-mail-agent-skill#readme","bugs":{"url":"https://github.com/codecell-germany/e-mail-agent-skill/issues"},"bin":{"e-mail-agent-cli":"dist/index.js","e-mail-agent-skill":"dist/installer.js"},"scripts":{"clean":"node scripts/clean.js","build":"npm run clean && tsc -p tsconfig.json && node scripts/ensure-executable.js","typecheck":"tsc --noEmit","test":"vitest run tests/unit","test:unit":"vitest run tests/unit","test:integration":"vitest run tests/integration","test:all":"vitest run","prepack":"npm run build && npm run test"},"publishConfig":{"access":"public"},"engines":{"node":">=20"},"dependencies":{"commander":"^14.0.1"},"devDependencies":{"@types/node":"^25.2.3","typescript":"^5.9.2","vitest":"^4.0.7"},"gitHead":"46debc540fc0f610dbc8232fd2bd876945b9cc0e","_id":"@codecell-germany/e-mail-agent-skill@0.1.4","_nodeVersion":"25.9.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-PjKZeFRTXM0GSt5pChaWb1qszRDjqyahIcRPSVPo9zr3kG94Su2/ED6+Fehn4T0VVgvKnFL/NtGwYdOJasax4A==","shasum":"2eb0d40eef99c9ad36a4538b84ac56fddf220667","tarball":"https://registry.npmjs.org/@codecell-germany/e-mail-agent-skill/-/e-mail-agent-skill-0.1.4.tgz","fileCount":40,"unpackedSize":151984,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIDxi/55HoJB/NsUY4TFWjtn+dnFe33BCSVH3AP0I2HHaAiBSgih05RWTo8guejX3Uoab7dPM0eOpSyzorM1OBIvqIg=="}]},"_npmUser":{"name":"codecell-germany","email":"admin@codecell.de"},"directories":{},"maintainers":[{"name":"codecell-germany","email":"admin@codecell.de"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/e-mail-agent-skill_0.1.4_1775834488519_0.39065634426893237"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-10T09:27:39.144Z","modified":"2026-04-10T15:21:28.821Z","0.1.0":"2026-04-10T09:27:39.388Z","0.1.1":"2026-04-10T09:45:26.626Z","0.1.2":"2026-04-10T11:30:50.086Z","0.1.3":"2026-04-10T11:32:45.233Z","0.1.4":"2026-04-10T15:21:28.711Z"},"bugs":{"url":"https://github.com/codecell-germany/e-mail-agent-skill/issues"},"author":{"name":"Nikolas Gottschol"},"license":"MIT","homepage":"https://github.com/codecell-germany/e-mail-agent-skill#readme","keywords":["email","microsoft-graph","outlook","agent","codex-skill","cli"],"repository":{"type":"git","url":"git+https://github.com/codecell-germany/e-mail-agent-skill.git"},"description":"Agent-focused Microsoft-first email CLI in TypeScript","maintainers":[{"name":"codecell-germany","email":"admin@codecell.de"}],"readme":"# e-mail-agent-skill\n\n---\n\n# English\n\n## Purpose\n\n`e-mail-agent-skill` is a Microsoft-first, provider-ready email automation toolkit for agents.\nIt ships as a real CLI plus a Codex-style skill payload, so an agent can install it, authenticate once, and operate a mailbox through terminal commands instead of a GUI.\n\nThe first implementation target is Microsoft 365 via Microsoft Graph.\nThe internal architecture is intentionally provider-neutral so Gmail and Amazon WorkMail can be added later without redesigning the CLI surface.\n\n## Current scope\n\n- Microsoft 365 / Exchange Online via Microsoft Graph\n- Device-code OAuth for local terminal use\n- Persisted Microsoft session cache with automatic reuse and refresh\n- Search messages server-side\n- Read full messages\n- Create and update drafts\n- Send drafts and direct messages\n- Move and archive messages\n- Mark messages as read\n- Auth status, export, and clear helpers\n- Low-level Graph request escape hatch\n- Installer that copies the skill payload into `~/.codex/skills`\n\n## Installation\n\n### 1. Install the package\n\n```bash\nnpm install -g @codecell-germany/e-mail-agent-skill\n```\n\n### 2. Verify the CLI\n\n```bash\ne-mail-agent-cli --help\ne-mail-agent-skill --help\n```\n\n### 3. Install the skill payload for Codex\n\n```bash\ne-mail-agent-skill install --force\n```\n\n## Quick start\n\nRequirements:\n\n- Node.js `>= 20`\n- Microsoft Entra app registration with a client ID\n- Shell environment variables for the Microsoft provider\n\nIf this is the first Microsoft 365 setup, print the built-in setup guide first:\n\n```bash\ne-mail-agent-cli setup m365 --language en\n```\n\nGerman output is also available:\n\n```bash\ne-mail-agent-cli setup m365 --language de\n```\n\nDetailed click-by-click reference:\n\n- `skills/e-mail-agent-cli/references/agent-onboarding.md`\n- `skills/e-mail-agent-cli/references/overview.md`\n- `skills/e-mail-agent-cli/references/m365-first-run.md`\n\nIf you also need shared or delegated mailboxes, add these delegated Microsoft Graph permissions in the app registration:\n\n- `Mail.ReadWrite.Shared`\n- `Mail.Send.Shared`\n\nThe permission model for shared mailboxes is therefore documented, but the signed-in Microsoft 365 user must still have the matching Exchange mailbox rights.\n\nRequired environment variables:\n\n```bash\nexport EMAIL_AGENT_PROVIDER=\"m365\"\nexport EMAIL_AGENT_M365_CLIENT_ID=\"...\"\nexport EMAIL_AGENT_M365_TENANT=\"organizations\"\n```\n\nBy default, the CLI requests both own-mailbox and shared-mailbox Microsoft Graph scopes so shared mailboxes work without a second redesign.\nIf a tenant wants a narrower token request, it can override the scope manually:\n\n```bash\nexport EMAIL_AGENT_M365_SCOPE=\"openid profile offline_access User.Read Mail.ReadWrite Mail.Send\"\n```\n\nStart the browser login once and persist the session locally:\n\n```bash\ne-mail-agent-cli auth login m365 --persist\n```\n\nIf permissions were added later in the Entra app registration, rerun the login with `--force` so Microsoft can issue a fresh token with the updated consent:\n\n```bash\ne-mail-agent-cli auth login m365 --persist --force\n```\n\nThen validate access:\n\n```bash\ne-mail-agent-cli doctor --provider m365 --json\ne-mail-agent-cli folders list --provider m365 --json\ne-mail-agent-cli doctor --provider m365 --mailbox admin@codecell.de --json\n```\n\nNormal mailbox commands automatically reuse the persisted session.\nNo new device-code flow should be needed for every command.\n\nOnly if you explicitly need shell exports for another process, export them from the existing persisted session:\n\n```bash\ne-mail-agent-cli auth export m365 --write-env-file ~/.config/e-mail-agent-cli/m365.env\nsource ~/.config/e-mail-agent-cli/m365.env\n```\n\nIf a fresh agent is using this skill, the correct first-run order is:\n\n1. `e-mail-agent-cli --help`\n2. `e-mail-agent-cli doctor --provider m365 --json`\n3. if setup is incomplete, print `e-mail-agent-cli setup m365 --language en|de`\n4. collect only:\n   - `EMAIL_AGENT_M365_CLIENT_ID`\n   - `EMAIL_AGENT_M365_TENANT`\n5. never ask for:\n   - client secret\n   - access token\n   - refresh token\n6. run browser OAuth:\n   - `e-mail-agent-cli auth login m365 --persist`\n7. present the Microsoft login URL and code to the user\n8. rerun `doctor`\n9. only then start mailbox operations\n\nFor an already configured machine, the agent should prefer:\n\n```bash\ne-mail-agent-cli auth status m365 --json\ne-mail-agent-cli doctor --provider m365 --json\n```\n\nIf a valid persisted session exists, the agent should continue directly to mailbox commands instead of triggering a fresh login.\n\n## Example commands\n\n### Search\n\n```bash\ne-mail-agent-cli mail search \\\n  --provider m365 \\\n  --query \"invoice\" \\\n  --limit 25 \\\n  --body-format text \\\n  --json\n```\n\n### Read a message\n\n```bash\ne-mail-agent-cli mail show \\\n  --provider m365 \\\n  --id \"<message-id>\" \\\n  --body-format text \\\n  --json\n```\n\n### Read from a shared mailbox\n\n```bash\ne-mail-agent-cli mail search \\\n  --provider m365 \\\n  --mailbox admin@codecell.de \\\n  --query \"invoice\" \\\n  --limit 10 \\\n  --body-format text \\\n  --json\n```\n\n### Create a draft\n\n```bash\ne-mail-agent-cli draft create \\\n  --provider m365 \\\n  --to person@example.com \\\n  --subject \"Follow-up\" \\\n  --body-file /absolute/path/to/body.txt \\\n  --body-content-type text \\\n  --json\n```\n\n### Send a draft\n\n```bash\ne-mail-agent-cli draft send \\\n  --provider m365 \\\n  --id \"<draft-id>\" \\\n  --execute \\\n  --confirm-send yes\n```\n\n### Send a direct message\n\n```bash\ne-mail-agent-cli mail send \\\n  --provider m365 \\\n  --to person@example.com \\\n  --subject \"Hello\" \\\n  --body \"Hello from the CLI.\" \\\n  --execute \\\n  --confirm-send yes\n```\n\n### Send from a shared mailbox\n\n```bash\ne-mail-agent-cli mail send \\\n  --provider m365 \\\n  --mailbox admin@codecell.de \\\n  --to person@example.com \\\n  --subject \"Hello\" \\\n  --body \"Hello from the shared mailbox.\" \\\n  --execute \\\n  --confirm-send yes\n```\n\n### Archive a message\n\n```bash\ne-mail-agent-cli mail archive \\\n  --provider m365 \\\n  --id \"<message-id>\" \\\n  --execute \\\n  --json\n```\n\n## Auth and session model\n\nThis project is static-env-first and session-cache-first.\n\nStatic configuration still comes from environment variables:\n\n- `EMAIL_AGENT_PROVIDER`\n- `EMAIL_AGENT_M365_CLIENT_ID`\n- `EMAIL_AGENT_M365_TENANT`\n- optional: `EMAIL_AGENT_M365_SCOPE`\n- optional: `EMAIL_AGENT_M365_API_BASE_URL`\n\nAfter `auth login`, the CLI persists the Microsoft session locally and later commands reuse it automatically.\nOn macOS, the default backend is the Keychain. A file backend can be forced for debugging or non-macOS environments.\n\nUseful auth commands:\n\n```bash\ne-mail-agent-cli auth login m365 --persist\ne-mail-agent-cli auth status m365 --json\ne-mail-agent-cli auth refresh m365 --json\ne-mail-agent-cli auth export m365 --write-env-file ~/.config/e-mail-agent-cli/m365.env\ne-mail-agent-cli auth clear m365 --json\n```\n\nExported shell files include both static Microsoft settings and the current session values:\n\n- `EMAIL_AGENT_M365_CLIENT_ID`\n- `EMAIL_AGENT_M365_TENANT`\n- `EMAIL_AGENT_M365_SCOPE`\n- `EMAIL_AGENT_M365_API_BASE_URL`\n- `EMAIL_AGENT_M365_ACCESS_TOKEN`\n- `EMAIL_AGENT_M365_REFRESH_TOKEN`\n- `EMAIL_AGENT_M365_EXPIRES_AT`\n\nBuilt-in setup guide:\n\n- `e-mail-agent-cli setup m365 --language en`\n- `e-mail-agent-cli setup m365 --language de`\n\n## Privacy and auth notes\n\n- The default auth path does not print tokens to STDOUT. Sensitive exports are only emitted when `--shell bash` or `--write-env-file` is used explicitly.\n- Persisted sessions are local-only. On macOS, the default storage backend is the Keychain.\n- Do not paste token values into prompts, tickets, screenshots, or logs.\n- Shared mailbox access requires both Graph delegated permissions and real Exchange mailbox rights for the signed-in user.\n- The high-level CLI defaults to the signed-in user's mailbox. Shared mailbox access is an explicit opt-in via `--mailbox <address>`.\n- If a tenant does not need shared mailboxes, it can narrow the requested OAuth scope through `EMAIL_AGENT_M365_SCOPE`.\n\n## Project structure\n\n- `src/`: CLI source\n- `skills/e-mail-agent-cli/SKILL.md`: agent instructions\n- `skills/e-mail-agent-cli/references/agent-onboarding.md`: deterministic first-run workflow for agents\n- `skills/e-mail-agent-cli/references/overview.md`: main overview and workflow guide\n- `skills/e-mail-agent-cli/references/m365-first-run.md`: first-run Microsoft 365 setup\n- `knowledge/`: architecture, auth, release, and limitation notes\n\n## Status\n\nThis repository is being rebuilt from a local Outlook cache prototype into a publishable skill-with-CLI project.\nThe old local-file approach is no longer the primary product direction.\n\n## License\n\nMIT\n\nPlease keep the original copyright and license notice when you use or adapt this project.\nIf you build on top of it publicly, crediting Nikolas Gottschol / CodeCell is appreciated.\n\n---\n\n# Deutsch\n\n## Zweck\n\n`e-mail-agent-skill` ist ein Microsoft-first, aber provider-neutral vorbereitetes E-Mail-Automations-Toolkit für Agenten.\nEs besteht aus einem echten CLI plus einer Codex-Skill-Payload, damit ein Agent den Skill installieren, sich einmal authentifizieren und danach ein Postfach direkt über Terminal-Kommandos steuern kann.\n\nDie erste echte Implementierung zielt auf Microsoft 365 über Microsoft Graph.\nDie interne Architektur wird bewusst so gebaut, dass Gmail und Amazon WorkMail später ohne Oberflächenbruch ergänzt werden können.\n\n## Aktueller Fokus\n\n- Microsoft 365 / Exchange Online über Microsoft Graph\n- Device-Code-OAuth für lokale Terminal-Nutzung\n- serverseitige Suche über Nachrichten\n- vollständiges Lesen einzelner Nachrichten\n- Entwürfe anlegen und aktualisieren\n- Entwürfe und Direktnachrichten senden\n- Nachrichten verschieben und archivieren\n- Nachrichten als gelesen markieren\n- Low-Level-Graph-Request als Escape Hatch\n- Installer, der die Skill-Payload nach `~/.codex/skills` kopiert\n\n## Installation\n\n### 1. Paket installieren\n\n```bash\nnpm install -g @codecell-germany/e-mail-agent-skill\n```\n\n### 2. CLI prüfen\n\n```bash\ne-mail-agent-cli --help\ne-mail-agent-skill --help\n```\n\n### 3. Skill-Payload für Codex installieren\n\n```bash\ne-mail-agent-skill install --force\n```\n\n## Schnellstart\n\nVoraussetzungen:\n\n- Node.js `>= 20`\n- Microsoft-Entra-App-Registrierung mit Client-ID\n- Shell-Umgebungsvariablen für den Microsoft-Provider\n\nWenn dies der erste Microsoft-365-Setup ist, gib zuerst die eingebaute Anleitung aus:\n\n```bash\ne-mail-agent-cli setup m365 --language en\n```\n\nDeutsche Ausgabe ist ebenfalls verfügbar:\n\n```bash\ne-mail-agent-cli setup m365 --language de\n```\n\nDetaillierte Klick-für-Klick-Referenz:\n\n- `skills/e-mail-agent-cli/references/m365-first-run.md`\n\nWenn du zusätzlich auf freigegebene oder delegierte Postfächer zugreifen willst, füge in der App-Registrierung außerdem diese delegierten Microsoft-Graph-Berechtigungen hinzu:\n\n- `Mail.ReadWrite.Shared`\n- `Mail.Send.Shared`\n\nDas Berechtigungsmodell für Shared Mailboxes ist damit dokumentiert, zusätzlich muss der angemeldete Microsoft-365-Benutzer aber die passenden Exchange-Rechte auf dieses Postfach haben.\n\nPflichtvariablen:\n\n```bash\nexport EMAIL_AGENT_PROVIDER=\"m365\"\nexport EMAIL_AGENT_M365_CLIENT_ID=\"...\"\nexport EMAIL_AGENT_M365_TENANT=\"organizations\"\n```\n\nStandardmäßig fordert das CLI sowohl Berechtigungen für das eigene Postfach als auch für Shared Mailboxes an, damit freigegebene Postfächer ohne zweiten Umbau funktionieren.\nWenn ein Mandant bewusst einen kleineren Token-Scope möchte, kann er ihn manuell überschreiben:\n\n```bash\nexport EMAIL_AGENT_M365_SCOPE=\"openid profile offline_access User.Read Mail.ReadWrite Mail.Send\"\n```\n\nLogin-Flow starten und die Exporte direkt in die aktuelle Bash-Session übernehmen:\n\n```bash\neval \"$(e-mail-agent-cli auth login m365 --shell bash)\"\n```\n\nWenn später zusätzliche Berechtigungen in der App-Registrierung ergänzt wurden, sollte der Login einmal erneut ausgeführt werden, damit Microsoft einen frischen Token mit dem aktualisierten Consent ausstellt.\n\nDanach Zugriff verifizieren:\n\n```bash\ne-mail-agent-cli doctor --provider m365 --json\ne-mail-agent-cli folders list --provider m365 --json\ne-mail-agent-cli doctor --provider m365 --mailbox admin@codecell.de --json\n```\n\n## Beispiele\n\nSuche:\n\n```bash\ne-mail-agent-cli mail search \\\n  --provider m365 \\\n  --query \"invoice\" \\\n  --limit 25 \\\n  --body-format text \\\n  --json\n```\n\nNachricht lesen:\n\n```bash\ne-mail-agent-cli mail show \\\n  --provider m365 \\\n  --id \"<message-id>\" \\\n  --body-format text \\\n  --json\n```\n\nAus einem Shared Postfach lesen:\n\n```bash\ne-mail-agent-cli mail search \\\n  --provider m365 \\\n  --mailbox admin@codecell.de \\\n  --query \"invoice\" \\\n  --limit 10 \\\n  --body-format text \\\n  --json\n```\n\nEntwurf anlegen:\n\n```bash\ne-mail-agent-cli draft create \\\n  --provider m365 \\\n  --to person@example.com \\\n  --subject \"Follow-up\" \\\n  --body-file /absolute/path/to/body.txt \\\n  --body-content-type text \\\n  --json\n```\n\nEntwurf senden:\n\n```bash\ne-mail-agent-cli draft send \\\n  --provider m365 \\\n  --id \"<draft-id>\" \\\n  --execute \\\n  --confirm-send yes\n```\n\nNachricht archivieren:\n\n```bash\ne-mail-agent-cli mail archive \\\n  --provider m365 \\\n  --id \"<message-id>\" \\\n  --execute \\\n  --json\n```\n\nAus einem Shared Postfach senden:\n\n```bash\ne-mail-agent-cli mail send \\\n  --provider m365 \\\n  --mailbox admin@codecell.de \\\n  --to person@example.com \\\n  --subject \"Hallo\" \\\n  --body \"Hallo aus dem Shared Postfach.\" \\\n  --execute \\\n  --confirm-send yes\n```\n\n## Env-Modell\n\nDieses Projekt ist bewusst Shell-Env-first gebaut.\nTokens liegen nicht in einer versteckten internen Datenbank. Das CLI erzeugt Shell-Exports, die direkt evaluiert oder in eine Datei geschrieben und später gesourct werden können.\n\nTypische Microsoft-Session-Variablen:\n\n- `EMAIL_AGENT_M365_ACCESS_TOKEN`\n- `EMAIL_AGENT_M365_REFRESH_TOKEN`\n- `EMAIL_AGENT_M365_EXPIRES_AT`\n\nEingebaute Setup-Anleitung:\n\n- `e-mail-agent-cli setup m365 --language en`\n- `e-mail-agent-cli setup m365 --language de`\n\n## Datenschutz und Auth-Hinweise\n\n- Tokens liegen absichtlich in Shell-Umgebungsvariablen. Diese Werte sollten niemals in Prompts, Tickets, Screenshots oder Logs kopiert werden.\n- Shared-Mailbox-Zugriff braucht immer zwei Ebenen: Graph-Delegated-Permissions und echte Exchange-Rechte für den angemeldeten Benutzer.\n- Das High-Level-CLI arbeitet standardmäßig auf dem eigenen Postfach. Shared Mailboxes werden bewusst nur über `--mailbox <adresse>` angesprochen.\n- Wenn ein Mandant keine Shared Mailboxes braucht, kann er den angeforderten OAuth-Scope über `EMAIL_AGENT_M365_SCOPE` bewusst verkleinern.\n\n## Projektstruktur\n\n- `src/`: CLI-Quellcode\n- `skills/e-mail-agent-cli/SKILL.md`: Agenten-Instruktionen\n- `skills/e-mail-agent-cli/references/m365-first-run.md`: Microsoft-365-First-Run-Setup\n- `knowledge/`: Architektur-, Auth-, Release- und Limitations-Dokumente\n\n## Status\n\nDieses Repository wird gerade von einem lokalen Outlook-Cache-Prototypen zu einem veröffentlichbaren Skill-mit-CLI-Projekt umgebaut.\nDer alte lokale Dateiansatz ist nicht mehr die primäre Produktlinie.\n\n## Lizenz\n\nMIT\n\nBitte behalte beim Nutzen oder Weiterentwickeln dieses Projekts den ursprünglichen Copyright-\nund Lizenzhinweis bei. Wenn du öffentlich darauf aufbaust, ist eine Nennung von Nikolas\nGottschol / CodeCell erwünscht.\n","readmeFilename":"README.md"}