Agent Mailbox

Agent Mailbox stellt automatisierten Tests und KI-Agenten kurzlebige E-Mail-Adressen für Anmelde-, Verifizierungs-, Magic-Link- und Passwort-Reset-Abläufe bereit. Es läuft in Ihrem eigenen Cloudflare-Konto und stellt sowohl eine JSON-API als auch einen zustandslosen MCP-Endpunkt bereit.

Jede Adresse hat ein separates zufälliges Mailbox-Token. Nachrichten werden in einem SQLite-gestützten Durable Object gespeichert, Anhänge in R2, und ein Alarm löscht die Mailbox, wenn ihre Time-to-Live abläuft.

Schnellstart

Sie benötigen Node.js 24 oder neuer und ein Cloudflare-Konto mit mindestens einer aktiven Domain. Erstellen und bereitstellen Sie eine frische Kopie mit:

npx create-agent-mailbox@latest

Das Paket create-agent-mailbox wird verfügbar sein, sobald die erste öffentliche Version veröffentlicht ist. Bis dahin klonen Sie dieses Repository und führen Sie Folgendes aus:

pnpm install
pnpm run setup

Die TypeScript-CLI verwendet Wranglers Browser-Login, lädt die aktiven Zonen in Ihrem Konto und empfiehlt dedizierte Hostnamen mail.<domain> und mailbox.<domain>. Sie zeigt einen Bereitstellungsplan, bevor sie Änderungen vornimmt. Nach der Genehmigung konfiguriert sie Email Routing, Subadressierung und Email Sending, führt die Projektprüfungen aus und stellt den Worker bereit. Cloudflare stellt den R2-Bucket, das Durable Object, DNS-Einträge und die eingehende Adressregel aus der Worker-Konfiguration bereit. Das Konto der ausgewählten Zone wird in der generierten Worker-Konfiguration festgelegt, sodass Wrangler Sie nicht erneut zur Auswahl auffordert.

Der Bootstrapper verwendet Corepack, um die exakte pnpm-Lockdatei des Repositorys zu installieren; pnpm muss nicht global installiert werden.

Nach der Bereitstellung kann derselbe Ablauf Codex oder Claude Code verbinden und den gebündelten Skill von Agent Mailbox installieren. Der Client erhält nur den Pfad zu einer lokalen Credential-Brücke; der API-Schlüssel bleibt in der ignorierten Credential-Datei mit Modus 0600. Starten Sie einen bereits geöffneten Client nach dem Verbinden neu.

Jede ausgewählte Zone erhält einen isolierten Worker, der nach der Zone benannt ist, z. B. agent-mailbox-example-com. Sie können Agent Mailbox für mehrere Domains im selben Cloudflare-Konto bereitstellen, ohne dass eine Einrichtung das Routing, den Speicher, die Geheimnisse oder die Konfiguration einer anderen Domain ersetzt. Bewahren Sie jede langlebige Bereitstellung in einem eigenen Projektverzeichnis auf, damit ihre generierte Konfiguration und Anmeldeinformationen verfügbar bleiben; verwenden Sie beispielsweise npx create-agent-mailbox@latest mailbox-example-net für eine zweite Domain.

Wenn Wrangler mehrere Authentifizierungsprofile hat, fragt die Einrichtung, welches verwendet werden soll, bevor sie die Zonen lädt. Ein einzelnes Profil wird automatisch ausgewählt. Für skriptgesteuerte Einrichtung übergeben Sie --profile <name> explizit.

Wrangler-OAuth ist ausreichend; Sie müssen kein separates Cloudflare-API-Token erstellen. DNS-Verfügbarkeitsprüfungen verwenden Cloudflares öffentlichen DNS-Resolver, und Wrangler übernimmt während der Bereitstellung die endgültige Bestätigung bei Konflikten mit benutzerdefinierten Domains.

