Gerenciar contatos pela API e pelo MCP

O catálogo de endereços da sua caixa de correio é totalmente programável. A API de mensagens e as ferramentas MCP podem criar, editar e excluir contatos, importar e exportar em massa (CSV ou vCard), pesquisar em um catálogo grande e organizar pessoas em grupos. Esses são os mesmos dados vistos pelo seu webmail e pelos clientes CardDAV. Assim, um contato adicionado por um agente de IA aparece no seu celular, e um contato adicionado no celular fica visível para a API.

Antes de começar

• Os contatos usam a superfície de token de mensagens (/api/v1/messages/...) e seus escopos, não um token de API do painel.
• Cada chamada fica restrita à caixa de correio do próprio token. Um token só pode ver e gerenciar seus próprios contatos e grupos, nunca os de outra caixa de correio.
• Os contatos são identificados pelo endereço de e-mail dentro de uma caixa de correio. Uma importação atualiza um contato correspondente. Criar um contato com um e-mail existente retorna esse contato sem alterações em vez de gerar uma duplicata.
• As respostas de listagem retornam um conjunto de campos organizado e fácil de ler (nome, e-mail, empresa, cargo, telefone, endereço, aniversário e notas). O cartão CardDAV bruto por trás de um contato sincronizado nunca é retornado; você sempre recebe a versão organizada.
• A importação aceita arquivos CSV e vCard (.vcf) de até 10 MB e entende os formatos de exportação do Google Contatos, Outlook, Apple e Roundcube, incluindo as particularidades de UTF-8, UTF-16 e BOM.

Escopos

Gerenciar contatos

Caminho-base: /api/v1/messages/contacts

Listar e pesquisar

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

q procura correspondências no nome ou no e-mail. Os resultados são paginados (per_page de 1 a 100, com padrão 50) e incluem um bloco pagination (total, per_page, current_page, last_page). Assim, você pode percorrer um catálogo de endereços grande até o fim em vez de parar na primeira página.

Criar um contato

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

Apenas email é obrigatório. Se já existir um contato com esse e-mail, o contato existente será retornado sem alterações. A criação nunca gera uma duplicata nem substitui os detalhes salvos.

Importar em massa

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

Envie o arquivo codificado em base64 com format definido como csv ou vcf (máximo de 10 MB após a decodificação). A resposta informa quantas linhas foram aplicadas e quantas foram ignoradas por não terem um e-mail utilizável:

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

Os cabeçalhos de coluna das exportações do Google, Outlook, Apple e Roundcube são reconhecidos automaticamente, então a maioria das exportações é importada sem qualquer edição.

Exportar

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

Retorna todo o catálogo de endereços como um único arquivo codificado em base64:

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

Use format=csv para um arquivo adequado a planilhas ou format=vcard para um .vcf que possa ser carregado em outro cliente de e-mail.

Grupos de contatos

Os grupos são listas de distribuição dentro do catálogo de endereços. Caminho-base: /api/v1/messages/contact-groups

Listar quem está em um grupo

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

Retorna os contatos do grupo, com os mesmos campos organizados da lista de contatos, além de um bloco pagination e do contact_count total do grupo. Assim, você pode consultar os membros do grupo em vez de alterá-los sem conhecer seu conteúdo.

Adicionar ou remover membros

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

A adição é idempotente: um contato que já está no grupo permanece como está. Só é possível adicionar contatos que pertençam à mesma caixa de correio. Cada solicitação de adição ou remoção aceita entre 1 e 200 IDs de contato; lotes maiores precisam ser divididos em várias solicitações.

Ferramentas MCP

O mesmo catálogo de endereços está disponível para agentes de IA pelo MCP, tanto no servidor stdio privado quanto no servidor MCP público:

As ferramentas de escrita ainda exigem o escopo de escrita do token de mensagens. Um administrador de MCP hospedado localmente também pode exigir aprovação explícita para ações de escrita, permitindo que um agente consulte contatos sem poder alterá-los.