CRM mit KI automatisieren: Leitfaden zur Mailpro™ Contact API v3

Die meisten CRM-Daten werden zweimal eingetragen — einmal in ein Formular, einmal im Kopf, wenn Sie vergessen, das Formular zu aktualisieren. KI-Agenten schließen diese Lücke. Geben Sie Claude, GPT oder Gemini eine Kontakt-Management-API und eine klare Aufgabenbeschreibung, und sie werden Kontakte anlegen oder aktualisieren, Tags vergeben, Segmente bauen und Daten bereinigen, ohne dass ein Mensch eine Oberfläche berührt. Dieser Leitfaden zeigt exakt, wie das mit der Mailpro™ Contact API v3 geht.

Kurzfassung

• CRM v3 ist JSON-only (snake_case), authentifiziert per JWT Bearer Token.
• Token holen via POST /v3/token — gültig 365 Tage.
• Kontakte werden über UUIDs identifiziert; Listen, Tags und Felder über Integer.
• Jeder Endpunkt ist in 20+ Programmiersprachen auf unserem Entwicklerportal dokumentiert.

Warum das CRM einem KI-Agenten zugänglich machen?

Agenten als neue Erfassungsschicht

Formular-basierte CRM-Eingabe ist ein gelöstes Problem — und zwar seit 20 Jahren schlecht gelöst. Agenten erlauben das Überspringen des Formulars. Ein Nutzer tippt „neuer Lead: Alice von ShopCorp, interessiert sich für unseren Enterprise-Plan, nächste Woche nachfassen". Der Agent parst, ruft POST /v3/Contact mit strukturierten Daten auf, taggt sie „enterprise-interesse" und plant eine Nachfass-Aufgabe. Null Tastenanschläge im Formular.

Drei konkrete Szenarien

• Lead-Anreicherung. Webhook feuert aus einem Formular; der Agent reichert mit öffentlichen Quellen an, upsertet den Kontakt in Mailpro™ v3 und taggt ihn mit einem Lead-Score.
• Listen-Hygiene. Wöchentlicher Cron; der Agent prüft Listen auf doppelte E-Mails, veraltete Daten, unklassifizierte Kontakte und sortiert Tags um.
• Dynamische Segmentierung. „Verschiebe alle, die die Spring-Sale-Kampagne geöffnet haben, ins Segment warm-leads" — der Agent liest Statistiken aus v2 und ruft v3 zum Re-Taggen auf.

Einen KI-Agenten mit JWT authentifizieren

POST /v3/token mit Password-Grant

Der einfachste Weg rein:

curl -X POST "https://api.mailpro.com/v3/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password" \
  -d "[email protected]" \
  -d "password=YOUR_API_KEY"

Antwort:

{
  "access_token": "eyJhbGciOi...",
  "token_type": "bearer",
  "expires_in": 31535999,
  "refresh_token": "eyJhbGciOi..."
}

Verwahren Sie den access_token sicher (serverseitige env-Variable, Vault) und senden Sie ihn als Authorization: Bearer <token> bei jedem weiteren v3-Aufruf.

Token-Lebensdauer: 365 Tage

Mailpro™-Tokens sind per Design langlebig — KI-Agenten laufen kontinuierlich, Sie wollen keine Refresh-Stürme. Wenn Sie Rotation brauchen, nutzen Sie den Refresh-Token-Flow oder stellen Sie periodisch einen neuen Token aus.

Dritt-Grants

Wenn Sie eine Zapier-, Make- oder Microsoft-Flow-Integration bauen, nutzen Sie die passenden Grant-Typen (zapier, microsoft-flow usw.). Sie emittieren einen JWT mit ThirdParty-Rolle. Die meisten Agenten-Integrationen kommen mit dem normalen password-Grant aus.

Schritt für Schritt: „Claude, füge diesen Kontakt hinzu, tagge VIP, nimm ihn in Liste 42 auf"

Hier glänzt das Design von v3: ein Prompt, drei API-Aufrufe, keine Oberfläche.

1. Werkzeugschemata

Geben Sie Ihrem Agenten drei schmale Werkzeuge — nicht ein großes. Schmale Werkzeuge wählt das Modell zuverlässiger.

tools = [
    {
        "name": "upsert_contact",
        "description": "Legt einen Kontakt an oder aktualisiert ihn in Mailpro per E-Mail.",
        "input_schema": {
            "type": "object",
            "properties": {
                "email":      {"type": "string", "format": "email"},
                "first_name": {"type": "string"},
                "last_name":  {"type": "string"},
                "fields":     {"type": "object", "description": "Werte benutzerdefinierter Felder"}
            },
            "required": ["email"]
        }
    },
    {
        "name": "tag_contact",
        "description": "Wendet ein Tag auf einen Kontakt per UUID an.",
        "input_schema": {
            "type": "object",
            "properties": {
                "contact_id": {"type": "string"},
                "tag_name":   {"type": "string"}
            },
            "required": ["contact_id", "tag_name"]
        }
    },
    {
        "name": "add_to_list",
        "description": "Fügt einen Kontakt einer Mailpro-Liste per Listen-ID hinzu.",
        "input_schema": {
            "type": "object",
            "properties": {
                "contact_id": {"type": "string"},
                "list_id":    {"type": "integer"}
            },
            "required": ["contact_id", "list_id"]
        }
    }
]