Die CLI generiert einen Master-API-Schlüssel und sendet ihn über die Standardeingabe an Wrangler, sodass er nie in der Befehlszeile erscheint. Eine lokale Kopie wird in die ignorierte Datei .agent-mailbox.credentials.json mit Modus 0600 geschrieben; dies ist die Anmeldeinformation, die Sie API- oder MCP-Clients geben. Verschieben Sie sie in Ihren Passwortmanager, wenn Sie die lokale Kopie nicht behalten möchten.

Nützliche Einrichtungsmodi:

# Validate local setup code and configuration. No login or Cloudflare changes.
pnpm mailbox deploy --check

# Log in, select a zone, and inspect DNS, but make no changes.
pnpm mailbox deploy --plan

# Scripted use after Wrangler is already authenticated.
pnpm mailbox deploy --zone example.com --yes

pnpm run setup bleibt als Kompatibilitätsalias für pnpm mailbox deploy erhalten.

Bereitstellungen verwalten

Agent Mailbox verwendet Cloudflare als Quelle der Wahrheit, anstatt ein zweites lokales Register zu führen:

# Find every Agent Mailbox Worker accessible to a Wrangler profile.
pnpm run list

# Check Worker bindings, custom domain, Email Routing, MX records, health,
# local credentials, and authenticated MCP connectivity.
pnpm run doctor

# Configure an installed MCP client and copy the portable Agent Skill.
pnpm run connect

# Safely remove one deployment after showing its exact Cloudflare resources.
pnpm run teardown

# Remove this checkout's MCP client connections and optionally its credentials.
pnpm run disconnect

# Empty and delete an R2 bucket retained by an earlier teardown.
pnpm run purge-data

list zeigt, welche Bereitstellung zu den Anmeldeinformationen im aktuellen Checkout passt. doctor verwendet standardmäßig den Worker in wrangler.jsonc; übergeben Sie einen Workernamen, eine E-Mail-Domain oder einen MCP-Hostnamen, um eine andere erkannte Instanz zu überprüfen. Authentifizierte MCP-Prüfungen werden für Instanzen übersprungen, deren API-Schlüssel nicht lokal verfügbar ist.

Für die nicht-interaktive Client-Einrichtung wählen Sie einen oder mehrere Clients explizit aus:

pnpm run connect --client codex --yes
pnpm run connect --client codex --client claude --yes

Der gebündelte Skill wird in das Benutzer-Skill-Verzeichnis des ausgewählten Clients installiert. Verwenden Sie --no-skill, wenn Sie nur die MCP-Verbindung möchten. Vorhandene Client-Verbindungen oder Skill-Verzeichnisse mit anderen Inhalten bleiben unverändert.

Eine Bereitstellung entfernen

teardown wählt eine erkannte Instanz aus und verlangt ihren vollständigen Workernamen als Bestätigung. Es entfernt nur die genaue eingehende Email-Routing-Regel dieses Workers, die benutzerdefinierte Domain, den Worker und den Durable-Object-Namespace. Gemeinsame DNS-Einstellungen für Email Routing auf Zonenebene, Subadressierung, Email Sending und andere Bereitstellungen von Agent Mailbox bleiben unverändert.

# Inspect the exact removal plan without changing Cloudflare.
pnpm run teardown -- agent-mailbox-example-com --dry-run

# Remove the Worker while retaining its R2 attachment bucket.
pnpm run teardown -- agent-mailbox-example-com

# Irreversibly empty and delete the attachment bucket as well.
pnpm run teardown -- agent-mailbox-example-com --purge-data

Die Operation ist so geordnet, dass der Worker zuletzt gelöscht wird. Wenn ein früherer Schritt fehlschlägt, führen Sie denselben Befehl erneut aus, um sicher fortzufahren. Für unbeaufsichtigte Nutzung geben Sie die Instanz, das Wrangler-Profil und --yes explizit an.

