Temporäre E-Mail API und MCP-Server für Tests und KI-Agenten

Schnellstart mit curl

Erstelle ein Postfach, warte auf die nächste E-Mail, lies sie und lösche das Postfach. Speichere deinen API-Schlüssel in TEMPGENERATOR_TOKEN und setze ihn nie in eine URL.

Benötigt curl und jq. Das Skript wartet bis zu dreimal je 20 Sekunden, gibt Betreff, Codes, Links und Text jeder Nachricht aus und löscht danach das Postfach.

export TEMPGENERATOR_URL='https://www.tempgenerator.com'
API="$TEMPGENERATOR_URL/developer-api/v1"
AUTH="Authorization: Bearer $TEMPGENERATOR_TOKEN"
INBOX=$(curl --fail-with-body -sS -X POST "$API/inboxes" -H "$AUTH" -H 'Accept: application/json')
ID=$(printf '%s' "$INBOX" | jq -r .id)
echo "Send a test email to $(printf '%s' "$INBOX" | jq -r .address)"
for ATTEMPT in 1 2 3; do
  RESULT=$(curl --fail-with-body -sS "$API/inboxes/$ID/wait?after=0&timeout=20" -H "$AUTH" -H 'Accept: application/json')
  [ "$(printf '%s' "$RESULT" | jq -r .status)" = message ] && break
done
for MESSAGE in $(printf '%s' "$RESULT" | jq -r '.messages[].id'); do
  curl --fail-with-body -sS "$API/inboxes/$ID/messages/$MESSAGE" -H "$AUTH" -H 'Accept: application/json' \
    | jq '{subject, codes, links, text}'
done
curl --fail-with-body -sS -X DELETE "$API/inboxes/$ID" -H "$AUTH"

Die API im Überblick

Basis-URL: https://www.tempgenerator.com/developer-api/v1. Sende Authorization: Bearer <key> mit jeder Anfrage. Antworten sind JSON; Fehler haben die Form {"error": {"code", "message", "retry_after"}}, und Kontingentfehler senden zusätzlich einen Retry-After-Header.

• POST /inboxes Postfach erstellen und Adresse sowie Ablaufzeit erhalten
• GET /inboxes/{id}/wait?after=0&timeout=20 Bis zu 20 Sekunden auf die nächste Nachricht nach einem Cursor warten
• GET /inboxes/{id}/messages?after=0 Bis zu 50 Nachrichten nach einem Cursor auflisten, älteste zuerst
• GET /inboxes/{id}/messages/{message_id} Eine Nachricht lesen: Text, Codes, Links und Anhangsliste
• GET /inboxes/{id}/messages/{message_id}/attachments/{index} Einen Anhang über seinen Index herunterladen
• DELETE /inboxes/{id} Postfach samt Nachrichten sofort löschen

Die Endpunkte zum Auflisten und Warten akzeptieren die optionalen Filter from und subject_contains. Beide prüfen ohne Unterscheidung von Groß- und Kleinschreibung, ob Absender bzw. Betreff den angegebenen Text enthalten.

Beispielantwort: Nachricht lesen

{
    "id": 42,
    "from": "no-reply@app.example",
    "subject": "Your verification code",
    "received_at": "2026-10-03T09:41:07+00:00",
    "text": "Your verification code is 482913.\nOr confirm: https://app.example/verify?token=8f3c",
    "text_truncated": false,
    "codes": [
        "482913"
    ],
    "links": [
        "https://app.example/verify?token=8f3c"
    ],
    "expires_at": "2026-10-03T10:40:12+00:00",
    "attachments": [
        {
            "index": 0,
            "filename": "receipt.pdf",
            "size": 48213
        }
    ],
    "untrusted_content": true
}

Entwickler-Tokens

Sobald deine E-Mail-Adresse bestätigt ist, erstellst du API-Schlüssel unter „Entwicklerzugang“. Ein Schlüssel mit Lese- und Schreibzugriff kann Postfächer erstellen, lesen und löschen; ein Leseschlüssel kann auflisten, warten, lesen und herunterladen. Schlüssel laufen nach 90 Tagen ab, ein Konto kann bis zu 10 aktive Schlüssel haben, und ein Widerruf gilt sofort.

Jeder Schlüssel wird nur einmal angezeigt und ausschließlich als SHA-256-Hash gespeichert. Ein Widerruf löscht die Postfächer des Schlüssels nicht: Die anderen gültigen Schlüssel des Kontos behalten den Zugriff, bis die Postfächer ablaufen oder gelöscht werden.

Ohne sleep() auf die nächste E-Mail warten

GET …/wait hält die Anfrage offen und antwortet, sobald eine Nachricht eintrifft, oder nach dem Timeout (höchstens 20 Sekunden) mit status timeout. Übergib next_cursor aus der vorherigen Antwort als after, damit du keine Nachricht doppelt liest.

