Auf MCPEmails aufbauen

Der Endpunkt

Jede Anfrage ist ein JSON-RPC-2.0-POST an https://mcpemails.com/api/mcp. Das ist derselbe Endpunkt, den claude.ai, ChatGPT und andere MCP-Clients verwenden, mit denselben Tools und denselben Berechtigungen. Ein Skript und ein Chat-Assistent sehen also ein und dasselbe Produkt.

• Senden Sie Content-Type: application/json und Accept: application/json. Die Antwort ist ein einzelnes JSON-Objekt.
• Der Server hält keine Sitzung. Es gibt nichts zu öffnen oder zu schließen, und jede Anfrage trägt ihren eigenen Authorization-Header.
• Erfolgreiche Tool-Ergebnisse enthalten ein typisiertes structuredContent-Objekt, sodass Sie nie Fließtext parsen müssen. Dieselben Daten stehen als JSON-String in content[0].text.

Authentifizierung

API-Schlüssel

• Erstellen Sie einen Schlüssel im Dashboard unter API-Schlüssel → Neuer Schlüssel. Benennen Sie ihn nach dem Skript oder Workflow, der ihn verwenden wird.
• Ein Schlüssel besteht aus mcpe_ und 64 Hexadezimalzeichen. Er wird einmal angezeigt, beim Erstellen, und nur ein Hash wird gespeichert. Kopieren Sie ihn dann; ein verlorener Schlüssel lässt sich nicht wiederherstellen, nur ersetzen.
• Senden Sie ihn bei jeder Anfrage als Authorization: Bearer mcpe_.... Setzen Sie einen Schlüssel nie in eine URL oder einen Query-String.
• Jeder Tarif kann so viele Schlüssel erstellen, wie er braucht. Verwenden Sie einen Schlüssel pro Skript oder Workflow, damit Sie einen widerrufen können, ohne die anderen anzutasten.
• Das Widerrufen eines Schlüssels auf der Seite API-Schlüssel beendet den Zugriff sofort.

Scopes

Jeder Schlüssel hat nur die Berechtigungen, die Sie beim Erstellen ankreuzen. Sie können sie später unter Zugriff bearbeiten ändern; die Änderung gilt ab dem nächsten Aufruf, ohne neu zu verbinden.

Beginnen Sie mit read:email und ergänzen Sie einen Schreib-Scope erst, wenn der Workflow ihn braucht. Ein Aufruf außerhalb der Scopes des Schlüssels wird abgelehnt, bevor wir Ihren Mailserver kontaktieren. Betrachter eines Workspace können nur Lese-Scopes halten.

Postfachzugriff

Ein Schlüssel erreicht standardmäßig jedes Postfach im Workspace. Um ihn auf einige davon festzulegen, öffnen Sie Zugriff bearbeiten am Schlüssel und wählen die Postfächer unter Postfachzugriff. Die Einschränkung wird bei jedem Aufruf geprüft: Ein Schlüssel, der auf das Support-Postfach festgelegt ist, kann das Finanz-Postfach nicht lesen, egal was die Anfrage sagt.

OAuth für Konnektor-Apps

Apps, die Nutzer selbst verbinden, etwa claude.ai, ChatGPT und andere MCP-Clients, melden sich mit OAuth statt mit einem Schlüssel an: dynamische Client-Registrierung, Authorization Code mit PKCE und ein Zustimmungsbildschirm, auf dem der Nutzer Scopes und Postfächer wählt. Siehe OAuth-Verbindung. Für Ihre eigenen Skripte, Server und Workflows ist ein API-Schlüssel einfacher.

Die drei Aufrufe

1. initialize (optional)

MCP-Clients beginnen mit initialize. Ein Skript kann es überspringen, weil der Server keine Sitzung hält, aber es ist ein günstiger Weg, um zu prüfen, ob der Schlüssel funktioniert, und die Anweisungen des Servers zu lesen.

curl -s https://mcpemails.com/api/mcp \
  -H "Authorization: Bearer $MCPEMAILS_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "clientInfo": { "name": "my-agent", "version": "1.0" },
      "capabilities": {}
    }
  }'