Wenn teardown Anhänge behält, schreibt es eine ignorierte Bereinigungsquittung mit Modus 0600 in das Projektverzeichnis. Dadurch bleiben das genaue Konto und der Bucket auffindbar, nachdem der Worker entfernt wurde. Löschen Sie sie später mit:

pnpm run purge-data

Verwenden Sie disconnect separat für die lokale Bereinigung. Standardmäßig entfernt es ausgewählte MCP-Verbindungen und behält sowohl Anmeldeinformationen als auch den gemeinsamen Skill. Im interaktiven Modus wird angeboten, passende Anmeldeinformationen zu löschen; bei skriptgesteuerter Nutzung ist --remove-credentials erforderlich. Da der Skill mehreren Bereitstellungen dienen kann, wird er nur mit der expliziten Option --remove-skill gelöscht.

Erneut bereitstellen, aktualisieren und Anmeldeinformationen rotieren

Die erneute Ausführung der Einrichtung für dieselbe Domain ist eine sichere erneute Bereitstellung. Wenn dieses Projekt passende lokale Anmeldeinformationen hat, installiert die Einrichtung denselben Master-API-Schlüssel erneut, anstatt verbundene Clients zu invalidieren. Das Ersetzen des Schlüssels erfordert immer eine explizite Auswahl oder --rotate-credentials.

Um eine Bereitstellung aus einer zukünftigen getaggten Version zu aktualisieren, erstellen Sie die neue Quelle ohne Bereitstellung, kopieren Sie die generierte Konfiguration und die ignorierten Anmeldeinformationen aus dem alten Projekt, überprüfen Sie die Änderungen und führen Sie dann die Einrichtung aus:

npx create-agent-mailbox@X.Y.Z agent-mailbox-next --no-deploy
cp agent-mailbox/wrangler.jsonc agent-mailbox/.agent-mailbox.credentials.json agent-mailbox-next/
cd agent-mailbox-next
corepack pnpm run setup
corepack pnpm run doctor

Behalten Sie das alte Verzeichnis, bis doctor erfolgreich ist. Wrangler behält frühere Workerversionen für ein Rollback. Wenn die lokalen Anmeldeinformationen nicht verfügbar sind, verweigert die Einrichtung die nicht-interaktive Ersetzung, es sei denn, --rotate-credentials wird angegeben.

Sicherheitsmodell

• Ein Master-API-Schlüssel schützt jede API- und MCP-Anfrage.

• Ein separates Mailbox-Token schützt jede erstellte Mailbox.

• Mailboxes laufen automatisch nach höchstens der konfigurierten maximalen TTL ab.

• Eingehende E-Mails an unbekannte oder abgelaufene Adressen werden abgelehnt.

• E-Mail-Inhalte sind nicht vertrauenswürdige Daten. Die Extraktion von Links und Codes ist deterministisch.

• Der ausgehende Versand ist pro Mailbox ratenbegrenzt und nur für Test-E-Mails vorgesehen.

• API-Antworten mit Mailbox-Daten verwenden Cache-Control: no-store.

Setzen Sie keine Bereitstellung ohne einen starken Master-API-Schlüssel ein. Dieses Projekt ist ein selbst gehostetes Testwerkzeug, kein öffentlicher Wegwerf-E-Mail-Dienst.

Anforderungen

• Node.js 24 oder neuer. pnpm 10 wird nur benötigt, wenn Sie aus einem Klon entwickeln.

• Ein Cloudflare-Konto mit einer Domain bei Cloudflare.

• Zugriff auf Cloudflare Email Routing und Email Sending für diese Domain.

Die CLI erfordert dedizierte Subdomains, anstatt eine Apex-Domain zu übernehmen. Agent Mailbox erstellt Adressen wie inbox+purpose-random@mail.example.com. Einige Dienste lehnen +-Aliasse ab oder normalisieren sie; diese Dienste erfordern möglicherweise eine dedizierte Catch-all-Implementierung in einer zukünftigen Version.