2. Die Überlegung des Agenten

Beim Prompt „Füge Alice Zhang von ShopCorp ([email protected]) hinzu, tagge VIP, nimm sie in Liste 42 auf" schließt Claude:

1. Rufe upsert_contact mit {email: "[email protected]", first_name: "Alice", last_name: "Zhang"} auf.
2. Lies die zurückgegebene contact_id.
3. Rufe tag_contact mit {contact_id, tag_name: "VIP"} auf.
4. Rufe add_to_list mit {contact_id, list_id: 42} auf.

Drei Werkzeugaufrufe, eine Nutzerabsicht. Das ist die Agenten-Schleife.

3. In Reihenfolge ausführen

def execute_tool(name, args, token):
    base = "https://api.mailpro.com/v3"
    headers = {"Authorization": f"Bearer {token}", "Content-Type": "application/json"}

    if name == "upsert_contact":
        r = requests.post(f"{base}/Contact", headers=headers, json={
            "email": args["email"],
            "first_name": args.get("first_name"),
            "last_name": args.get("last_name"),
            "fields": args.get("fields", {})
        })
        return r.json()

    elif name == "tag_contact":
        r = requests.post(f"{base}/Tag/{args['tag_name']}/Contact",
                          headers=headers, json={"contact_id": args["contact_id"]})
        return r.json()

    elif name == "add_to_list":
        r = requests.post(f"{base}/List/{args['list_id']}/Contact",
                          headers=headers, json={"contact_id": args["contact_id"]})
        return r.json()

4. Geschäftsregeln behandeln (406-Antworten)

Genug von manueller Listenpflege? Die Mailpro-Tarife enthalten die Kontakt-API, damit Ihr KI-Agent Listen sauber und segmentiert hält — automatisch.

v3 liefert HTTP 406 bei Verletzungen von Geschäftsregeln, mit einem JSON-Body wie:

{ "Message": "A contact already exist with the same Email" }

Häufige 406-Gründe:

• Email cannot be empty
• Email has an invalid format
• A contact already exist with the same Email
• The email address was unsubscribed permanently
• One or more lists have reached the contact limit

Bringen Sie Ihrem Agenten bei, das Feld Message zu lesen und elegant zu reagieren: bei einem Duplikat den bestehenden Kontakt nachschlagen und aktualisieren, statt aufzugeben. Bei ungültiger E-Mail den Nutzer um Korrektur bitten.

Benutzerdefinierte Felder und Segmente

Benutzerdefiniertes Feld anlegen (/v3/Field)

curl -X POST "https://api.mailpro.com/v3/Field" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "lead_score", "field_type": "Number"}'

Segment mit Regeln bauen (/v3/Segment)

Segmente sind dynamisch — sie aktualisieren sich, sobald sich Kontaktdaten ändern. Agenten lieben sie: einmal anlegen, die Regeln fangen Kontakte für immer ein.

ȁeClaude, verschiebe alle Öffner der letzten Kampagne in das Segment Hot Leads"

Genau die Art Mehrschrittaufgabe, in der v3 glänzt. Der Agent:

1. Fragt v2-Statistiken ab (/stats/open), um Öffner der letzten Kampagne zu finden.
2. Ruft für jeden Öffner v3 auf, um ihn in das Segment Hot Leads aufzunehmen (über Tag oder durch Aktualisieren eines Scoring-Feldes).

Solche API-übergreifenden Workflows sind genau das, was einheitliche KI-Agenten freischalten.

Kontakte im großen Stil per Agent importieren

Wenn Ihr Agent auf ein „neue Lead-Liste"-Event reagiert (CSV-Upload, geteiltes Sheet, CRM-Export), schleifen Sie nicht einzeln. Nutzen Sie den Bulk-Import-Endpunkt:

curl -X POST "https://api.mailpro.com/v3/Import/Upload" \
  -H "Authorization: Bearer $TOKEN" \
  -F "id_list=42" \
  -F "[email protected]" \
  -F "webhook_url=https://example.com/hooks/import-done"

