Transaktions-E-Mail-API für KI-Agenten: Leitfaden Mailpro™ v2

Wenn Sie unseren Leitfaden zu KI-Agenten und den Mailpro™ APIs gelesen haben, kennen Sie das Prinzip: Das Modell entscheidet, Ihr Code versendet. Dieser Artikel geht tief in eine einzige API, die Mailpro™ Email API v2, und zeigt ein funktionierendes Setup für Transaktions-E-Mails und Kampagnen, gesteuert von Claude, GPT oder jedem LLM mit Tool Calling – mit den genauen Endpoints und Parametern.

Kurz gesagt

• Basis-URL https://api.mailpro.com/v2, Antworten in JSON, OAuth-2.0-Bearer-Token (oder die bisherige Kombination IdClient + ApiKey).
• Eine E-Mail an eine Person: POST /send/sendmail.json. Eine gespeicherte Vorlage an eine ganze Liste: POST /send/campaign.json.
• Verfolgen Sie jede Transaktions-E-Mail mit GET /send/{IdSingleSend}/status.json oder über die Webhooks email.delivered / email.bounced.
• Importieren Sie Kontakte gesammelt aus einem Agenten mit POST /import/upload.json (CSV oder XLSX, bis 50 MB).

KI-gesteuerte E-Mails: Welche Anwendungsfälle lohnen sich?

Intelligente Bestellbestätigungen

Eine Standardbestätigung ist eine Vorlage. Ein Agent kann eine persönliche Notiz ergänzen ("Danke, dass Sie sich für das Blue XL entschieden haben, den Favoriten unserer Kunden") sowie passende Empfehlungen, und sie dann über die API versenden. Sie behalten die Zuverlässigkeit einer strukturierten Vorlage und gewinnen die Wärme einer persönlich geschriebenen Nachricht.

Automatische Vorsortierung im Support

Geht ein Ticket ein, ordnet der Agent es ein, entwirft eine Antwort und versendet sie, wenn er sich sicher ist und das Thema auf einer freigegebenen Liste steht. Alles andere geht samt Entwurf an einen Menschen.

Zusammenfassungen statt E-Mail-Flut

Der Agent liest die Ereignisse eines Tages (Rechnungen, Anmeldungen, Warnungen) und verschickt um 18 Uhr eine einzige Übersicht: "Heute: 12 bezahlt, 3 überfällig, 2 zu prüfen." Eine E-Mail, kein Rauschen. Die API kümmert sich um die Zustellung, das Modell um die Zusammenfassung.

Wie richten Sie die Email API v2 in 5 Minuten ein?

1. Zugangsdaten anlegen

Gehen Sie in Ihrem Mailpro™ Konto zu Settings → API access. Legen Sie für einen Agenten einen OAuth-Client an und fordern Sie nur die Scopes an, die er braucht, in der Regel email:send und email:read. Die bisherigen Zugangsdaten IdClient (numerisch) und ApiKey (GUID) funktionieren ebenfalls, sind aber nicht auf Scopes beschränkt – behalten Sie sie deshalb Ihren eigenen Back-End-Skripten vor.

2. Verbindung prüfen

curl -H "Authorization: Bearer ACCESS_TOKEN" \
  https://api.mailpro.com/v2/account/credits.json

Sie sollten Ihr verbleibendes E-Mail-Guthaben als JSON erhalten. Ein 401 bedeutet, dass Token oder Schlüssel falsch sind; ein 403 insufficient_scope bedeutet, dass dem Token account:read fehlt.

3. Absender-ID ermitteln

E-Mails werden von einer verifizierten Absenderadresse versendet. GET /senderEmail/list.json liefert diese Adressen mit ihren IDs; diese ID übergeben Sie als IDEmailExp.

Schritt für Schritt: Claude eine Transaktions-E-Mail senden lassen

Das Beispiel nutzt Claude von Anthropic, doch dasselbe Muster funktioniert mit OpenAI Function Calling oder Gemini Tool Use: Das SDK ändert sich, die Architektur nicht.