Manuelle Bereitstellung

Die Setup-CLI ist der empfohlene Weg. Dies sind die entsprechenden manuellen Schritte.

1. Den Worker konfigurieren

Bearbeiten Sie wrangler.jsonc und ersetzen Sie jeden example.com-Wert:

• name muss für jede Bereitstellung von Agent Mailbox im Cloudflare-Konto eindeutig sein.

• addresses[0] ist die eingehende Basisadresse, normalerweise inbox@<EMAIL_DOMAIN>.

• routes[0].pattern ist der öffentliche API- und MCP-Hostname.

• vars.EMAIL_DOMAIN ist die Domain, die für generierte Adressen verwendet wird.

• vars.MCP_HOSTNAME ist der Hostname, der vom MCP-Transport zugelassen wird.

Wenn Sie Bindungsnamen ändern, führen Sie pnpm exec wrangler types aus und committen Sie die aktualisierte worker-configuration.d.ts.

2. E-Mail-Funktionen auf Domain-Ebene bereitstellen

Öffnen Sie im Cloudflare-Dashboard Compute → Email Service:

1. Empfangsdomain einbinden.

2. Aktivieren Sie die Subadressierung in den Email-Routing-Einstellungen.

3. Binden Sie dieselbe Domain unter Email Sending ein.

Der Wrangler-Eintrag addresses erstellt die eingehende Adressregel, wenn der Worker bereitgestellt wird, aber DNS, Routing auf Zonenebene, Subadressierung und Sendeberechtigung müssen bereits konfiguriert sein.

3. Überprüfen und bereitstellen

pnpm check
pnpm deploy

Wrangler stellt den R2-Bucket, das Durable Object, den benutzerdefinierten Hostnamen und die eingehende Adressregel aus wrangler.jsonc bereit. Dadurch wird die Anwendung in Ihrem Cloudflare-Konto bereitgestellt; es veröffentlicht dieses Git-Repository nicht.

4. Die Bereitstellung schützen

Erstellen Sie einen langen zufälligen Wert in Ihrem Passwortmanager und geben Sie ihn dann in der interaktiven Eingabeaufforderung von Wrangler ein:

pnpm exec wrangler secret put AGENT_API_KEY

Legen Sie diesen Wert niemals in wrangler.jsonc, in einen Shell-Befehl oder in die Versionskontrolle.

5. Die Bereitstellung überprüfen

Überprüfen Sie den öffentlichen Health-Endpunkt:

curl https://mailbox.example.com/health

Ersetzen Sie den Hostnamen durch Ihre konfigurierte Route. Eine erfolgreiche Antwort ist {"ok":true}.

Lokale Entwicklung

pnpm install
cp .dev.vars.example .dev.vars
pnpm dev

Ersetzen Sie das Beispielgeheimnis in .dev.vars, bevor Sie den Worker starten. Lokaler Durable-Object- und R2-Zustand wird unter dem ignorierten Verzeichnis .wrangler gespeichert.

Führen Sie die vollständige Verifizierungssuite aus mit:

pnpm check

JSON-API

Alle Mailbox-Routen erfordern den Master-Schlüssel:

Authorization: Bearer <AGENT_API_KEY>

Mailbox-spezifische Operationen erfordern außerdem das bei der Erstellung zurückgegebene Token:

X-Mailbox-Token: <MAILBOX_TOKEN>

Eine Mailbox erstellen

curl -X POST https://mailbox.example.com/api/mailboxes \
  -H "Authorization: Bearer $AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"purpose":"signup","ttlSeconds":3600}'

Die Antwort enthält address, mailboxToken und expiresAt. Speichern Sie das Mailbox-Token; es kann nicht wiederhergestellt werden.

Auf eine Verifizierungs-E-Mail warten

