Skip to content

codecell-germany/e-mail-agent-skill

BranchesTags

Repository files navigation

e-mail-agent-skill

English

Purpose

e-mail-agent-skill is a Microsoft-first, provider-ready email automation toolkit for agents. It 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.

The first implementation target is Microsoft 365 via Microsoft Graph. The internal architecture is intentionally provider-neutral so Gmail and Amazon WorkMail can be added later without redesigning the CLI surface.

Current scope

  • Microsoft 365 / Exchange Online via Microsoft Graph
  • Device-code OAuth for local terminal use
  • Persisted Microsoft session cache with automatic reuse and refresh
  • Search messages server-side
  • Read full messages
  • Create and update drafts
  • Send drafts and direct messages
  • Move and archive messages
  • Mark messages as read
  • Auth status, export, and clear helpers
  • Low-level Graph request escape hatch
  • Installer that copies the skill payload into ~/.codex/skills

Installation

1. Install the package

npm install -g @codecell-germany/e-mail-agent-skill

2. Verify the CLI

e-mail-agent-cli --help
e-mail-agent-skill --help

3. Install the skill payload for Codex

e-mail-agent-skill install --force

Quick start

Requirements:

  • Node.js >= 20
  • Microsoft Entra app registration with a client ID
  • Shell environment variables for the Microsoft provider

If this is the first Microsoft 365 setup, print the built-in setup guide first:

e-mail-agent-cli setup m365 --language en

German output is also available:

e-mail-agent-cli setup m365 --language de

Detailed click-by-click reference:

  • skills/e-mail-agent-cli/references/agent-onboarding.md
  • skills/e-mail-agent-cli/references/overview.md
  • skills/e-mail-agent-cli/references/m365-first-run.md

If you also need shared or delegated mailboxes, add these delegated Microsoft Graph permissions in the app registration:

  • Mail.ReadWrite.Shared
  • Mail.Send.Shared

The permission model for shared mailboxes is therefore documented, but the signed-in Microsoft 365 user must still have the matching Exchange mailbox rights.

Required environment variables:

export EMAIL_AGENT_PROVIDER="m365"
export EMAIL_AGENT_M365_CLIENT_ID="..."
export EMAIL_AGENT_M365_TENANT="organizations"

By default, the CLI requests both own-mailbox and shared-mailbox Microsoft Graph scopes so shared mailboxes work without a second redesign. If a tenant wants a narrower token request, it can override the scope manually:

export EMAIL_AGENT_M365_SCOPE="openid profile offline_access User.Read Mail.ReadWrite Mail.Send"

Start the browser login once and persist the session locally:

e-mail-agent-cli auth login m365 --persist

If 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:

e-mail-agent-cli auth login m365 --persist --force

Then validate access:

e-mail-agent-cli doctor --provider m365 --json
e-mail-agent-cli folders list --provider m365 --json
e-mail-agent-cli doctor --provider m365 --mailbox admin@codecell.de --json

Normal mailbox commands automatically reuse the persisted session. No new device-code flow should be needed for every command.

Only if you explicitly need shell exports for another process, export them from the existing persisted session:

e-mail-agent-cli auth export m365 --write-env-file ~/.config/e-mail-agent-cli/m365.env
source ~/.config/e-mail-agent-cli/m365.env

If a fresh agent is using this skill, the correct first-run order is:

  1. e-mail-agent-cli --help
  2. e-mail-agent-cli doctor --provider m365 --json
  3. if setup is incomplete, print e-mail-agent-cli setup m365 --language en|de
  4. collect only:
    • EMAIL_AGENT_M365_CLIENT_ID
    • EMAIL_AGENT_M365_TENANT
  5. never ask for:
    • client secret
    • access token
    • refresh token
  6. run browser OAuth:
    • e-mail-agent-cli auth login m365 --persist
  7. present the Microsoft login URL and code to the user
  8. rerun doctor
  9. only then start mailbox operations

For an already configured machine, the agent should prefer:

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

If a valid persisted session exists, the agent should continue directly to mailbox commands instead of triggering a fresh login.

Example commands

Search

e-mail-agent-cli mail search \
  --provider m365 \
  --query "invoice" \
  --limit 25 \
  --body-format text \
  --json

Read a message

e-mail-agent-cli mail show \
  --provider m365 \
  --id "<message-id>" \
  --body-format text \
  --json

Read from a shared mailbox

e-mail-agent-cli mail search \
  --provider m365 \
  --mailbox admin@codecell.de \
  --query "invoice" \
  --limit 10 \
  --body-format text \
  --json

Create a draft

e-mail-agent-cli draft create \
  --provider m365 \
  --to person@example.com \
  --subject "Follow-up" \
  --body-file /absolute/path/to/body.txt \
  --body-content-type text \
  --json

Send a draft

e-mail-agent-cli draft send \
  --provider m365 \
  --id "<draft-id>" \
  --execute \
  --confirm-send yes

Send a direct message