1. Das Tool definieren

tools = [{
  "name": "send_transactional_email",
  "description": "Sendet eine E-Mail an einen Kunden über Mailpro.",
  "input_schema": {
    "type": "object",
    "properties": {
      "to":      {"type": "string"},
      "subject": {"type": "string"},
      "html":    {"type": "string", "description": "Vollständiger HTML-Inhalt"}
    },
    "required": ["to", "subject", "html"]
  }
}]

2. Den System-Prompt schreiben

Du hilfst Customer-Success-Mitarbeitern, Follow-up-E-Mails zu schreiben und zu versenden.
Rufe send_transactional_email erst auf, nachdem der Mensch bestätigt hat.
Schreibe knapp und freundlich und füge immer einen klaren Call-to-Action-Link ein.

3. Den Aufruf an /send/sendmail ausführen

import requests

def send_transactional_email(args, token, sender_id):
    r = requests.post(
        "https://api.mailpro.com/v2/send/sendmail.json",
        headers={"Authorization": f"Bearer {token}"},
        data={
            "IDEmailExp": sender_id,       # aus /senderEmail/list
            "EmailData":  args["to"],      # E-Mail,Feld1,Feld2...
            "Subject":    args["subject"],
            "BodyHTML":   args["html"],
            "ActivateStatistics": "true",  # Öffnungen und Klicks erfassen
        },
    )
    r.raise_for_status()
    return r.json()   # {"SingleSend": {"IdSingleSend": 8001, ...}}

Nützliche optionale Felder: DatePlanned (ISO 8601), um den Versand zu planen statt sofort zu senden, ReplyTo, BodyText für eine Nur-Text-Version sowie attachments. Geben Sie das JSON als Tool-Ergebnis an das Modell zurück, damit es dem Nutzer mitteilen kann, dass die E-Mail unterwegs ist.

Sie binden Transaktions-E-Mails an? Die automatischen E-Mails von Mailpro gehen bei jedem Auslöser sofort raus — Belege, Bestätigungen, Warnungen — mit einer Zustellung, auf die Sie sich verlassen können.

4. Zustellung bestätigen

GET /send/8001/status.json liefert delivered, bounced (mit BounceType und dem DiagCode des Servers), deferred, sent, scheduled oder queued. Mit delivered können Sie etwa fünf Minuten nach der Übergabe rechnen. Für Rückmeldungen in Echtzeit abonnieren Sie die Webhooks email.delivered und email.bounced, statt den Status ständig abzufragen.

Kampagnen: Der Agent bereitet vor, ein Mensch drückt auf Senden

Für einen Versand an eine ganze Liste arbeitet der Agent mit einer gespeicherten Vorlage statt mit rohem HTML:

curl -X POST https://api.mailpro.com/v2/send/campaign.json \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -d "IDMessage=55" \
  -d "IDEmailExp=201" \
  -d "ListId=101" \
  -d "Campaign=1" \
  -d "TitleCampaign=April newsletter" \
  -d "DatePlanned=2026-05-01T09:00:00"

DatePlanned ist optional: Lassen Sie es weg, geht die Kampagne sofort raus. Ein bewährtes Muster: Der Agent wählt Liste, Vorlage und Versandzeit passend zur Zeitzone der Zielgruppe und legt den Plan dann einem Menschen zur Freigabe vor. Geplante Kampagnen lassen sich weiterhin mit PATCH /send/{IdSend}/reschedule.json verschieben oder mit POST /send/{IdSend}/cancel.json abbrechen.

Personalisierung mit Feldern

Bei /send/sendmail nimmt EmailData die Adresse gefolgt von bis zu 25 Werten auf ([email protected],Alice,Dupont,Paris), die die Personalisierungsfelder der Vorlage füllen. Bei Kampagnen stammen die Felder aus den Daten jedes Kontakts in der Liste. Der Agent muss das Feld nur in sein HTML setzen; die API füllt es für jeden Empfänger.

