Gestionar contactos mediante API y MCP

La libreta de direcciones de tu buzón es totalmente programable. La API de mensajes y las herramientas MCP pueden crear, editar y eliminar contactos, importar y exportar en bloque (CSV o vCard), buscar en una libreta extensa y organizar personas en grupos. Son los mismos datos que ven tu webmail y tus clientes CardDAV, por lo que un contacto añadido por un agente de IA aparece en tu teléfono, y uno añadido desde el teléfono queda visible para la API.

Antes de empezar

• Los contactos utilizan la superficie de token de mensajes (/api/v1/messages/...) y sus ámbitos, no un token de API del panel.
• Cada llamada se limita al buzón propio del token. Un token solo puede ver y gestionar sus propios contactos y grupos, nunca los de otro buzón.
• Los contactos se identifican por la dirección de correo dentro de cada buzón. Una importación actualiza un contacto coincidente. Si creas uno con un correo existente, se devuelve ese contacto sin cambios en lugar de crear un duplicado.
• Las respuestas de lista devuelven un conjunto de campos claro y legible (nombre, correo, empresa, cargo, teléfono, dirección, cumpleaños y notas). Nunca se devuelve la tarjeta CardDAV sin procesar que hay detrás de un contacto sincronizado; siempre recibes la versión ordenada.
• La importación admite archivos CSV y vCard (.vcf) de hasta 10 MB, y comprende los formatos de exportación de Contactos de Google, Outlook, Apple y Roundcube, incluidas las particularidades de UTF-8, UTF-16 y BOM.

Ámbitos

Gestionar contactos

Ruta base: /api/v1/messages/contacts

Enumerar y buscar

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

q busca coincidencias en el nombre o el correo. Los resultados se devuelven paginados (per_page entre 1 y 100, con 50 como valor predeterminado) junto con un bloque pagination (total, per_page, current_page, last_page), para que puedas recorrer una libreta extensa hasta el final en lugar de detenerte en la primera página.

Crear un contacto

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

Solo se requiere email. Si ya existe un contacto con ese correo, se devuelve el existente sin cambios. La creación nunca produce un duplicado ni sobrescribe los datos guardados.

Importar en bloque

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

Envía el archivo codificado en base64 con format establecido en csv o vcf (máximo de 10 MB una vez decodificado). La respuesta indica cuántas filas se aplicaron y cuántas se omitieron por no tener un correo utilizable:

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

Los encabezados de columnas de las exportaciones de Google, Outlook, Apple y Roundcube se reconocen automáticamente, por lo que la mayoría se importa sin necesidad de editar nada.

Exportar

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

Devuelve toda la libreta de direcciones como un único archivo codificado en base64:

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

Usa format=csv para obtener un archivo compatible con hojas de cálculo o format=vcard para obtener un .vcf que puedas cargar en otro cliente de correo.

Grupos de contactos

Los grupos son listas de distribución dentro de la libreta de direcciones. Ruta base: /api/v1/messages/contact-groups

Ver quién pertenece a un grupo

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

Devuelve los contactos del grupo, con los mismos campos ordenados que la lista de contactos, además de un bloque pagination y el contact_count total del grupo, para que puedas consultar sus miembros en vez de modificarlos a ciegas.

Añadir o quitar miembros

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

La adición es idempotente: un contacto que ya esté en el grupo se deja tal cual. Solo se pueden añadir contactos que pertenezcan al mismo buzón. Cada solicitud para añadir o quitar acepta entre 1 y 200 identificadores de contacto; los lotes más grandes deben dividirse en varias solicitudes.

Herramientas MCP

La misma libreta de direcciones está disponible para los agentes de IA mediante MCP, tanto en el servidor stdio privado como en el servidor MCP público:

Las herramientas de escritura siguen requiriendo el ámbito de escritura del token de mensajes. Un administrador de MCP alojado localmente también puede exigir aprobación explícita para las acciones de escritura, de modo que un agente pueda consultar contactos sin poder modificarlos.