2. tools/list

tools/list liefert jedes Tool, das dieser Schlüssel aufrufen darf, mit Beschreibung, Eingabeschema und Ausgabeschema. Lesen Sie es beim Start, statt Tool-Namen oder Argumente fest zu verdrahten: Die Liste ist nach den Scopes des Schlüssels gefiltert, und Tools bekommen mit der Zeit neue Argumente.

curl -s https://mcpemails.com/api/mcp \
  -H "Authorization: Bearer $MCPEMAILS_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/list" }'

3. tools/call

Rufen Sie ein Tool über seinen Namen mit seinen Argumenten auf. Die meisten Tools nehmen eine action, die bestimmt, was sie tun, etwa list, read oder search bei email_read. Benennen Sie das Postfach mit inbox (seiner Adresse) oder inbox_id; inbox_list liefert beides.

curl -s https://mcpemails.com/api/mcp \
  -H "Authorization: Bearer $MCPEMAILS_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "email_read",
      "arguments": { "action": "list", "inbox": "you@example.com", "unread": true, "limit": 20 }
    }
  }'

Ein erfolgreiches Ergebnis:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [{ "type": "text", "text": "{\"messages\":[...],\"total\":42, ...}" }],
    "structuredContent": {
      "messages": [{ "id": "...", "subject": "...", "from": { "name": "...", "email": "..." } }],
      "total": 42,
      "total_is_estimate": false,
      "has_more": true,
      "next_offset": 20
    }
  }
}

Die Tool-Referenz beschreibt jedes Tool, und der curl-Leitfaden enthält weitere Beispiele.

Fehler

Es gibt zwei Arten. Eine Anfrage, die gar nicht ausgeführt werden konnte, kommt als JSON-RPC-error mit einem HTTP-Status zurück. Eine Anfrage, die ein Tool erreicht hat und von ihm abgelehnt wurde, kommt als normales result mit isError: true zurück, damit ein KI-Modell den Grund liest. Verzweigen Sie anhand von data.error_code oder dem _meta-Code, nicht anhand des Meldungstexts.

HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope", ...

{
  "jsonrpc": "2.0",
  "id": 4,
  "error": {
    "code": -32004,
    "message": "Insufficient scope: the 'send:email' scope is required to call email_compose.",
    "data": { "error_code": "insufficient_scope", "required_scopes": ["send:email"], ... }
  }
}

HTTP/1.1 429 Too Many Requests
Retry-After: 12

{
  "jsonrpc": "2.0",
  "id": 5,
  "error": {
    "code": -32003,
    "message": "Rate limit exceeded",
    "data": { "error_code": "rate_limit_exceeded", "window": "per_minute", "retry_after": 12, ... }
  }
}

{
  "jsonrpc": "2.0",
  "id": 6,
  "result": {
    "isError": true,
    "content": [{ "type": "text", "text": "Invalid arguments for email_read. The call was rejected before it ran, ..." }],
    "_meta": {
      "com.mcpemails/invalid_arguments": {
        "error_code": "invalid_arguments",
        "retryable": false,
        "errors": [{ "path": "arguments.since", "message": "..." }]
      }
    }
  }
}

Paginierung

Jedes Listen- und Suchergebnis endet mit denselben vier Feldern:

• has_more: true, wenn eine weitere Seite existiert. Nur has_more: false bedeutet, dass Sie alles gesehen haben.
• next_offset: Geben Sie ihn als offset zurück, mit allen anderen Argumenten unverändert, um die nächste Seite zu erhalten. Er ist null, wenn has_more false ist.
• total: die Zahl der Treffer, oder null, wenn der Anbieter sie nicht zählen kann. Sie widerspricht nie der Seite, die Sie gerade halten.
• total_is_estimate: true, wenn total eine Schätzung oder eine Untergrenze ist und keine exakte Zählung.

Lange Nachrichtentexte werden auf dieselbe Weise in Abschnitte geteilt: Wenn body_truncated true ist, lesen Sie erneut mit body_next_offset als body_offset.

