Contacten beheren via API en MCP

Het adresboek van je mailbox is volledig programmeerbaar. Met de berichten-API en MCP-tools kun je contacten maken, bewerken en verwijderen, bulksgewijs importeren en exporteren (CSV of vCard), een groot adresboek doorzoeken en personen in groepen organiseren. Dit zijn dezelfde gegevens die je webmail en CardDAV-clients zien. Een contact dat door een AI-agent wordt toegevoegd, verschijnt dus op je telefoon, en een contact dat je op je telefoon toevoegt, is zichtbaar voor de API.

Voordat je begint

• Contacten gebruiken het berichtentoken-oppervlak (/api/v1/messages/...) en de bijbehorende scopes, niet een dashboard-API-token.
• Elke aanroep is beperkt tot de eigen mailbox van het token. Een token kan alleen de eigen contacten en groepen bekijken en beheren, nooit die van een andere mailbox.
• Contacten worden binnen een mailbox op e-mailadres gekoppeld. Bij een import wordt een overeenkomend contact bijgewerkt. Als je een contact met een bestaand e-mailadres maakt, wordt dat contact ongewijzigd teruggegeven in plaats van een duplicaat te maken.
• Lijstantwoorden geven een duidelijke, leesbare verzameling velden terug (naam, e-mailadres, bedrijf, functie, telefoon, adres, verjaardag en notities). De onbewerkte CardDAV-kaart achter een gesynchroniseerd contact wordt nooit teruggegeven; je ontvangt altijd de overzichtelijke versie.
• Importeren ondersteunt CSV- en vCard-bestanden (.vcf) tot 10 MB en herkent de exportindelingen van Google Contacten, Outlook, Apple en Roundcube, inclusief bijzonderheden van UTF-8, UTF-16 en BOM.

Scopes

Contacten beheren

Basispad: /api/v1/messages/contacts

Weergeven en zoeken

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

q zoekt naar overeenkomsten in naam of e-mailadres. Resultaten worden in pagina's teruggegeven (per_page van 1 tot 100, standaard 50) met een pagination-blok (total, per_page, current_page, last_page), zodat je een groot adresboek tot het einde kunt doorlopen in plaats van na de eerste pagina te stoppen.

Een contact maken

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"
}

Alleen email is vereist. Als er al een contact met dat e-mailadres bestaat, wordt het bestaande contact ongewijzigd teruggegeven. Bij het maken ontstaat nooit een duplicaat en worden opgeslagen gegevens niet overschreven.

Bulksgewijs importeren

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

Stuur het Base64-gecodeerde bestand met format ingesteld op csv of vcf (maximaal 10 MB gedecodeerd). Het antwoord vermeldt hoeveel rijen zijn toegepast en hoeveel zijn overgeslagen omdat ze geen bruikbaar e-mailadres bevatten:

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

Kolomkoppen uit exports van Google, Outlook, Apple en Roundcube worden automatisch herkend, zodat de meeste exports zonder bewerking kunnen worden geïmporteerd.

Exporteren

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

Geeft het volledige adresboek terug als één Base64-gecodeerd bestand:

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

Gebruik format=csv voor een bestand dat geschikt is voor spreadsheets of format=vcard voor een .vcf-bestand dat je in een andere e-mailclient kunt laden.

Contactgroepen

Groepen zijn distributielijsten binnen het adresboek. Basispad: /api/v1/messages/contact-groups

Bekijken wie in een groep zit

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

Geeft de contacten van de groep terug, met dezelfde overzichtelijke velden als de contactenlijst, plus een pagination-blok en de totale contact_count van de groep. Zo kun je het lidmaatschap van een groep lezen in plaats van het blindelings te wijzigen.

Leden toevoegen of verwijderen

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

Toevoegen is idempotent: een contact dat al in de groep zit, blijft ongewijzigd. Alleen contacten die tot dezelfde mailbox behoren, kunnen worden toegevoegd. Elke aanvraag om leden toe te voegen of te verwijderen accepteert 1 tot 200 contact-ID's; grotere batches moeten over meerdere aanvragen worden verdeeld.

MCP-tools

Hetzelfde adresboek is via MCP beschikbaar voor AI-agenten, zowel via de particuliere stdio-server als via de openbare MCP-server:

Schrijvende tools vereisen nog steeds de schrijfscope van het berichtentoken. Een beheerder van een lokaal gehoste MCP kan ook expliciete goedkeuring voor schrijfacties vereisen, zodat een agent contacten kan bekijken zonder ze te kunnen wijzigen.