Kontakte gesammelt aus einem Agenten-Upload importieren

Wenn der erste Schritt eines Workflows lautet "Füge diese 500 neuen Leads hinzu", machen Sie keine 500 API-Aufrufe. Senden Sie eine einzige Datei:

curl -X POST https://api.mailpro.com/v2/import/upload.json \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -F "ListId=42" \
  -F "[email protected]" \
  -F "WebhookUrl=https://example.com/hooks/import-done"

Die Datei muss UTF-8-kodiert sein und eine Kopfzeile mit Email enthalten; weitere Spalten werden den benutzerdefinierten Feldern der Liste zugeordnet. Der Endpoint gibt sofort eine ImportJobId zurück, verarbeitet die Datei im Hintergrund und ruft Ihre WebhookUrl mit der Anzahl importierter, übersprungener und ungültiger Zeilen auf.

Stolperfallen und Tipps

• Abgemeldete Adressen werden abgelehnt. Die API antwortet mit "Email address unsubscribed." und dem Status 400. Sagen Sie dem Agenten, dass das endgültig ist und kein Fehler, den er wiederholen sollte.
• Behalten Sie das Guthaben im Blick. "Not enough credit available." kommt als 403 zurück. Abonnieren Sie den Webhook credits.low, damit ein Mensch rechtzeitig nachlädt, bevor der Agent an die Grenze stößt.
• Achten Sie auf das Anfragekontingent. API-Aufrufe zählen gegen ein monatliches Kontingent, das sich Email-, CRM- und SMS-API teilen (GET /account/limits.json). Begrenzen Sie die Tool-Aufrufe pro Konversation und warten Sie bei 429 mit steigenden Abständen, bevor Sie es erneut versuchen.
• Bleiben Sie bei JSON. XML wird mit dem Suffix .xml unterstützt, doch JSON ist für die Tool-Ausgabe eines LLM einfacher.
• Authentifizieren Sie Ihre Domain. Auch personalisierte, von KI geschriebene E-Mails brauchen SPF, DKIM und DMARC, um im Posteingang zu landen; mehr dazu in unserem Leitfaden zur E-Mail-Zustellbarkeit.

Fallstudie (fiktiv): "NovaFit", eine Fitnessstudio-Kette mit KI-geschriebenen Kurserinnerungen

NovaFit betreibt 40 Fitnessstudios und verschickt 24 Stunden vor jedem gebuchten Kurs eine Erinnerung. Früher bestanden die Erinnerungen aus einer einzigen Vorlage ("Hallo Anna, Ihr Yogakurs ist morgen um 7 Uhr"). Das Team hat Claude hinter das Buchungssystem geschaltet: Für jede Erinnerung liest der Agent die jüngste Teilnahme des Mitglieds und die Kursart, schreibt eine persönliche Zeile ("Letzte Woche haben Sie die Kriegerpose eine volle Minute gehalten – bereit für die nächste Stufe?") und versendet die E-Mail mit /send/sendmail. Bounces kommen über den Webhook email.bounced zurück und werden an den Empfang gemeldet. Die Öffnungsrate der Erinnerungen stieg von 46 % auf 63 %, die Teilnahme um 8 Prozentpunkte – bei unverändertem E-Mail-Volumen.

Nächste Schritte

Die Email API v2 übernimmt den Versand. Wenn Ihr Agent außerdem Kontakte, Tags, Segmente und benutzerdefinierte Felder verwalten soll, lesen Sie unseren Leitfaden zur CRM API v3 für KI. Für Textnachrichten siehe SMS mit einem KI-Agenten versenden. Sie wägen eine verwaltete Plattform gegen einen reinen Versanddienst ab? Lesen Sie unseren Leitfaden zu den besten Amazon-SES-Alternativen. Vollständige Referenz: die Dokumentation der Email API v2.