Wiederholungen und Idempotenzschlüssel

Eine abgebrochene Verbindung nach einem Versand lässt Sie im Unklaren, ob die E-Mail rausgegangen ist. Übergeben Sie einen idempotency_key und wiederholen Sie mit demselben Schlüssel: Die Arbeit läuft genau einmal.

curl -s https://mcpemails.com/api/mcp \
  -H "Authorization: Bearer $MCPEMAILS_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 7,
    "method": "tools/call",
    "params": {
      "name": "email_compose",
      "arguments": {
        "action": "send",
        "inbox": "you@example.com",
        "to": ["customer@example.com"],
        "subject": "Your order has shipped",
        "body": "Hi, your order is on its way.",
        "idempotency_key": "order-1042-shipped"
      }
    }
  }'

• Akzeptiert bei Sendungen, Antworten, Weiterleitungen, geplanten Sendungen, Entwurfsänderungen und Postfachänderungen wie Verschieben, Markieren und Löschen. tools/list zeigt idempotency_key im Eingabeschema jedes Tools, das ihn annimmt.
• Bis zu 200 Zeichen. Verwenden Sie etwas aus Ihrem eigenen System, etwa eine Bestellnummer und einen Ereignisnamen.
• Schlüssel sind an den API-Schlüssel gebunden, der sie gesendet hat, und werden 24 Stunden lang gemerkt.
• Eine Wiederholung mit demselben Schlüssel und denselben Argumenten läuft nicht erneut. Sie liefert idempotent_replay: true, den ursprünglichen status und das ursprüngliche Ergebnis in result, einschließlich der message_id, die Ihnen vielleicht verloren ging.
• Derselbe Schlüssel mit anderen Argumenten wird mit idempotency_key_conflict abgelehnt. Verwenden Sie für eine neue Operation einen neuen Schlüssel.
• Eine Wiederholung, während der erste Aufruf noch läuft, liefert status: "processing". Versuchen Sie es kurz darauf erneut.
• Wenn der Mailanbieter einen Versand abgelehnt hat, bevor er ihn angenommen hat, wurde nichts gesendet und der Schlüssel wird freigegeben, sodass die identische Wiederholung tatsächlich sendet.
• Wenn der Ausgang ungewiss ist, meldet die Wiedergabe status: "unknown". Prüfen Sie den Ordner Gesendet, bevor Sie unter einem neuen Schlüssel erneut senden.

{
  "idempotency_key": "order-1042-shipped",
  "idempotent_replay": true,
  "status": "succeeded",
  "result": { "message_id": "...", "inbox_id": "...", "status": "sent" },
  "message": "This logical request was already processed. ..."
}

Sendefreigabe

Jedes Postfach kann jede Sendung zurückhalten, bis eine Person sie freigibt. Eine Sendung aus Ihrem Skript liefert dann eine approval_id mit status: "pending_approval", statt rauszugehen, und geht raus, sobald jemand sie im Dashboard freigibt. Das funktioniert in jedem Tarif und ist eine gute Voreinstellung, solange sich eine neue Automatisierung erst bewähren muss. Eine Wiederholung mit demselben idempotency_key meldet die Freigabe, statt eine zweite anzulegen.

Ratenlimits

Jeder Tarif hat eine Obergrenze pro Minute für den gesamten Workspace. Ein einzelner Schlüssel kann das volle Minutenlimit des Tarifs nutzen; mehrere Schlüssel teilen es sich.

• tools/call-Antworten tragen RateLimit-Limit, RateLimit-Remaining und RateLimit-Reset (in Sekunden) für das Zeitfenster, das am nächsten an seiner Grenze ist, damit ein Client sein Tempo anpassen kann, bevor er das Limit erreicht.
• Jeder Schlüssel hat außerdem Stunden- und Tagesfenster. Ein 429 nennt in data.window das Fenster, das voll ist.
• Ein 429 trägt Retry-After in Sekunden. Warten Sie so lange und senden Sie dann dieselbe Anfrage erneut.
• Free enthält ein monatliches Kontingent an E-Mail-Aktionen. Bezahlte Tarife haben keine monatliche Obergrenze und keine Kosten pro Aufruf.