Ein Timeout ist kein Zustellfehler: Warte einfach mit demselben Cursor erneut. Pro Postfach läuft ein Wartevorgang, und ein neuerer Wartevorgang auf demselben Postfach ersetzt den älteren; Wartevorgänge auf verschiedenen Postfächern laufen parallel, bis zu 2 gleichzeitig pro Konto.

E-Mail-Tests in Playwright, Cypress, pytest und CI

Gib jedem Test ein eigenes Postfach, löse die Registrierungs- oder Passwort-Reset-E-Mail deiner App aus, warte darauf und prüfe Code oder Link per Assertion. Lösche das Postfach im Teardown.

Speichere den Schlüssel als CI-Secret, zum Beispiel als TEMPGENERATOR_TOKEN in GitHub Actions. Cypress kann dieselben HTTP-Aufrufe mit cy.request ausführen, und das Python-Rezept unten funktioniert mit pytest oder jedem anderen Test-Runner.

Playwright (TypeScript)

import { test, expect } from '@playwright/test';

const api = `${process.env.TEMPGENERATOR_URL}/developer-api/v1`;
const headers = { Authorization: `Bearer ${process.env.TEMPGENERATOR_TOKEN}`, Accept: 'application/json' };

async function call(path: string, method = 'GET') {
  const response = await fetch(api + path, { method, headers });
  if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
  return response.status === 204 ? null : response.json();
}

async function waitForCode(inboxId: string, after = 0): Promise<string> {
  for (let attempt = 0; attempt < 3; attempt++) {
    const result = await call(`/inboxes/${inboxId}/wait?after=${after}&timeout=20`);
    for (const summary of result.messages) {
      const message = await call(`/inboxes/${inboxId}/messages/${summary.id}`);
      if (message.codes.length) return message.codes[0];
    }
    after = result.next_cursor;
  }
  throw new Error('No verification code arrived');
}

test('signup sends a verification code', async ({ page }) => {
  const inbox = await call('/inboxes', 'POST');
  try {
    await page.goto('/signup');
    await page.getByLabel('Email').fill(inbox.address);
    await page.getByRole('button', { name: 'Create account' }).click();
    await page.getByLabel('Verification code').fill(await waitForCode(inbox.id));
    await expect(page.getByText('Welcome')).toBeVisible();
  } finally {
    await call(`/inboxes/${inbox.id}`, 'DELETE');
  }
});

GitHub Actions

- name: End-to-end tests
  run: npx playwright test
  env:
    TEMPGENERATOR_URL: https://www.tempgenerator.com
    TEMPGENERATOR_TOKEN: ${{ secrets.TEMPGENERATOR_TOKEN }}

Registrierungs-Check mit Python

Führe das Skript mit gesetzten Umgebungsvariablen aus. Es gibt ein neues Postfach aus; sende aus deiner eigenen Test-App eine Registrierungs-E-Mail an diese Adresse und drücke dann die Eingabetaste. Es wartet bis zu 15 Sekunden, gibt jede Nachricht mit ihren Codes und Links aus und löscht das Postfach auch dann, wenn das Lesen fehlschlägt.

import json, os
from urllib.request import Request, urlopen

base = os.environ["TEMPGENERATOR_URL"].rstrip("/") + "/developer-api/v1"
headers = {"Authorization": "Bearer " + os.environ["TEMPGENERATOR_TOKEN"],
           "Accept": "application/json"}

def request(path, method="GET"):
    with urlopen(Request(base + path, headers=headers, method=method), timeout=30) as response:
        return json.load(response) if response.status != 204 else None

inbox = request("/inboxes", "POST")
print(json.dumps(inbox), flush=True)
try:
    input()
    result = request("/inboxes/" + inbox["id"] + "/wait?after=0&timeout=15")
    print(json.dumps(result))
    for message in result["messages"]:
        detail = request("/inboxes/" + inbox["id"] + "/messages/" + str(message["id"]))
        print(json.dumps(detail))
finally:
    request("/inboxes/" + inbox["id"], "DELETE")

MCP-Server für KI-Agenten

Endpunkt https://www.tempgenerator.com/mcp, authentifiziert mit Authorization: Bearer <key>. Streamable HTTP mit Protokoll 2026-07-28; ältere Clients werden über den Handshake 2025-11-25 oder 2025-06-18 bedient.

Client verbinden

Claude Code

claude mcp add --transport http tempgenerator-mail https://www.tempgenerator.com/mcp \
  --header "Authorization: Bearer $TEMPGENERATOR_TOKEN"

Cursor: .cursor/mcp.json

{
  "mcpServers": {
    "tempgenerator-mail": {
      "url": "https://www.tempgenerator.com/mcp",
      "headers": { "Authorization": "Bearer ${env:TEMPGENERATOR_TOKEN}" }
    }
  }
}

VS Code: .vscode/mcp.json

{
  "inputs": [
    { "type": "promptString", "id": "tempgenerator-token", "description": "TempGenerator API key", "password": true }
  ],
  "servers": {
    "tempgenerator-mail": {
      "type": "http",
      "url": "https://www.tempgenerator.com/mcp",
      "headers": { "Authorization": "Bearer ${input:tempgenerator-token}" }
    }
  }
}