curl "https://mailbox.example.com/api/mailboxes/$ADDRESS/wait?subject=verify&timeoutSeconds=20" \
  -H "Authorization: Bearer $AGENT_API_KEY" \
  -H "X-Mailbox-Token: $MAILBOX_TOKEN"

Routen:

• POST /api/mailboxes

• GET /api/mailboxes/:address/messages

• GET /api/mailboxes/:address/messages/:id

• GET /api/mailboxes/:address/messages/:id/links

• GET /api/mailboxes/:address/messages/:id/codes

• GET /api/mailboxes/:address/messages/:id/attachments/:index

• GET /api/mailboxes/:address/wait

• POST /api/mailboxes/:address/send

• DELETE /api/mailboxes/:address

• GET /health

Anhangsindizes stammen aus dem attachments-Array, das mit einer vollständigen Nachricht zurückgegeben wird, und sind nullbasiert.

MCP

Der Streamable-HTTP-Endpunkt ist https://<your-hostname>/mcp. Konfigurieren Sie Ihren MCP-Client mit dieser URL und diesem Header:

Authorization: Bearer <AGENT_API_KEY>

Verfügbare Tools:

• create_mailbox

• wait_for_email

• list_emails

• get_email

• get_links

• get_codes

• send_email

• delete_mailbox

Die einfachste Client-Einrichtung ist:

pnpm run connect

Dies unterstützt Codex und Claude Code. Es gibt jeder Bereitstellung einen eindeutigen MCP-Verbindungsnamen, sodass Clients mehrere Domains von Agent Mailbox unterscheiden können.

Optionale Stdio-Brücke

Ältere MCP-Clients können bin/agent-mailbox-mcp verwenden, das mcp-remote aus den Abhängigkeiten dieses Projekts ausführt. Nach der automatisierten Einrichtung liest es den Endpunkt und den Schlüssel aus .agent-mailbox.credentials.json:

bin/agent-mailbox-mcp

Sie können diese generierten Werte mit Umgebungsvariablen überschreiben:

export AGENT_MAILBOX_MCP_URL=https://mailbox.example.com/mcp
export AGENT_MAILBOX_API_KEY='<master-api-key>'
bin/agent-mailbox-mcp

Für grafische Linux-Clients speichern Sie den Schlüssel im Secret Service anstelle einer Umgebungsvariable und konfigurieren Sie diese nicht geheimen Suchattribute:

export AGENT_MAILBOX_MCP_URL=https://mailbox.example.com/mcp
export AGENT_MAILBOX_KEYRING_SERVICE=agent-mailbox
export AGENT_MAILBOX_KEYRING_ACCOUNT=agent-mailbox
bin/agent-mailbox-mcp

Betrieb

• Standard-Mailbox-TTL: ein Tag.

• Maximale Mailbox-TTL: sieben Tage.

• Standard-Ausgangslimit: 20 Nachrichten pro Mailbox pro UTC-Tag.

• Worker-Logs und -Traces sind in wrangler.jsonc aktiviert; passen Sie das Sampling an Ihren erwarteten Datenverkehr und Ihr Budget an.

• Das Löschen oder Ablaufen einer Mailbox löscht auch ihre R2-Anhänge.

Behandeln Sie den Master-API-Schlüssel und jedes Mailbox-Token als Anmeldeinformationen. E-Mail-Inhalte, Header, Links, Codes und Anhänge können persönliche oder sensible Daten enthalten.

Support, Mitwirken und Sicherheit

Öffnen Sie ein GitHub-Issue für reproduzierbare Fehler, Feature-Anfragen und allgemeine Nutzungsfragen. Siehe CONTRIBUTING.md für Entwicklungsrichtlinien und SECURITY.md für die private Meldung von Sicherheitslücken. Geben Sie in einem Issue niemals Anmeldeinformationen, Mailbox-Inhalte oder private Bereitstellungskennungen an.

Lizenz

Agent Mailbox ist unter der MIT-Lizenz verfügbar.