Webhooks für neue E-Mails

In Pro und Business kann MCPEmails einen POST an Ihre URL senden, wenn E-Mails in einem Postfach eintreffen, sodass ein Workflow bei neuer Post startet, statt abzufragen. Erstellen Sie im Dashboard einen Endpunkt, wählen Sie seine Postfächer und kopieren Sie das Signaturgeheimnis, das einmal angezeigt wird. Die URL muss HTTPS sein, auf Port 443 oder 8443. Mit der Testschaltfläche senden Sie ein signiertes ping-Ereignis.

Das Ereignis

POST /your/webhook HTTP/1.1
Content-Type: application/json
MCPEmails-Event-Id: evt_...
MCPEmails-Event-Type: message.received
MCPEmails-Signature: t=1792843200,v1=5f2b...

{
  "id": "evt_...",
  "type": "message.received",
  "created_at": "2026-10-24T09:20:00.000Z",
  "workspace_id": "...",
  "inbox_id": "...",
  "folder": "INBOX",
  "count": 1,
  "message_ids": ["..."]
}

• type ist message.received. message_ids listet die neuen Nachrichten im Ordner INBOX dieses Postfachs, bis zu 10 pro Ereignis; count ist die Zahl der eingetroffenen Nachrichten und kann höher sein.
• Standardmäßig enthält die Nutzlast nur IDs, keinen Inhalt. Ein Endpunkt, der auf Header einschließen gestellt ist, erhält zusätzlich eine messages-Liste mit id, from und subject jeder Nachricht.
• Holen Sie die Nachricht mit email_read (action: "read", der inbox_id und einer message_id) über einen API-Schlüssel. Die Scopes und der Postfachzugriff dieses Schlüssels gelten wie gewohnt.
• Die Zustellung erfolgt in der Regel innerhalb von etwa zwei Minuten nach Eintreffen der Nachricht. Postfächer werden nach Zeitplan geprüft, es geschieht also nicht sofort.

Signatur prüfen

Jede Zustellung trägt MCPEmails-Signature: t=<Unix-Sekunden>,v1=<hex>, wobei v1 der HMAC-SHA256 über den Zeitstempel, einen Punkt und den rohen Anfragekörper ist, mit dem Geheimnis des Endpunkts als Schlüssel. Der Schlüssel ist das ganze Geheimnis wie angezeigt, einschließlich des Präfixes whsec_. Berechnen Sie die Signatur über den rohen Körper neu, vergleichen Sie in konstanter Zeit und lehnen Sie einen Zeitstempel ab, der älter als fünf Minuten ist.

import crypto from 'node:crypto';

// rawBody: the request body exactly as received, before JSON.parse.
export function verifyMcpemailsSignature(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(
    String(header ?? '').split(',').map((part) => part.trim().split('=')),
  );
  const timestamp = Number(parts.t);
  if (!Number.isFinite(timestamp)) return false;
  if (Math.abs(Date.now() / 1000 - timestamp) > toleranceSeconds) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${parts.t}.${rawBody}`)
    .digest();
  const received = Buffer.from(parts.v1 ?? '', 'hex');
  return received.length === expected.length && crypto.timingSafeEqual(received, expected);
}

Wiederholungen

• Antworten Sie innerhalb von 10 Sekunden mit einem beliebigen 2xx-Status. Alles andere zählt als Fehlschlag, auch eine Weiterleitung, der nicht gefolgt wird.
• Eine fehlgeschlagene Zustellung wird nach 1 Minute, 5 Minuten, 30 Minuten, 2 Stunden, 6 Stunden und 24 Stunden wiederholt. Jede Wiederholung wird mit einem frischen Zeitstempel neu signiert.
• Ein Endpunkt, der 24 Stunden lang oder 50-mal in Folge fehlgeschlagen ist, wird deaktiviert, und der Workspace-Inhaber wird per E-Mail informiert. Sie können ihn im Dashboard wieder einschalten.
• Verwenden Sie MCPEmails-Event-Id, um eine bereits verarbeitete Zustellung zu ignorieren. Eine Wiederholung trägt dieselbe Ereignis-ID.

Rezepte

n8n: einen Workflow bei neuer E-Mail starten

• Fügen Sie einen Webhook-Trigger-Node mit der HTTP-Methode POST hinzu und registrieren Sie seine Produktions-URL als Webhook-Endpunkt im MCPEmails-Dashboard.
• Fügen Sie einen HTTP Request-Node hinzu: Methode POST, URL https://mcpemails.com/api/mcp, Authentifizierung Generic Credential Type → Header Auth mit dem Namen Authorization und dem Wert Bearer mcpe_....
• Aktivieren Sie Send Body, wählen Sie JSON und verwenden Sie den Body unten, um die neue Nachricht zu lesen. Die folgenden Nodes erhalten die Nachricht in result.structuredContent.
• Um die Signatur in n8n zu prüfen, aktivieren Sie Raw Body am Webhook-Node und führen die obige Prüfung in einem Code-Node aus. Auf selbst gehostetem n8n erlauben Sie das crypto-Modul mit NODE_FUNCTION_ALLOW_BUILTIN=crypto.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "email_read",
    "arguments": {
      "action": "read",
      "inbox_id": "{{ $json.body.inbox_id }}",
      "message_id": "{{ $json.body.message_ids[0] }}"
    }
  }
}

Für einen AI-Agent-Node, der selbst E-Mails liest und sendet, siehe den n8n-Leitfaden.

Claude Code

Fügen Sie den Server mit einem Schlüssel in einem Header hinzu. Das passt zu Headless-Maschinen und CI, wo es keinen Browser für die OAuth-Anmeldung gibt:

claude mcp add --transport http mcpemails https://mcpemails.com/api/mcp \
  --header "Authorization: Bearer $MCPEMAILS_KEY"

Der Claude-Code-Leitfaden behandelt die OAuth-Anmeldung und die Wahl der Scopes.

Ein kurzes Node-Skript

Listet jede ungelesene Nachricht in einem Postfach, Seite für Seite, und wartet einen 429 ab:

// node agent.mjs  (Node 18 or later, MCPEMAILS_KEY in the environment)
const ENDPOINT = 'https://mcpemails.com/api/mcp';
let nextId = 1;

async function callTool(name, args) {
  const res = await fetch(ENDPOINT, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.MCPEMAILS_KEY}`,
      'Content-Type': 'application/json',
      Accept: 'application/json',
    },
    body: JSON.stringify({ jsonrpc: '2.0', id: nextId++, method: 'tools/call', params: { name, arguments: args } }),
  });
  if (res.status === 429) {
    const wait = Number(res.headers.get('Retry-After') ?? 1);
    await new Promise((resolve) => setTimeout(resolve, wait * 1000));
    return callTool(name, args);
  }
  const reply = await res.json();
  if (reply.error) throw new Error(`${reply.error.code}: ${reply.error.message}`);
  if (reply.result.isError) throw new Error(reply.result.content[0].text);
  return reply.result.structuredContent;
}

const inbox = 'you@example.com';
let offset = 0;
do {
  const page = await callTool('email_read', { action: 'list', inbox, unread: true, limit: 50, offset });
  for (const m of page.messages) console.log(m.id, m.from?.email, m.subject);
  offset = page.has_more ? page.next_offset : null;
} while (offset !== null);

OpenClaw

OpenClaw meldet sich standardmäßig mit OAuth an; der OpenClaw-Leitfaden führt Sie hindurch. Um stattdessen einen eingeschränkten Schlüssel zu verwenden, tragen Sie ihn in die headers-Map des Servereintrags ein und lassen auth leer, denn OpenClaw ignoriert einen statischen Authorization-Header bei einem Eintrag, der auf OAuth steht.

{
  "mcp": {
    "servers": {
      "mcpemails": {
        "url": "https://mcpemails.com/api/mcp",
        "transport": "streamable-http",
        "headers": { "Authorization": "Bearer mcpe_YOUR_KEY_HERE" }
      }
    }
  }
}