Claude im Web und in der Desktop-App: Füge einen benutzerdefinierten Konnektor mit der Endpunkt-URL hinzu, wähle keine Anmeldung und ergänze den Anfrage-Header Authorization: Bearer <key>. Claude verbindet sich aus der Cloud von Anthropic, daher muss die URL öffentlich erreichbar sein.

Tools

create_inbox

Erstellt ein privates Postfach und gibt dessen ID und Adresse zurück.

list_messages

Listet Nachrichtenübersichten nach einem Cursor auf, optional gefiltert nach Absender und Betreff.

wait_for_message

Wartet bis zu 20 Sekunden auf die nächste Nachricht.

read_message

Liest Text, Codes, Links und Anhangsliste einer Nachricht.

delete_inbox

Löscht das Postfach samt Nachrichten.

Beispiel-Prompt

Erstelle ein temporäres Postfach und nenne mir die Adresse. Warte dann auf die Bestätigungs-E-Mail meiner Staging-App und sag mir den Code.

Lass Agenten Registrierungen nur für Konten abschließen, die dir gehören oder die du nutzen darfst. Empfangene E-Mails sind nicht vertrauenswürdig: Der Server öffnet nie Links, und Agenten sollten niemals Anweisungen aus einer Nachricht befolgen.

MCP-SDK für Python

Getestet mit Python 3 und dem offiziellen Paket mcp 2.3.0: pip install "mcp>=2.3,<3". Setze zuerst TEMPGENERATOR_URL und TEMPGENERATOR_TOKEN.

import asyncio, os

import httpx2
from mcp import Client
from mcp.client.streamable_http import streamable_http_client

async def main():
    url = os.environ["TEMPGENERATOR_URL"].rstrip("/") + "/mcp"
    headers = {"Authorization": "Bearer " + os.environ["TEMPGENERATOR_TOKEN"]}
    async with httpx2.AsyncClient(headers=headers, timeout=httpx2.Timeout(30, read=60)) as http:
        async with Client(streamable_http_client(url, http_client=http)) as client:
            print([tool.name for tool in (await client.list_tools()).tools])
            created = await client.call_tool("create_inbox", {})
            if created.is_error:
                raise RuntimeError(created.content)
            inbox = created.structured_content
            try:
                print("Send a test email to", inbox["address"])
                waited = await client.call_tool("wait_for_message", {"inbox_id": inbox["id"], "timeout": 20})
                for summary in waited.structured_content["messages"]:
                    message = await client.call_tool("read_message", {"inbox_id": inbox["id"], "message_id": summary["id"]})
                    print(message.structured_content["subject"], message.structured_content["codes"])
            finally:
                deleted = await client.call_tool("delete_inbox", {"inbox_id": inbox["id"]})
                if deleted.is_error:
                    raise RuntimeError(deleted.content)

asyncio.run(main())

Anhänge

Beim Lesen einer Nachricht erhältst du Index, Dateiname und Größe jedes Anhangs. Lade einen Anhang mit GET …/attachments/{index} herunter: Dateien bis 10 MB werden als application/octet-stream mit bereinigten Dateinamen ausgeliefert. MCP-Clients sehen dieselbe Liste und laden über diesen REST-Endpunkt herunter.

Wann du diese API statt anderer Tools nutzt

Mailpit, MailHog und Ethereal fangen die E-Mails ab, die deine eigene App an einen lokalen oder Fake-SMTP-Server sendet – ideal, wenn du die SMTP-Einstellungen selbst kontrollierst. Diese Postfächer sind dagegen echte Adressen auf einer öffentlichen Domain, die jeder Absender erreichen kann: ein Drittanbieterdienst, ein Staging-Server mit deinem echten E-Mail-Anbieter oder ein produktionsnaher Ablauf.

Allgemeine Temp-Mail-APIs wie mail.tm oder Guerrilla Mail sind für persönliche Wegwerfadressen gedacht. Diese API ist für Automatisierung gebaut: befristete Schlüssel mit festen Berechtigungen, ein Postfach pro Test, begrenztes Warten per Long-Polling, erkannte Codes und Links sowie ein MCP-Server.

Nicht enthalten: E-Mail-Versand, SMS, HTML- oder Spam-Vorschauen, eigene Domains und OAuth-Anmeldung für MCP-Clients.

Aufbewahrung, Limits und Sicherheit

Eine Empfangsdomain kann eine kürzere Lebensdauer oder ein niedrigeres Nachrichtenlimit festlegen.

Nur Empfang. Behandle E-Mails und Anhänge als nicht vertrauenswürdig; nichts wird automatisch geöffnet. Das Löschen eines Postfachs entfernt seine Nachrichten sofort, und abgelaufene Postfächer werden durch eine geplante Bereinigung entfernt.

Häufige Fragen