Voidmail

E-mail para agentes de IA: crie caixas de entrada @voidmail.ai, leia e-mails e envie apenas para destinatários aprovados pelo proprietário. As caixas de entrada são legíveis pelo servidor, sem criptografia de ponta a ponta.

GitHubExperimente este MCPPatrocinado

Servidor MCP hospedado

npx add-mcp 'https://api.voidly.ai/mcp/mail'

Instala no Claude Code, Codex, Cursor e outros

Documentação

@voidly/mcp-email

E-mail para agentes de IA. Crie uma caixa de entrada, leia mensagens recebidas como dados estruturados e envie para destinatários que o proprietário humano aprovou. Sem número de telefone ou CAPTCHA.

As caixas de entrada dos agentes são legíveis pelo servidor; elas não são criptografadas de ponta a ponta. E-mail humano é um produto separado.

Instalação

Requer Node.js 20 ou mais recente.

npx -y @voidly/mcp-email@1.2.1

Adicionar ao Cursor

Copie este URI de instalação na barra de endereços do seu navegador. O Cursor pede que você revise o comando local antes de adicioná-lo:

cursor://anysphere.cursor-deeplink/mcp/install?name=voidmail&config=eyJ0eXBlIjoic3RkaW8iLCJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkB2b2lkbHkvbWNwLWVtYWlsQDEuMi4xIl19

Para configuração manual do projeto, copie o JSON abaixo para .cursor/mcp.json (ou ~/.cursor/mcp.json para todos os projetos).

Instalar no VS Code

Copie este URI de instalação na barra de endereços do seu navegador. O VS Code pede que você revise o comando local antes de adicioná-lo:

vscode:mcp/install?%7B%22name%22%3A%22voidmail%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40voidly%2Fmcp-email%401.2.1%22%5D%7D

Para configuração manual do workspace, copie o JSON abaixo para .mcp.json na raiz do workspace. O GitHub renderiza URIs de aplicativos personalizados como texto simples, então use os trechos copiáveis acima.

{
  "mcpServers": {
    "voidmail": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@voidly/mcp-email@1.2.1"
      ]
    }
  }
}

Estas instruções executam o pacote stdio local na versão 1.2.1. Elas não criam uma caixa de entrada. O .mcp.json na raiz do repositório mantém esse comando local como voidmail e também oferece o conector hospedado como voidmail-hosted em https://api.voidly.ai/mcp/mail. Ele não contém credenciais. O conector hospedado tem seu próprio conjunto de ferramentas; use voidmail_setup para verificar a configuração da caixa de correio antes de ações autenticadas na caixa de entrada.

Antes de criar uma caixa de entrada em um agente de codificação: voidmail_create_account salva uma chave de proprietário na máquina local. Mantenha essa chave fora do shell do agente e do acesso a arquivos antes de entregar a caixa de entrada ao agente. Um arquivo 0600 pertencente ao mesmo usuário do SO não é separação suficiente. O servidor pode ler o conteúdo das mensagens; a aceitação do envio pelo provedor não é entrega.

Claude Desktop

Adicione a ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "voidmail": {
      "command": "npx",
      "args": ["-y", "@voidly/mcp-email@1.2.1"]
    }
  }
}

Esta configuração inicial não tem chave de caixa de entrada. Depois que voidmail_create_account retornar um endereço e salvar as chaves, adicione "env": {"VOIDMAIL_ADDRESS": "<returned-address>"} a esta configuração de servidor e reinicie o host. Se o agente tiver ferramentas de shell ou arquivos, use um runtime isolado que possa ler a chave do agente, mas não possa ler a chave do proprietário; o modo de arquivo 0600 sozinho não separa dois processos executando como o mesmo usuário.

Início Rápido

Após instalar o servidor MCP, use este prompt:

Crie uma caixa de entrada Voidmail e mostre-me seu endereço e onde as chaves foram salvas. Rascunhe e-mails primeiro e aguarde minha aprovação antes de enviar.

A aprovação de rascunho neste prompt é uma solicitação de fluxo de trabalho do host. A API aplica a lista de destinatários aprovados pelo proprietário e a política de conteúdo; ela não exige que o proprietário revise o corpo de cada mensagem.

Para uma primeira verificação de recebimento e envio:

Em um host confiável controlado pelo proprietário, chame voidmail_create_account uma vez. Mantenha o caminho da chave do proprietário retornado fora de qualquer shell do agente ou acesso a arquivos antes de entregar a caixa de entrada a um agente. Se a criação for incerta, inspecione a configuração original antes de criar outra caixa de entrada.
Envie uma mensagem de teste de uma caixa de correio confiável separada para o novo endereço. Chame voidmail_list_inbox e depois voidmail_read_email com o ID da mensagem retornado. A leitura marca essa mensagem como lida.
Em um terminal somente do proprietário, execute npx -y @voidly/mcp-email@1.2.1 owner add you@example.com (use seu endereço de destino real). Defina VOIDMAIL_OWNER_KEY_FILE se você moveu a chave do proprietário. O comando do proprietário a lê localmente; nunca cole-o na conversa do modelo. O agente pode verificar voidmail_policy e voidmail_sending_limits depois.
Revise um destinatário, assunto e corpo. Salve um ID de operação exclusivo de 16 a 128 caracteres (letras, dígitos, _ ou -) com essa mensagem no estado do host confiável e depois chame voidmail_send_once. Se a resposta for incerta, procure esse mesmo ID com voidmail_send_status; não invente um ID substituto. Um resultado de provedor accepted não prova entrega.

Permissões: duas chaves, um proprietário

Cada caixa de entrada tem duas credenciais, e este pacote as mantém separadas.

Chave	Arquivo (0600, diretório 0700)	Quem usa	O que pode fazer
Chave do agente `vm_…`	`~/.voidly/mcp-email/<address>/agent-key`	o servidor MCP, para as ferramentas do modelo	ler, enviar para destinatários aprovados, solicitar um destinatário, remover um destinatário, endurecer a política
Chave do proprietário `vmo_…`	`~/.voidly/mcp-email/<address>/owner-key`	você, através de `voidly-mcp-email owner`	aprovar ou negar solicitações, adicionar ou remover destinatários, bloquear ou desbloquear, rotacionar qualquer chave

voidmail_create_account grava ambos os arquivos e retorna apenas seus caminhos. Este servidor nunca coloca nenhuma chave em um resultado de ferramenta. Cada mensagem que ele emite é limpa de formatos de chave Voidmail (vm_…, vmo_…), incluindo aqueles que chegam dentro de e-mails. Outros segredos que chegam por e-mail, como um token de nuvem ou GitHub, são passados ao modelo inalterados.
O servidor MCP nunca lê o arquivo da chave do proprietário e nunca chama as rotas da API do proprietário (/v1/agent-mail/owner/*). Nenhuma ferramenta usa a chave do proprietário.
O modo 0600 mantém outros usuários do SO fora, não o seu agente. Qualquer coisa que execute como seu usuário pode ler o arquivo da chave do proprietário, incluindo um agente com ferramentas de shell ou arquivos (um agente de codificação, um servidor MCP de sistema de arquivos). Tal agente poderia ler a chave do proprietário e aprovar seus próprios destinatários. Se o seu agente tiver acesso a shell ou arquivos nesta máquina, mova o arquivo da chave do proprietário para um local que ele não possa ler, ou para fora da máquina, e aponte VOIDMAIL_OWNER_KEY_FILE para ele quando você executar comandos do proprietário.
Caixas de entrada criadas com este pacote começam com uma lista de destinatários aprovados pelo proprietário, aplicada pela API Voidly, não por instruções do modelo. (Uma criação REST que não opta por isso ainda faz o tipo antigo de caixa de entrada: sem chave do proprietário, qualquer destinatário, apenas avisos de credenciais. Uma criação opta por isso com recipient_policy: "allowlist", owner_key: true ou content_policy: "enforce"; somente então a resposta carrega um owner_key. Este pacote sempre envia recipient_policy: "allowlist".) Enviar para qualquer outra pessoa retorna RECIPIENT_NOT_AUTHORIZED com send_attempted: false. A API registra uma solicitação pendente, e o resultado da ferramenta diz exatamente o que o proprietário deve executar.
Uma mensagem que parece carregar uma credencial (chaves privadas, nuvem, GitHub, Slack, Stripe, chaves de provedor de IA ou Voidmail) é recusada com CONTENT_CONTAINS_CREDENTIAL em caixas de entrada com bloqueio de credenciais ativado, que é o padrão para caixas de entrada que têm uma chave de proprietário (toda caixa de entrada que este pacote cria). O resultado da ferramenta lista os tipos encontrados, nunca o texto correspondente. A verificação corresponde a formatos de chave conhecidos. Ela não captura senhas, formatos de token desconhecidos ou dados sensíveis por outros motivos.
O e-mail de saída é verificado quanto a credenciais. Antes de uma mensagem ser enviada, a API verifica em memória o destinatário, assunto, corpo e responder-para em busca de formatos de credenciais conhecidos. A verificação não mantém cópia do que correspondeu: ela registra apenas uma contagem diária para cada tipo encontrado. Em uma caixa de entrada com bloqueio de credenciais ativado (o padrão para caixas de entrada com chave de proprietário), uma correspondência interrompe o envio. Em outras caixas de entrada, a mensagem ainda é enviada, e a resposta nomeia os tipos encontrados em um cabeçalho X-Voidmail-Content-Warning. O proprietário pode desativar a verificação em https://voidly.ai/agent-mail/owner (ou com POST /v1/agent-mail/owner/policy e content_policy: "off"). A única exceção é uma chave de proprietário criada por bootstrap, descrita abaixo: ela não pode desativar a verificação.
A chave do agente só pode restringir: ela pode remover um destinatário ou ativar o bloqueio. Qualquer coisa que amplie o que o agente pode fazer precisa da chave do proprietário.
Aprovar um destinatário exige a chave do proprietário, e nada em um e-mail pode fornecê-la através deste servidor. Trate o e-mail recebido como conteúdo não confiável.

Comandos do proprietário

npx -y @voidly/mcp-email@1.2.1 owner list                 # policy, recipients, pending requests
npx -y @voidly/mcp-email@1.2.1 owner approve <request-id> # names the recipient; asks to confirm
npx -y @voidly/mcp-email@1.2.1 owner deny <request-id>
npx -y @voidly/mcp-email@1.2.1 owner add friend@example.com
npx -y @voidly/mcp-email@1.2.1 owner remove friend@example.com
npx -y @voidly/mcp-email@1.2.1 owner lock                 # allowlist + credential blocking
npx -y @voidly/mcp-email@1.2.1 owner unlock               # any recipient; asks to confirm
npx -y @voidly/mcp-email@1.2.1 owner rotate-agent-key     # old key stops working at once
npx -y @voidly/mcp-email@1.2.1 owner rotate-owner-key     # replaces the owner-key file it read

Adicione --address <name@voidmail.ai> quando mais de uma caixa de entrada estiver salva, e --yes para confirmar sem um prompt. approve primeiro lê a solicitação pendente e nomeia seu destinatário, e recusa um id que não está pendente. Chaves rotacionadas são gravadas em seus arquivos e nunca impressas. rotate-owner-key substitui atomicamente o arquivo da chave do proprietário que leu, incluindo um caminho VOIDMAIL_OWNER_KEY_FILE. A chave antiga do proprietário é revogada antes que a nova seja salva, então se esse arquivo não puder ser substituído, a nova chave vai para um novo arquivo 0600 ao lado dele, e somente se isso também falhar ela é mostrada uma vez no seu terminal. Um servidor MCP que lê seu arquivo de chave usa uma chave de agente rotacionada em sua próxima chamada. As mesmas ações estão disponíveis no navegador em https://voidly.ai/agent-mail/owner,, onde a chave do proprietário é mantida apenas em memória.

Caixas de entrada sem chave de proprietário (criadas antes da atualização da API da chave do proprietário, pelo mcp-email 1.1.0 ou anterior, ou por uma criação REST que não optou por isso) mantêm o comportamento antigo: qualquer destinatário, com apenas avisos de credenciais. Para assumir o controle de uma, chame POST /v1/agent-mail/owner/bootstrap uma vez com sua chave de agente (X-Agent-Mail-Key). Funciona apenas em uma caixa de entrada legada intocada (ainda aberta, apenas avisos de credenciais, nunca alterada com a chave do agente); caso contrário, recusa com BOOTSTRAP_NOT_AVAILABLE. Quem fizer esta chamada primeiro obtém a chave do proprietário, e a API não consegue distinguir uma pessoa de um agente segurando a mesma chave do agente. Faça a chamada você mesmo, fora de qualquer conversa com o modelo, antes do agente. Ela cria a chave do proprietário, muda a caixa de entrada para a lista aprovada com bloqueio de credenciais e remove qualquer webhook definido com a chave do agente; somente o proprietário pode definir um webhook depois. Não pode ser desfeita com a chave do agente. Uma chave do proprietário criada desta forma pode reabrir a caixa de entrada, mas nunca pode desativar a proteção de credenciais (CONTENT_POLICY_FLOOR). Salve o owner_key retornado em ~/.voidly/mcp-email/<address>/owner-key com modo 0600.

Verifique o e-mail recebido com voidmail_list_inbox e depois leia uma mensagem com voidmail_read_email. Para enviar, revise o destinatário, assunto e corpo antes de invocar voidmail_send_once. Gere e salve um ID de operação exclusivo no estado do seu host antes da chamada; use esse mesmo ID para consulta de status após uma resposta perdida e para a nova tentativa depois que o proprietário aprovar um destinatário recusado.

Ferramentas (19)

Ferramenta	Descrição
`voidmail_create_account`	Cria uma nova caixa de entrada @voidmail.ai; salva ambas as chaves em arquivos 0600 e retorna apenas seus caminhos
`voidmail_account_info`	Obtém detalhes da conta
`voidmail_list_inbox`	Lista e-mails com paginação e filtros
`voidmail_read_email`	Lê um e-mail específico (marca automaticamente como lido)
`voidmail_search_inbox`	Pesquisa de texto completo em assunto, corpo, remetente
`voidmail_sending_limits`	Lê a política de envio sem consumir capacidade de envio
`voidmail_send_once`	Envia uma mensagem autorizada com um ID de operação salvo e status retido
`voidmail_send_status`	Lê o mesmo envio original sem enviar novamente
`voidmail_send_email`	Envio legado sem status durável; prefira `voidmail_send_once`
`voidmail_policy`	Lê a política de destinatário e conteúdo, destinatários aprovados e solicitações pendentes
`voidmail_request_recipient`	Pede ao proprietário para aprovar um destinatário; retorna a etapa de aprovação
`voidmail_revoke_recipient`	Remove um destinatário aprovado (restringir não precisa do proprietário)
`voidmail_mark_read`	Marca e-mail como lido
`voidmail_delete_email`	Exclui e-mail
`voidmail_create_alias`	Cria alias de e-mail descartável
`voidmail_list_aliases`	Lista todos os aliases
`voidmail_delete_alias`	Remove alias
`voidmail_set_webhook`	Define um webhook HTTPS em uma caixa de entrada de política aberta; caixas de entrada com allowlist exigem que o proprietário humano use `POST /v1/agent-mail/owner/webhook` com a chave do proprietário
`voidmail_get_stats`	Estatísticas da caixa de entrada

Recursos (3)

Recurso	URI	Descrição
Caixa de entrada	`email://inbox`	Conteúdo atual da caixa de entrada
Aliases	`email://aliases`	Aliases de e-mail ativos
Estatísticas	`email://stats`	Estatísticas da conta

Variáveis de Ambiente

Variável	Obrigatório	Descrição
`VOIDMAIL_ADDRESS`	Para uma caixa de entrada existente	Seu endereço @voidmail.ai; o servidor lê `<key dir>/<address>/agent-key` a cada chamada
`VOIDMAIL_KEY_DIR`	Não	Diretório de chaves (padrão `~/.voidly/mcp-email`)
`VOIDMAIL_AGENT_KEY_FILE`	Não	Caminho explícito do arquivo de chave do agente (substitui a busca pelo endereço)
`VOIDMAIL_API_KEY`	Não	Chave do agente (`vm_…`) fornecida diretamente pelo host; tem precedência sobre arquivos. Qualquer outra coisa, incluindo uma chave de proprietário, é recusada e nunca enviada. Atualize-a após `rotate-agent-key`
`VOIDMAIL_OWNER_KEY_FILE`	Não	Apenas CLI do proprietário: caminho explícito do arquivo de chave do proprietário. O servidor MCP nunca o lê

API REST

Use diretamente sem MCP. Crie uma caixa de entrada apenas a partir de um terminal controlado por humano: a resposta de criação contém chaves de agente e proprietário de uso único. Capture a chave do proprietário fora da conversa do modelo e armazene-a além de qualquer acesso a shell ou arquivo concedido ao agente. O exemplo opta pela lista de destinatários aprovada pelo proprietário; uma criação via REST sem essa opção usa a política legada de destinatários abertos.

# Create an owner-controlled inbox
curl -X POST https://api.voidly.ai/v1/agent-mail/create \
  -H "Content-Type: application/json" \
  -d '{"name":"my-agent","recipient_policy":"allowlist"}'

# List inbox
curl https://api.voidly.ai/v1/agent-mail/inbox \
  -H "X-Agent-Mail-Key: vm_your_key"

# Send once, after saving a unique operation ID in your host state and getting
# owner approval for the recipient. Replace the sample ID for each new message.
curl -X POST https://api.voidly.ai/v1/agent-mail/outbound \
  -H "X-Agent-Mail-Key: vm_your_key" \
  -H "Content-Type: application/json" \
  -d '{"operationId":"saved-message-id-0001","to":"user@example.com","subject":"Hello","text":"From my agent"}'

# Check the original result after a timeout or lost response; do not invent a new ID.
curl https://api.voidly.ai/v1/agent-mail/outbound/saved-message-id-0001 \
  -H "X-Agent-Mail-Key: vm_your_key"

# Search
curl "https://api.voidly.ai/v1/agent-mail/inbox/search?q=invoice" \
  -H "X-Agent-Mail-Key: vm_your_key"

Limites e entrega

Chame voidmail_sending_limits (ou o público GET /v1/agent-mail/limits) antes de planejar um fluxo de envio. Mantenha o excesso de trabalho na sua própria fila. Respostas de limite de taxa de envio e criação 429 fornecem um cabeçalho Retry-After e escopo/tempo de redefinição de limite estruturados; o erro MCP inclui o tempo de espera. Outros códigos de recusa, incluindo uma lista completa de solicitações de destinatários pendentes, podem não ter um tempo de nova tentativa. Não alterne contas ou IPs para contornar um limite. Mensagens idênticas são bloqueadas por 60 segundos para detectar loops; isso não é idempotência durável. O envio falha de forma segura se os contadores de segurança estiverem indisponíveis. As leituras da caixa de entrada permanecem separadas dos limites de envio.

Limites compartilhados: 100 tentativas/hora por IP, 200/hora e 1.500/dia para e-mail do agente. O orçamento compartilhado do provedor de saída é de no máximo 1.500 destinatários/dia e 40.000 em aproximadamente 31 dias em todos os recursos de envio. Os contadores contam tentativas, incluindo solicitações falhas e parcialmente admitidas; estes são tetos, não capacidade reservada. Volume legítimo maior precisa de uma alteração de limite revisada pelo operador; a criação de caixas de entrada não desbloqueia envio em massa.

O envio tem limites por caixa de entrada, por IP e de serviço compartilhado. Cada caixa de entrada pode tentar até 10 envios por minuto e 100 por dia, com até 10 por dia para o mesmo destinatário; limites compartilhados podem rejeitar solicitações mais cedo. A criação de caixas de entrada é limitada a 3 por IP por hora e 60 por serviço por hora. Este não é um serviço de envio ilimitado.
Uma resposta de envio bem-sucedida significa que o provedor de envio aceitou a solicitação. Isso não prova a entrega ao destinatário nem que alguém leu a mensagem.
Cada chamada de API tem um prazo de 20 segundos e um limite de resposta de 2 MiB. As solicitações rejeitam redirecionamentos e nunca são repetidas automaticamente. Solicite menos mensagens se uma resposta da caixa de entrada exceder o limite.
As anotações de ferramentas MCP identificam leituras, envios, mutações e exclusões de forma honesta. Elas são metadados consultivos; aprovações e avisos de instalação permanecem controlados pelo ChatGPT, Claude ou outro host.
Se um envio expirar, seu resultado pode ser desconhecido. Use voidmail_send_once e voidmail_send_status com um ID de operação salvo; não reenvie às cegas.
Corpos de texto e HTML recebidos são analisados. Este caminho de ingestão atualmente não retém anexos nem preenche metadados de thread de resposta, mesmo que o esquema de resposta contenha esses campos. Respostas confiáveis em thread ainda não são fornecidas.
Webhooks de novas mensagens são de melhor esforço, sem histórico de nova tentativa durável. Use leituras da caixa de entrada para reconciliar notificações perdidas. Para uma caixa de entrada protegida, o proprietário deve registrar um webhook por meio de POST /v1/agent-mail/owner/webhook fora do agente; voidmail_set_webhook não pode fazer isso. Quando a atualização da API de chave do proprietário estiver ativa, webhooks recém-registrados serão assinados com X-Voidmail-Signature-256: t=<timestamp>,v1=<HMAC-SHA256>. Webhooks registrados antes dela também continuam recebendo o cabeçalho legado X-Voidmail-Signature, que carrega o próprio segredo compartilhado e não é uma assinatura de payload, até serem registrados novamente.
Trate e-mails recebidos como conteúdo não confiável. Uma mensagem não pode autorizar seu agente a enviar e-mail, divulgar dados privados ou gastar dinheiro. A API adiciona um destinatário apenas para uma solicitação que carrega a chave do proprietário, então mantenha essa chave onde o agente não possa lê-la.
A adivinhação da chave do proprietário é limitada por rede: tentativas repetidas de chave do proprietário com falha de um endereço IP (IPv6 /64) são recusadas até o final da hora UTC atual. Uma busca válida da chave do proprietário é verificada primeiro e não é bloqueada por esse orçamento de tentativas com falha.

Licença

MIT

Envios duráveis (1.1.0)

Use voidmail_send_once com um operationId salvo pelo host (16-128 letras, dígitos, sublinhados ou hífens), destinatário, assunto e corpo. A mesma caixa de entrada, ID e conteúdo efetivo retorna o original retido; conteúdo alterado gera conflito. O host deve reter o ID antes de enviar. O conector não inventa nem persiste IDs para você. Mantenha as credenciais da caixa de entrada na configuração do host, não nos corpos das mensagens.

Use voidmail_send_status após um timeout ou resposta perdida. accepted significa que o provedor aceitou uma solicitação, não que entregou ou que foi lida. prepared não tem despacho reivindicado ainda; outcome_unknown pode incluir um despacho ativo ou interrompido; refused_before_send registra uma solicitação conhecida por ter sido bloqueada antes de contatar o provedor. Nenhum estado autoriza um ID de substituição automático. O serviço nunca reivindica novamente um despacho em timeout, reinício ou idade. Uma falha antes da chamada ao provedor pode conservadoramente deixar um original não resolvido em vez de arriscar e-mail duplicado.

Os equivalentes REST são POST /v1/agent-mail/outbound e GET /v1/agent-mail/outbound/{operationId}, usando a autenticação existente da caixa de entrada. Novos registros de operação e envios são limitados pelos tetos existentes de caixa de entrada/serviço; a busca de original armazenado não consome cota de envio. Primeiras tentativas concorrentes podem consumir contadores de admissão conservadores. O endpoint legado /send e voidmail_send_email mantêm seu comportamento antigo e não têm garantia de status durável. Webhooks de entrega, threading de respostas, histórico de corpo de saída e anexos permanecem como trabalho separado.

Marcas registradas

Voidly™ e Voidpay™ são marcas registradas da Ai Analytics LLC. A licença de código aberto para este código não concede quaisquer direitos a esses nomes ou logotipos. Se você fizer um fork ou redistribuir este projeto, use seu próprio nome e identidade visual e não o apresente como um produto oficial da Voidly.