Der Endpunkt liefert sofort eine import_job_id. Wenn die Verarbeitung abschließt, postet Mailpro™ einen Callback an Ihre webhook_url mit Zahlen (importiert / übersprungen / ungültig). Ihr Agent nutzt den Webhook als Signal für Anschlussaktionen („Import fertig → Willkommens-Kampagne starten").

Der vollständige Agenten-Flow: Vertriebsanreicherung

Trigger: Stripe-Kunde-Webhook feuert. Ziel: Der Agent soll anreichern, ins CRM aufnehmen und eine Willkommens-E-Mail senden.

1. Anreichern. Der Agent ruft eine externe Anreicherungs-API (Clearbit, People Data Labs, eigenes Scraping) für Firmenname, Rolle, LinkedIn auf.
2. In Mailpro™ v3 upserten. POST /v3/Contact mit E-Mail + angereicherten Feldern.
3. Tag und Liste. Agent taggt den Kontakt stripe-customer und nimmt ihn in die Liste Zahlende Kunden auf.
4. Willkommens-E-Mail. Agent ruft die v2-API /send/sendmail.json mit personalisiertem Willkommen auf.

Vier Werkzeugaufrufe, zwei APIs, ein nahtloses Onboarding. Menschliche Kosten: null.

Tipps und Stolperfallen

snake_case vs PascalCase

v3 ist snake_case (first_name, list_id, contact_id). v2 ist PascalCase (FirstName, ListId). Wenn Ihr Agent mit beiden APIs spricht, erwähnen Sie das explizit im System-Prompt, damit er keine Feldnamen erfindet.

Geschäftsfehler liefern 406, nicht 400

400 = fehlerhafte Daten gesendet. 406 = Daten sind gültig, verletzen aber eine Geschäftsregel. Der Agent muss unterscheiden — 400 ist ein Bug; 406 ist ein normales Ereignis, von dem er sich erholen soll.

50 000 Anfragen pro Monat standardmäßig

v3 hat eine monatliche Anfragegrenze pro Konto. Aggressive Schleifen stoßen dagegen. Bündeln Sie mit /v3/Contact/Multiple, wo möglich. Die Grenze sehen Sie in Ihrem Konto-Dashboard.

Anwendungsfall (fiktiv): „CoraInsure" — KI-Makler, der 2.000 Leads pro Tag triagiert

CoraInsure ist ein Versicherungsmakler-Aggregator. Täglich landen 2.000 Leads aus Vergleichsportalen im Webhook. Früher säuberten und routeten zwei Data Operators jeden Lead manuell. Mit Claude an Mailpro™ v3 angeschlossen wurde der Workflow:

1. Webhook feuert → Claude bekommt den Lead-JSON.
2. Claude reichert an (validiert E-Mail, normalisiert Telefon auf E.164, leitet Versicherungsprodukt aus dem Freitext ab).
3. Claude ruft upsert_contact auf, vergibt Tags (kfz, wohn, leben), nimmt in die passende Liste auf.
4. Claude scort den Lead (0–100) und schreibt den Score ins benutzerdefinierte Feld lead_score.
5. Leads mit hohem Score lösen automatisch eine v2-Willkommens-E-Mail aus.

Die Verarbeitungszeit pro Lead sank von 6 Minuten (Mensch) auf 4 Sekunden (Agent). Die Datenqualität verbesserte sich — Claude ist strenger bei der E-Mail-Validierung als müde Menschen. Die zwei Operators wurden auf echte Makler-Aufgaben verlegt.

Nächster Schritt

Mit v3, das Ihr CRM übernimmt, und v2 für den Versand, bleibt SMS. Weiter zum SMS-Leitfaden, damit Ihr Agent den letzten Kanal bekommt. Oder zurück zum Säulen-Leitfaden.

Referenzdokumentation: CRM API v3. Preise: Mailpro-Preise.

FAQ

Unterstützt Mailpro v3 OAuth oder nur den Password-Grant?

Beides. password ist am einfachsten; client_credentials für Maschine-zu-Maschine-Flows; zapier, automateio und microsoft-flow sind dedizierte Dritt-Grants, die einen JWT mit ThirdParty-Rolle ausstellen.

Kann ich Kontakte von Mailpro v2 auf v3 migrieren?

Ja — beide APIs greifen auf dieselbe Kontaktdatenbank zu. Ein via v2 angelegter Kontakt ist über v3 sichtbar und steuerbar, und umgekehrt.

Wie funktionieren benutzerdefinierte Felder mit KI?

Feld einmal via POST /v3/Field mit Typ anlegen (Text, Number, Date, Boolean). Danach kann der Agent Werte auf Kontakten über fields im Payload setzen. Benutzerdefinierte Felder dienen auch als Personalisierungsvariablen in E-Mail-Kampagnen.

Was ist der Unterschied zwischen Liste, Tag und Segment?

Eine Liste ist eine statische Sammlung, der Sie Kontakte explizit hinzufügen. Ein Tag ist ein leichtgewichtiges Label (ein Kontakt kann mehrere haben). Ein Segment ist eine dynamische Abfrage — „alle Kontakte mit tag='VIP' und country='DE'" — die sich selbst aktualisiert, wenn sich Kontaktdaten ändern. Mehr dazu in unserem Leitfaden zur E-Mail-Zustellbarkeit.