E-Mail-Posteingangs-API + Versand per Sendmux

E-Mail-Posteingangs-API, eingehende E-Mails und ausgehender Versand – MCP- und A2A-Server für KI-Agenten, mit eingehenden E-Mails, sauberem JSON-Parsing, Webhooks und Multi-Provider-Routing über Sendmux.

Dieses Paket ist das Sendmux-MCP. Halten Sie es getrennt von jedem Dokumentationssuch-MCP, das von Dokumentationswerkzeugen verwendet wird.

Dokumentation

• Sendmux-Dokumentation: sendmux.ai/docs

• Referenz der Management-API: sendmux.ai/docs/api/introduction

• Referenz der Mailbox-API: sendmux.ai/docs/mailbox-api/introduction

• Referenz der Sending-API: sendmux.ai/docs/sending-api/introduction

• Quellrepository: Sendmux/sendmux-sdk

Related MCP server: mcp-server-lobstermail

Voraussetzungen

• Python 3.10 oder neuer.

• Ein sendefähiger smx_mbx_*-Schlüssel oder ein vom Eigentümer genehmigtes Sending-Ressourcen-smx_agent_*-Token für Sending-Tools.

• Ein Mailbox-bezogener smx_mbx_*-Schlüssel oder ein eingeschränktes smx_agent_*-Token für Mailbox-Tools.

• Ein Root-smx_root_*-Schlüssel für Management-Tools.

Installation

pip install sendmux-mcp

Verwendung

Führen Sie einen einzelnen lokalen Server mit den oberflächenspezifischen Befehlen aus.

SENDMUX_API_KEY=smx_mbx_... sendmux-mcp-mailbox
SENDMUX_API_KEY=smx_root_... sendmux-mcp-management
SENDMUX_API_KEY=smx_mbx_... sendmux-mcp-sending

Führen Sie einen kombinierten lokalen Server mit sendmux-mcp aus.

SENDMUX_MCP_SURFACES=mailbox,sending \
SENDMUX_MAILBOX_API_KEY=smx_mbx_... \
SENDMUX_SENDING_API_KEY=smx_mbx_... \
sendmux-mcp

Führen Sie alle drei lokalen Oberflächen aus, wenn Sie beide Schlüsseltypen besitzen.

SENDMUX_MCP_SURFACES=mailbox,management,sending \
SENDMUX_MAILBOX_API_KEY=smx_mbx_... \
SENDMUX_MANAGEMENT_API_KEY=smx_root_... \
SENDMUX_SENDING_API_KEY=smx_mbx_... \
sendmux-mcp

Der generische Befehl sendmux-mcp akzeptiert auch --surface oder --surfaces. Die Wrapper-Befehle wählen genau eine Oberfläche aus.

Transporte

stdio ist der Standardtransport für lokale Agent-Clients.

SENDMUX_API_KEY=smx_mbx_... sendmux-mcp-mailbox --transport stdio

http und streamable-http stellen den MCP-Endpunkt über HTTP bereit. Der HTTP-Modus verwendet standardmäßig 127.0.0.1:8765/mcp und erfordert ein separates MCP-Bearer-Token, sofern Sie nicht ausdrücklich darauf verzichten.

SENDMUX_API_KEY=smx_mbx_... \
SENDMUX_MCP_HTTP_BEARER_TOKEN=local-mcp-token \
sendmux-mcp-mailbox --transport http --host 127.0.0.1 --port 8765 --path /mcp

/health gibt eine kleine JSON-Health-Antwort für die ausgewählten Oberflächen zurück.

Gehosteter Endpunkt

Der öffentliche gehostete MCP-Endpunkt ist https://mcp.sendmux.ai/mcp.

Verwenden Sie für gehostete Clients HTTP-Transport mit OAuth. Fügen Sie keine manuellen Authorization-Header, API-Schlüssel, benutzerdefinierte OAuth-Endpunkte oder benutzerdefinierte Bereiche hinzu, es sei denn, Ihr Client erfordert diese ausdrücklich.

Gehostete OAuth-Clients, die angeforderte Bereiche während der Registrierung oder Autorisierung weglassen, werden unterstützt; der Server bewirbt den gehosteten Bereichssatz über Discovery und Bearer-Challenges.

Der gebündelte Befehl sendmux-mcp-hosted führt die gehostete Serverlaufzeit aus. Lokale und private Bereitstellungen sollten die obigen lokalen Befehle verwenden, es sei denn, Sie betreiben eine kompatible OAuth-gestützte gehostete Umgebung.

Gehosteter A2A-Endpunkt

Dieselbe gehostete Laufzeit stellt deterministisches A2A 1.0 über HTTP+JSON unter https://a2a.sendmux.ai/a2a/v1 bereit. Entdecken Sie es über https://a2a.sendmux.ai/.well-known/agent-card.json; OAuth-Ressourcenmetadaten finden Sie unter https://a2a.sendmux.ai/.well-known/oauth-protected-resource.

Senden Sie genau ein JSON-DataPart an die A2A-Operation message:send. Seine Daten wählen eine kuratierte Sendmux-Operation aus und liefern die Eingaben dieser Operation:

{
  "operationId": "managementListDomains",
  "pathParameters": {},
  "query": { "limit": 10 },
  "headers": {},
  "body": null,
  "mailboxId": null
}

operationId verwendet dieselben kuratierten Operations-IDs wie der gehostete MCP-Dienst. OAuth-Gewährungen sind an die Zielgruppe der A2A-Ressource gebunden und behalten ihre Sendmux-Oberflächen- und Berechtigungsgrenzen bei. Der Dienst gibt ein JSON-DataPart zurück, das den Upstream-Status, sichere Antwort-Header und den JSON-Body (oder bodyBase64 für Nicht-JSON-Antworten) enthält.

Der A2A-Endpunkt ist unmittelbar und zustandslos: Streaming, Push-Benachrichtigungen, persistente Aufgaben und Aufgabenabbrüche werden nicht beworben oder weitergeleitet.

Konfiguration

Gebündelte OpenAPI-Snapshots sind die Standardeinstellung, damit veröffentlichte Tool-Namen, Schemata und Beschreibungen stabil bleiben. Pfad-, Verzeichnis- und URL-Überschreibungen sind für Entwicklungs-, Canary- und Debugging-Läufe verfügbar.

Tool-Oberflächen

• Mailbox: 25 Tools für gewährte Mailboxen, Profil-/Sitzungsermittlung, Nachrichten, Anhänge, begrenzte Nachrichtenwartezeiten, Threads, Ordner, Suche, Zählungen und Mailbox-Sendungen. Erfordert einen smx_mbx_*-Schlüssel oder ein eingeschränktes smx_agent_*-Token. Agent-Tokens bleiben durch serverseitige Bereiche begrenzt; vorab beanspruchte, selbstregistrierte Agent-Tokens enthalten kein email.send.

• Management: 21 Tools für Domänen, Mailboxen, Protokolle, Metriken, Ausgabenübersicht und Webhooks. Erfordert einen smx_root_*-Schlüssel.

• Sending: 5 Tools für Anhang-Upload-Referenzen, Einzelsendungen und Stapelsendungen. Erfordert einen smx_mbx_*-Schlüssel oder ein vom Eigentümer genehmigtes Sending-Ressourcen-smx_agent_*-Token.

Der Server lehnt Schlüssel mit dem falschen Präfix ab, bevor er startet.

Anhang-Workflow für Agenten

Verwenden Sie mailbox_wait_for_message, wenn ein Benutzer einen Agenten bittet, auf neue E-Mails zu warten. Das Tool ist begrenzt; wenn es matched=false zurückgibt, rufen Sie es erneut auf, anstatt einen MCP-Toolaufruf auf unbestimmte Zeit offen zu halten.

Wenn eine Nachricht Anhänge hat:

1. Rufen Sie mailbox_read_attachment mit message_id und attachment_id auf, wenn Sie den Inhalt des Anhangs benötigen.

2. Lesen Sie bei kleinen textähnlichen Anhängen den zurückgegebenen text.

3. Verwenden Sie bei binären oder übergroßen Anhängen den zurückgegebenen resource_link / download_url umgehend außerhalb des Modellkontexts.

4. Verwenden Sie mailbox_get_attachment nur, wenn Metadaten ausreichen oder Sie den Link aktualisieren müssen.

Verwenden Sie mailbox_upload_attachment für ausgehende Anhänge über MCP. Es akzeptiert genau einen Eingabemodus:

• file_path für lokales stdio-MCP, wenn sich die Datei in einem vom Client deklarierten Dateisystem-Root befindet.

• presign_upload_url=true für gehostetes MCP oder shell-fähige Agenten; laden Sie die Datei mit exakten Headern und ohne API-Schlüssel auf die zurückgegebene URL hoch und senden Sie dann mit der zurückgegebenen blob_id.

• content_base64 nur für winzige, vom Agenten erstellte Dateien, begrenzt auf 32 KiB dekodiert. Wenn sie zu groß ist, wechseln Sie zu file_path, Presigned-Upload, CLI --attach oder SDK-Datei-Hilfsfunktionen.

file_path- und Presigned-Upload-Modi verwenden das Mailbox-Anhanglimit, derzeit 7.500.000 Bytes pro Anhang. Presigned-Uploads legen auch die exakt deklarierte Bytelänge und den Inhaltstyp fest.

Für Mailbox-Sendungen akzeptiert mailbox_send_message entweder winzige Inline-Base64-Anhangobjekte (content, filename, content_type) oder hochgeladene Anhangreferenzen (blob_id, filename, content_type).

Für Sending-API-Sendungen rufen Sie sending_upload_attachment mit file_path auf lokalem stdio-MCP auf, oder rufen Sie sending_create_attachment_upload auf und senden Sie Bytes außerhalb des Modellkontexts für gehostete/shell-fähige Agenten. Übergeben Sie dann {"attachment_id": "att_..."} in sending_send_email.attachments[]. Vermeiden Sie Sending-Inline-Base64, außer für winzige generierte Inhalte.

Konsolen-Skripte

• sendmux-mcp

• sendmux-mcp-mailbox

• sendmux-mcp-management

• sendmux-mcp-sending

• sendmux-mcp-hosted

Support

Öffnen Sie ein Issue in Sendmux/sendmux-sdk mit dem Paketnamen, der Version, dem Befehl, dem Transport und der Request-ID aus einem beliebigen API-Fehler.

Lizenz

MIT. Siehe die Lizenzdatei.