Kontakte über API und MCP verwalten

Das Adressbuch Ihres Postfachs ist vollständig programmierbar. Die Nachrichten-API und die MCP-Tools können Kontakte erstellen, bearbeiten und löschen, Massenimporte und -exporte durchführen (CSV oder vCard), ein großes Adressbuch durchsuchen und Personen in Gruppen organisieren. Es handelt sich um dieselben Daten, die Ihr Webmail und Ihre CardDAV-Clients sehen. Ein von einem KI-Agenten hinzugefügter Kontakt erscheint daher auf Ihrem Smartphone, und ein auf dem Smartphone hinzugefügter Kontakt ist für die API sichtbar.

Bevor Sie beginnen

• Kontakte verwenden die Oberfläche für Nachrichten-Token (/api/v1/messages/...) und deren Scopes, nicht ein Dashboard-API-Token.
• Jeder Aufruf ist auf das eigene Postfach des Tokens beschränkt. Ein Token kann nur die eigenen Kontakte und Gruppen sehen und verwalten, niemals die eines anderen Postfachs.
• Kontakte werden innerhalb eines Postfachs anhand ihrer E-Mail-Adresse zugeordnet. Ein Import aktualisiert einen übereinstimmenden Kontakt. Wenn ein Kontakt mit einer vorhandenen E-Mail-Adresse erstellt wird, wird der bestehende Kontakt unverändert zurückgegeben, statt ein Duplikat anzulegen.
• Listenantworten liefern einen übersichtlichen, leicht lesbaren Satz von Feldern (Name, E-Mail, Unternehmen, Berufsbezeichnung, Telefon, Adresse, Geburtstag und Notizen). Die unbearbeitete CardDAV-Karte hinter einem synchronisierten Kontakt wird nie zurückgegeben; Sie erhalten immer die aufbereitete Version.
• Der Import akzeptiert CSV- und vCard-Dateien (.vcf) bis zu 10 MB und versteht die Exportformate von Google Kontakte, Outlook, Apple und Roundcube, einschließlich Besonderheiten bei UTF-8, UTF-16 und BOM.

Scopes

Kontakte verwalten

Basispfad: /api/v1/messages/contacts

Auflisten und durchsuchen

GET /api/v1/messages/contacts?q=alice&per_page=50&page=1
Scope: messages:read

q sucht nach Übereinstimmungen in Name oder E-Mail-Adresse. Die Ergebnisse werden seitenweise zurückgegeben (per_page von 1 bis 100, Standardwert 50) und enthalten einen pagination-Block (total, per_page, current_page, last_page). So können Sie ein großes Adressbuch bis zum Ende durchlaufen, statt nach der ersten Seite anzuhalten.

Kontakt erstellen

POST /api/v1/messages/contacts
Scope: messages:write
{
  "email": "ada@example.com",
  "name": "Ada Lovelace",
  "company": "Analytical Engines",
  "job_title": "Mathematician",
  "phone": "+1 555 0100",
  "address": "London",
  "birthday": "1815-12-10",
  "notes": "Met at the conference"
}

Nur email ist erforderlich. Wenn bereits ein Kontakt mit dieser E-Mail-Adresse vorhanden ist, wird der bestehende Kontakt unverändert zurückgegeben. Bei der Erstellung wird nie ein Duplikat angelegt oder ein gespeichertes Detail überschrieben.

Massenimport

POST /api/v1/messages/contacts/import
Scope: messages:write
{
  "content_base64": "<base64 of your .csv or .vcf file>",
  "format": "csv"
}

Senden Sie die Base64-codierte Datei mit format auf csv oder vcf gesetzt (maximal 10 MB decodiert). Die Antwort teilt Ihnen mit, wie viele Zeilen übernommen und wie viele wegen einer fehlenden nutzbaren E-Mail-Adresse übersprungen wurden:

{ "imported": 128, "skipped": 3 }

Spaltenüberschriften aus Exporten von Google, Outlook, Apple und Roundcube werden automatisch erkannt, sodass die meisten Exporte ohne Bearbeitung importiert werden können.

Exportieren

GET /api/v1/messages/contacts/export?format=vcard
Scope: messages:read

Gibt das gesamte Adressbuch als einzelne Base64-codierte Datei zurück:

{ "format": "vcard", "content_base64": "..." }

Verwenden Sie format=csv für eine tabellenkalkulationsfreundliche Datei oder format=vcard für eine .vcf-Datei, die Sie in einen anderen E-Mail-Client laden können.

Kontaktgruppen

Gruppen sind Verteilerlisten innerhalb des Adressbuchs. Basispfad: /api/v1/messages/contact-groups

Mitglieder einer Gruppe auflisten

GET /api/v1/messages/contact-groups/42/members?per_page=50&page=1
Scope: messages:read

Gibt die Kontakte der Gruppe mit denselben aufbereiteten Feldern wie die Kontaktliste zurück, ergänzt um einen pagination-Block und den gesamten contact_count der Gruppe. So können Sie die Mitgliedschaft einer Gruppe lesen, statt sie blind zu ändern.

Mitglieder hinzufügen oder entfernen

POST /api/v1/messages/contact-groups/42/members
Scope: messages:write
{ "contact_ids": [11, 12, 13] }

Das Hinzufügen ist idempotent: Ein Kontakt, der bereits zur Gruppe gehört, bleibt unverändert. Nur Kontakte, die demselben Postfach angehören, können hinzugefügt werden. Jede Anfrage zum Hinzufügen oder Entfernen akzeptiert zwischen 1 und 200 Kontakt-IDs; größere Mengen müssen auf mehrere Anfragen aufgeteilt werden.

MCP-Tools

Dasselbe Adressbuch steht KI-Agenten über MCP zur Verfügung, sowohl über den privaten stdio-Server als auch über den öffentlichen MCP-Server:

Schreibende Tools benötigen weiterhin den Schreib-Scope des Nachrichten-Tokens. Ein Administrator eines lokal gehosteten MCP kann außerdem eine ausdrückliche Genehmigung für Schreibaktionen verlangen, sodass ein Agent Kontakte durchsuchen kann, ohne sie ändern zu dürfen.