Gestire i contatti tramite API e MCP

La rubrica della tua casella di posta è completamente programmabile. L'API dei messaggi e gli strumenti MCP possono creare, modificare ed eliminare contatti, eseguire importazioni ed esportazioni in blocco (CSV o vCard), cercare in una rubrica di grandi dimensioni e organizzare le persone in gruppi. Sono gli stessi dati visibili nel webmail e nei client CardDAV, quindi un contatto aggiunto da un agente IA appare sul telefono e uno aggiunto dal telefono è visibile all'API.

Prima di iniziare

• I contatti usano l'interfaccia del token dei messaggi (/api/v1/messages/...) e i relativi ambiti, non un token API del pannello.
• Ogni chiamata è limitata alla casella di posta del token. Un token può vedere e gestire soltanto i propri contatti e gruppi, mai quelli di un'altra casella.
• I contatti sono identificati dall'indirizzo email all'interno di una casella. Un'importazione aggiorna un contatto corrispondente. La creazione con un'email esistente restituisce quel contatto senza modificarlo, anziché creare un duplicato.
• Le risposte degli elenchi restituiscono un insieme di campi chiaro e leggibile (nome, email, azienda, qualifica, telefono, indirizzo, compleanno e note). La scheda CardDAV grezza dietro un contatto sincronizzato non viene mai restituita; ricevi sempre la versione ordinata.
• L'importazione accetta file CSV e vCard (.vcf) fino a 10 MB e riconosce i formati di esportazione di Contatti Google, Outlook, Apple e Roundcube, comprese le particolarità di UTF-8, UTF-16 e BOM.

Ambiti

Gestire i contatti

Percorso base: /api/v1/messages/contacts

Elencare e cercare

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

q trova corrispondenze nel nome o nell'email. I risultati vengono restituiti a pagine (per_page da 1 a 100, valore predefinito 50) con un blocco pagination (total, per_page, current_page, last_page), così puoi scorrere una rubrica di grandi dimensioni fino alla fine invece di fermarti alla prima pagina.

Creare un contatto

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

È obbligatorio soltanto email. Se esiste già un contatto con quell'email, il contatto esistente viene restituito senza modifiche. La creazione non genera mai un duplicato e non sovrascrive i dettagli salvati.

Importare in blocco

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

Invia il file codificato in base64 con format impostato su csv o vcf (massimo 10 MB dopo la decodifica). La risposta indica quante righe sono state applicate e quante sono state ignorate perché prive di un'email utilizzabile:

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

Le intestazioni delle colonne delle esportazioni di Google, Outlook, Apple e Roundcube vengono riconosciute automaticamente, quindi la maggior parte delle esportazioni può essere importata senza modifiche.

Esportare

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

Restituisce l'intera rubrica come singolo file codificato in base64:

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

Usa format=csv per un file adatto a un foglio di calcolo oppure format=vcard per un file .vcf da caricare in un altro client di posta.

Gruppi di contatti

I gruppi sono liste di distribuzione all'interno della rubrica. Percorso base: /api/v1/messages/contact-groups

Elencare i membri di un gruppo

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

Restituisce i contatti del gruppo, con gli stessi campi ordinati dell'elenco dei contatti, oltre a un blocco pagination e al contact_count totale del gruppo. Puoi quindi leggere i membri di un gruppo anziché modificarli alla cieca.

Aggiungere o rimuovere membri

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

L'aggiunta è idempotente: un contatto già presente nel gruppo rimane invariato. È possibile aggiungere soltanto contatti appartenenti alla stessa casella di posta. Ogni richiesta di aggiunta o rimozione accetta da 1 a 200 ID contatto; i gruppi più grandi devono essere suddivisi in più richieste.

Strumenti MCP

La stessa rubrica è disponibile agli agenti IA tramite MCP, sia sul server stdio privato sia sul server MCP pubblico:

Gli strumenti di scrittura richiedono comunque l'ambito di scrittura del token dei messaggi. Un amministratore MCP in hosting locale può anche richiedere un'approvazione esplicita per le azioni di scrittura, così un agente può consultare i contatti senza poterli modificare.