e-mail-agent-cli mail send \
  --provider m365 \
  --to person@example.com \
  --subject "Hello" \
  --body "Hello from the CLI." \
  --execute \
  --confirm-send yes

Send from a shared mailbox

e-mail-agent-cli mail send \
  --provider m365 \
  --mailbox admin@codecell.de \
  --to person@example.com \
  --subject "Hello" \
  --body "Hello from the shared mailbox." \
  --execute \
  --confirm-send yes

Archive a message

e-mail-agent-cli mail archive \
  --provider m365 \
  --id "<message-id>" \
  --execute \
  --json

Auth and session model

This project is static-env-first and session-cache-first.

Static configuration still comes from environment variables:

  • EMAIL_AGENT_PROVIDER
  • EMAIL_AGENT_M365_CLIENT_ID
  • EMAIL_AGENT_M365_TENANT
  • optional: EMAIL_AGENT_M365_SCOPE
  • optional: EMAIL_AGENT_M365_API_BASE_URL

After auth login, the CLI persists the Microsoft session locally and later commands reuse it automatically. On macOS, the default backend is the Keychain. A file backend can be forced for debugging or non-macOS environments.

Useful auth commands:

e-mail-agent-cli auth login m365 --persist
e-mail-agent-cli auth status m365 --json
e-mail-agent-cli auth refresh m365 --json
e-mail-agent-cli auth export m365 --write-env-file ~/.config/e-mail-agent-cli/m365.env
e-mail-agent-cli auth clear m365 --json

Exported shell files include both static Microsoft settings and the current session values:

  • EMAIL_AGENT_M365_CLIENT_ID
  • EMAIL_AGENT_M365_TENANT
  • EMAIL_AGENT_M365_SCOPE
  • EMAIL_AGENT_M365_API_BASE_URL
  • EMAIL_AGENT_M365_ACCESS_TOKEN
  • EMAIL_AGENT_M365_REFRESH_TOKEN
  • EMAIL_AGENT_M365_EXPIRES_AT

Built-in setup guide:

  • e-mail-agent-cli setup m365 --language en
  • e-mail-agent-cli setup m365 --language de

Privacy and auth notes

  • 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.
  • Persisted sessions are local-only. On macOS, the default storage backend is the Keychain.
  • Do not paste token values into prompts, tickets, screenshots, or logs.
  • Shared mailbox access requires both Graph delegated permissions and real Exchange mailbox rights for the signed-in user.
  • The high-level CLI defaults to the signed-in user's mailbox. Shared mailbox access is an explicit opt-in via --mailbox <address>.
  • If a tenant does not need shared mailboxes, it can narrow the requested OAuth scope through EMAIL_AGENT_M365_SCOPE.

Project structure

  • src/: CLI source
  • skills/e-mail-agent-cli/SKILL.md: agent instructions
  • skills/e-mail-agent-cli/references/agent-onboarding.md: deterministic first-run workflow for agents
  • skills/e-mail-agent-cli/references/overview.md: main overview and workflow guide
  • skills/e-mail-agent-cli/references/m365-first-run.md: first-run Microsoft 365 setup
  • knowledge/: architecture, auth, release, and limitation notes

Status

This repository is being rebuilt from a local Outlook cache prototype into a publishable skill-with-CLI project. The old local-file approach is no longer the primary product direction.

License

MIT

Please keep the original copyright and license notice when you use or adapt this project. If you build on top of it publicly, crediting Nikolas Gottschol / CodeCell is appreciated.

Deutsch

Zweck

e-mail-agent-skill ist ein Microsoft-first, aber provider-neutral vorbereitetes E-Mail-Automations-Toolkit für Agenten. Es 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.

Die erste echte Implementierung zielt auf Microsoft 365 über Microsoft Graph. Die interne Architektur wird bewusst so gebaut, dass Gmail und Amazon WorkMail später ohne Oberflächenbruch ergänzt werden können.

Aktueller Fokus

  • Microsoft 365 / Exchange Online über Microsoft Graph
  • Device-Code-OAuth für lokale Terminal-Nutzung
  • serverseitige Suche über Nachrichten
  • vollständiges Lesen einzelner Nachrichten
  • Entwürfe anlegen und aktualisieren
  • Entwürfe und Direktnachrichten senden
  • Nachrichten verschieben und archivieren
  • Nachrichten als gelesen markieren
  • Low-Level-Graph-Request als Escape Hatch
  • Installer, der die Skill-Payload nach ~/.codex/skills kopiert

Installation

1. Paket installieren

npm install -g @codecell-germany/e-mail-agent-skill

2. CLI prüfen

e-mail-agent-cli --help
e-mail-agent-skill --help

3. Skill-Payload für Codex installieren

e-mail-agent-skill install --force

Schnellstart

Voraussetzungen:

  • Node.js >= 20
  • Microsoft-Entra-App-Registrierung mit Client-ID
  • Shell-Umgebungsvariablen für den Microsoft-Provider

Wenn dies der erste Microsoft-365-Setup ist, gib zuerst die eingebaute Anleitung aus:

e-mail-agent-cli setup m365 --language en

Deutsche Ausgabe ist ebenfalls verfügbar:

e-mail-agent-cli setup m365 --language de

Detaillierte Klick-für-Klick-Referenz:

  • skills/e-mail-agent-cli/references/m365-first-run.md

Wenn 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:

  • Mail.ReadWrite.Shared
  • Mail.Send.Shared

Das 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.

Pflichtvariablen:

export EMAIL_AGENT_PROVIDER="m365"
export EMAIL_AGENT_M365_CLIENT_ID="..."
export EMAIL_AGENT_M365_TENANT="organizations"

Standardmäß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. Wenn ein Mandant bewusst einen kleineren Token-Scope möchte, kann er ihn manuell überschreiben:

export EMAIL_AGENT_M365_SCOPE="openid profile offline_access User.Read Mail.ReadWrite Mail.Send"

Login-Flow starten und die Exporte direkt in die aktuelle Bash-Session übernehmen:

eval "$(e-mail-agent-cli auth login m365 --shell bash)"

Wenn 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.

Danach Zugriff verifizieren:

e-mail-agent-cli doctor --provider m365 --json
e-mail-agent-cli folders list --provider m365 --json
e-mail-agent-cli doctor --provider m365 --mailbox admin@codecell.de --json

Beispiele

Suche:

e-mail-agent-cli mail search \
  --provider m365 \
  --query "invoice" \
  --limit 25 \
  --body-format text \
  --json

Nachricht lesen:

e-mail-agent-cli mail show \
  --provider m365 \
  --id "<message-id>" \
  --body-format text \
  --json

Aus einem Shared Postfach lesen:

e-mail-agent-cli mail search \
  --provider m365 \
  --mailbox admin@codecell.de \
  --query "invoice" \
  --limit 10 \
  --body-format text \
  --json

Entwurf anlegen:

e-mail-agent-cli draft create \
  --provider m365 \
  --to person@example.com \
  --subject "Follow-up" \
  --body-file /absolute/path/to/body.txt \
  --body-content-type text \
  --json

Entwurf senden:

e-mail-agent-cli draft send \
  --provider m365 \
  --id "<draft-id>" \
  --execute \
  --confirm-send yes

Nachricht archivieren:

e-mail-agent-cli mail archive \
  --provider m365 \
  --id "<message-id>" \
  --execute \
  --json

Aus einem Shared Postfach senden:

e-mail-agent-cli mail send \
  --provider m365 \
  --mailbox admin@codecell.de \
  --to person@example.com \
  --subject "Hallo" \
  --body "Hallo aus dem Shared Postfach." \
  --execute \
  --confirm-send yes

Env-Modell

Dieses Projekt ist bewusst Shell-Env-first gebaut. Tokens 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.

Typische Microsoft-Session-Variablen:

  • EMAIL_AGENT_M365_ACCESS_TOKEN
  • EMAIL_AGENT_M365_REFRESH_TOKEN
  • EMAIL_AGENT_M365_EXPIRES_AT

Eingebaute Setup-Anleitung:

  • e-mail-agent-cli setup m365 --language en
  • e-mail-agent-cli setup m365 --language de

Datenschutz und Auth-Hinweise

  • Tokens liegen absichtlich in Shell-Umgebungsvariablen. Diese Werte sollten niemals in Prompts, Tickets, Screenshots oder Logs kopiert werden.
  • Shared-Mailbox-Zugriff braucht immer zwei Ebenen: Graph-Delegated-Permissions und echte Exchange-Rechte für den angemeldeten Benutzer.
  • Das High-Level-CLI arbeitet standardmäßig auf dem eigenen Postfach. Shared Mailboxes werden bewusst nur über --mailbox <adresse> angesprochen.
  • Wenn ein Mandant keine Shared Mailboxes braucht, kann er den angeforderten OAuth-Scope über EMAIL_AGENT_M365_SCOPE bewusst verkleinern.

Projektstruktur

  • src/: CLI-Quellcode
  • skills/e-mail-agent-cli/SKILL.md: Agenten-Instruktionen
  • skills/e-mail-agent-cli/references/m365-first-run.md: Microsoft-365-First-Run-Setup
  • knowledge/: Architektur-, Auth-, Release- und Limitations-Dokumente

Status

Dieses Repository wird gerade von einem lokalen Outlook-Cache-Prototypen zu einem veröffentlichbaren Skill-mit-CLI-Projekt umgebaut. Der alte lokale Dateiansatz ist nicht mehr die primäre Produktlinie.

Lizenz

MIT

Bitte behalte beim Nutzen oder Weiterentwickeln dieses Projekts den ursprünglichen Copyright- und Lizenzhinweis bei. Wenn du öffentlich darauf aufbaust, ist eine Nennung von Nikolas Gottschol / CodeCell erwünscht.

About

Agent-focused Microsoft-first email CLI with browser OAuth, shared mailbox support, and Codex skill packaging.

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages