Inbound-E-Mail-API: E-Mails programmatisch empfangen fuer KI-Agenten

Eine Inbound-E-Mail-API ermoeglicht es Ihrer Anwendung, E-Mails programmatisch zu empfangen. Anstatt ein Postfach abzufragen oder einen Posteingang zu durchsuchen, werden eingehende Nachrichten in Echtzeit ueber Webhooks an Ihren Code geliefert. Fuer KI-Agenten, die E-Mails lesen, verstehen und beantworten muessen, ist eine Inbound-E-Mail-API der grundlegende Baustein, der autonome E-Mail-Workflows ermoeglicht.

Dieser Leitfaden erklaert, wie Inbound-E-Mail-APIs funktionieren, wie Sie eine mit AgentSend einrichten, und warum das Webhook-pro-Postfach-Modell besser fuer KI-Agenten geeignet ist als traditionelle Ansaetze wie IMAP-Abfragen oder domainweites Inbound-Parsing.

Was ist eine Inbound-E-Mail-API?

Eine Inbound-E-Mail-API ist ein Dienst, der eingehende E-Mails in Ihrem Namen annimmt und sie als strukturierte Daten an Ihre Anwendung liefert. Der typische Ablauf funktioniert so: MX-Eintraege leiten eingehende Post an die Server des API-Anbieters, der Anbieter analysiert die rohe E-Mail in einen strukturierten Payload (Absender, Betreff, Text, Anhaenge, Header) und liefert diesen Payload dann an eine Webhook-URL, die Sie konfigurieren.

Der wesentliche Vorteil gegenueber traditionellem E-Mail-Empfang ist, dass Ihre Anwendung niemals einen Mailserver verwaltet. Es gibt keine IMAP-Verbindung zu pflegen, kein POP3-Abfrageintervall zu optimieren und kein rohes MIME-Parsing zu implementieren. Sie empfangen einen sauberen JSON-Payload ueber HTTP POST, verarbeiten ihn und antworten mit einem 200-Statuscode. Das ist die gesamte Integration.

Fuer KI-Agenten ist dies wichtig, weil Agenten in Echtzeit auf eingehende E-Mails reagieren muessen. Ein Kundensupport-Agent kann nicht fuenf Minuten auf die naechste IMAP-Abfrage warten, um ein neues Ticket zu entdecken. Eine E-Mail-Webhook-API liefert die Nachricht in dem Moment, in dem sie ankommt, sodass Ihr Agent sofort mit der Verarbeitung beginnen kann.

Wie Inbound-E-Mail in AgentSend funktioniert

Die E-Mail-Empfangs-API von AgentSend basiert auf Webhooks pro Postfach. Wenn Sie ein Postfach erstellen, koennen Sie eine Webhook-URL konfigurieren, die jede eingehende Nachricht fuer dieses spezifische Postfach empfaengt. Jedes Postfach ist isoliert — es gibt keine gemeinsame Routing-Schicht, in der Sie Empfaengeradressen pruefen und an den richtigen Handler weiterleiten muessen.

Jede Webhook-Zustellung enthaelt eine HMAC-Signatur im X-AgentSend-Signature-Header. Ihre Anwendung verifiziert diese Signatur mit dem Webhook-Secret Ihres Postfachs, um zu bestätigen, dass der Payload von AgentSend gesendet wurde und waehrend der Uebertragung nicht manipuliert wurde. Wenn Ihr Endpunkt voruebergehend nicht erreichbar ist, wiederholt AgentSend die Zustellung mit exponentiellem Backoff fuer bis zu 24 Stunden.

Einrichtung von Inbound-E-Mail

Der Einstieg mit der E-Mail-Postfach-API von AgentSend erfordert zwei Schritte: Erstellen Sie ein Postfach mit einer Webhook-URL und verarbeiten Sie dann die eingehenden Payloads.

Schritt 1: Ein Postfach mit Webhook erstellen

Mit cURL:

curl -X POST https://api.agentsend.io/v1/inboxes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "support-agent",
    "webhook_url": "https://yourapp.com/webhooks/inbound-email",
    "webhook_secret": "whsec_your_secret_here"
  }'

Mit Python:

import requests

resp = requests.post(
    "https://api.agentsend.io/v1/inboxes",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "name": "support-agent",
        "webhook_url": "https://yourapp.com/webhooks/inbound-email",
        "webhook_secret": "whsec_your_secret_here",
    },
)
inbox = resp.json()
print(inbox["email"])  # support-agent@yourteam.agentsend.io

Schritt 2: Den Webhook-Payload verarbeiten

Wenn eine E-Mail ankommt, sendet AgentSend einen JSON-Payload an Ihre Webhook-URL. Hier ist ein minimaler Python-Handler mit Flask:

import hmac, hashlib
from flask import Flask, request, jsonify

app = Flask(__name__)
WEBHOOK_SECRET = "whsec_your_secret_here"

@app.route("/webhooks/inbound-email", methods=["POST"])
def handle_inbound():
    # Verify HMAC signature
    signature = request.headers.get("X-AgentSend-Signature")
    expected = hmac.new(
        WEBHOOK_SECRET.encode(),
        request.data,
        hashlib.sha256,
    ).hexdigest()

    if not hmac.compare_digest(signature, expected):
        return jsonify({"error": "invalid signature"}), 401

    payload = request.json
    sender = payload["from"]
    subject = payload["subject"]
    body = payload["body_text"]
    thread_id = payload["thread_id"]

    # Pass to your AI agent for processing
    process_with_agent(sender, subject, body, thread_id)

    return jsonify({"status": "ok"}), 200

Inbound-E-Mail-API vs traditionelle Ansaetze

Es gibt verschiedene Moeglichkeiten, E-Mails programmatisch zu empfangen. So vergleichen sich die gaengigsten Ansaetze fuer KI-Agenten-Anwendungsfaelle.

Der entscheidende Unterschied ist die Isolation. Mailgun und SendGrid arbeiten auf Domain-Ebene: Sie richten die MX-Eintraege Ihrer Domain auf deren Server, und alle eingehenden E-Mails fuer diese Domain treffen an einem einzigen Webhook-Endpunkt ein. Sie sind dafuer verantwortlich, die Empfaengeradresse in jedem Payload zu pruefen und an den richtigen Agenten weiterzuleiten. Mit AgentSend hat jedes Postfach seinen eigenen Webhook, sein eigenes Signatur-Secret und seine eigene Thread-Historie. Es gibt keine Routing-Logik zu erstellen oder zu pflegen.

E-Mail-Postfach-API: Postfaecher programmatisch erstellen

Einer der leistungsfaehigsten Aspekte einer E-Mail-Postfach-API ist die Moeglichkeit, Postfaecher spontan zu erstellen. Wenn Ihre Plattform einen neuen Kunden einbindet, einen neuen KI-Agenten bereitstellt oder einen neuen Workflow startet, koennen Sie mit einem einzigen API-Aufruf ein dediziertes Postfach erstellen. Jedes Postfach erhaelt automatisch seine eigene E-Mail-Adresse — keine DNS-Konfiguration, kein manuelles Setup, kein Warten auf Propagierung.

Dies ist besonders nuetzlich fuer Multi-Agenten-Architekturen. Ein Kundensupportsystem koennte separate Postfaecher fuer Rechnungsfragen, technischen Support und Kontoverwaltung erstellen. Jedes Postfach wird an einen spezialisierten Agenten mit eigenem Webhook-Endpunkt und eigener Konversationshistorie weitergeleitet. Die Skalierung von einem Agenten auf fuenfzig ist eine Schleife von API-Aufrufen, kein DNS-Migrationsprojekt.

Anwendungsfaelle fuer Inbound-E-Mail-APIs

Eine Inbound-E-Mail-API ermoeglicht eine Reihe autonomer Agenten-Workflows, die mit traditioneller E-Mail-Infrastruktur schwierig oder unmoeglich zu realisieren sind.

• Kundensupport-Agenten — Empfangen Support-Tickets per E-Mail, klassifizieren die Absicht, loesen haeufige Fragen automatisch und eskalieren komplexe Probleme mit vollstaendigem Thread-Kontext an menschliche Agenten.
• Forschungsagenten — Abonnieren Newsletter, empfangen Berichte und verarbeiten eingehende Informationsfluesse. Der Agent liest jede E-Mail, extrahiert relevante Daten und aktualisiert eine Wissensbasis ohne menschliches Eingreifen.
• Planungsagenten — Empfangen Besprechungsanfragen und Verfuegbarkeitsantworten per E-Mail. Der Agent analysiert den Inhalt, prueft Kalender und sendet Bestaetigungsantworten — alles ueber seine eigene dedizierte E-Mail-Adresse.
• Outbound-fokussierte Agenten mit Antwortverarbeitung — Agenten, die Kaltakquise, Follow-up-Sequenzen oder Benachrichtigungen senden, koennen Antworten ueber dasselbe Postfach empfangen und verarbeiten, wobei der vollstaendige Konversationskontext erhalten bleibt.

In jedem Fall eliminiert die Inbound-E-Mail-API die Infrastrukturlast. Ihr Agentencode konzentriert sich auf das Verstehen und Beantworten von Nachrichten, nicht auf das Aufrechterhalten von IMAP-Verbindungen, das Parsen von MIME oder das Routing von E-Mails an den richtigen Handler.