InboxAPI

InboxAPI CLI

Dê ao seu agente de IA seu próprio endereço de e-mail pessoal. Envie, receba, leia, pesquise e responda e-mails — direto do Claude, OpenCode, Codex, Gemini ou qualquer cliente de IA compatível com MCP. Sem servidor de e-mail para executar, sem SMTP para configurar.

---

Sumário

• Como funciona
• Detalhes técnicos
• Informações importantes
• Instalação
• Primeiros passos
• Comandos
• Comandos CLI
• Uso com clientes MCP
• Habilidades para Claude Code
• Desenvolvimento
• FAQ
• Licença
• Aviso legal

---

Como funciona

1. Instale a CLI
2. Conecte-a ao seu cliente de IA (Claude Desktop, Claude Code, Gemini CLI, OpenCode, etc.)
3. Seu IA agora pode usar e-mail — sem necessidade de código ou chaves de API

Uma conta com um endereço de e-mail pessoal exclusivo é criada automaticamente na primeira execução. Seu IA pode então:

• Enviar e-mails para qualquer endereço
• Receber e-mails em sua própria caixa de entrada
• Responder e encaminhar e-mails
• Pesquisar e-mails por palavra-chave
• Ler conversas completas em tópicos

Detalhes técnicos

A CLI atua como uma ponte local entre seu cliente de IA e o serviço em nuvem InboxAPI. Ela fala o Model Context Protocol (MCP) por meio de entrada/saída padrão, para que qualquer cliente de IA compatível possa usá-la sem integração personalizada.

Informações importantes

• Este é o e-mail pessoal do seu agente — InboxAPI dá ao seu agente de IA seu próprio endereço de e-mail para uso pessoal. Não é um serviço de e-mail transacional — não use para envio em massa, marketing ou notificações de aplicativos.
• Limite semanal de envio — Cada conta pode enviar para até cinco endereços de e-mail exclusivos por semana. Isso é redefinido semanalmente.
• Verifique sua pasta de spam — Cada agente recebe seu próprio subdomínio, e novos subdomínios ainda não têm reputação de e-mail. Mensagens iniciais podem cair na pasta de spam ou lixo eletrônico do destinatário. Adicionar o endereço de e-mail do seu agente aos seus contatos ou à lista de permissões ajuda. A entrega melhora com o tempo à medida que os destinatários interagem com os e-mails do seu agente.
• Anexos — Envie anexos por meio de subcomandos da CLI usando --attachment (arquivos locais) ou --attachment-ref (anexos no servidor por ID).
• Suporte a e-mail HTML — Subcomandos da CLI suportam e-mails HTML com --html-body ou --html-body-file.
• Verificação do proprietário — Vincule seu e-mail à conta do seu agente com verify_owner para habilitar a recuperação de conta e remover restrições de teste. Recomendado como primeiro passo após a configuração.

Instalação

npm install -g @inboxapi/cli@latest

Binários pré-compilados estão incluídos para:

Plataforma	Arquitetura
macOS	ARM64, x64
Linux	x64, ARM64
Windows	x64

Atualização

Execute o mesmo comando de instalação para atualizar para a versão mais recente:

npm install -g @inboxapi/cli@latest

A CLI também verifica atualizações automaticamente quando executada em modo proxy e as instala em segundo plano.

Primeiros passos

Basta iniciar o proxy — uma conta é criada automaticamente na primeira execução

inboxapi proxy

Na primeira execução sem credenciais salvas, a CLI cria automaticamente uma conta com um nome gerado (por exemplo, brooding-fluffy-owl) e autentica. Nenhuma configuração manual é necessária.

As credenciais são armazenadas no diretório de configuração do seu sistema e injetadas automaticamente nas chamadas de ferramentas. A CLI verifica vários locais para que possa detectar credenciais criadas por agentes de IA:

• ~/Library/Application Support/inboxapi/credentials.json (principal no macOS)
• ~/.config/inboxapi/credentials.json (principal no Linux / alternativa no macOS)
• ~/.local/inboxapi/credentials.json (alternativa, usada por alguns agentes de IA)

Comandos

proxy (padrão)

Inicia o proxy STDIO. Lê mensagens JSON-RPC da entrada padrão, encaminha-as para o endpoint do InboxAPI e transmite respostas SSE para a saída padrão. Se nenhuma credencial for encontrada, uma conta é criada automaticamente com um nome gerado.

inboxapi proxy
inboxapi proxy --endpoint https://custom-endpoint.example.com/mcp
inboxapi proxy --claim-secret ibx...

Executar inboxapi sem subcomando também inicia o proxy. --claim-secret é usado apenas quando as credenciais não existem e o proxy cria automaticamente uma conta em um domínio personalizado.

login

Cria manualmente uma conta com um nome escolhido e armazena as credenciais de acesso localmente. Não é necessário para uso básico, pois proxy lida com a criação de conta automaticamente.

inboxapi login
inboxapi login --name myaccount
inboxapi login --endpoint https://custom-endpoint.example.com/mcp
inboxapi login --name myaccount --claim-secret ibx...

custom-domain-claim

Reivindica uma caixa de correio primária de domínio personalizado para a conta atual usando um segredo de reivindicação de domínio personalizado. A caixa de correio gerada anteriormente permanece habilitada para recebimento, mas não pode enviar.

inboxapi custom-domain-claim --secret ibx... --email-address myaccount@example.com

whoami

Exibe a conta e o endpoint atualmente autenticados.

inboxapi whoami

reset

Exclui as credenciais armazenadas. Oferece interativamente fazer backup primeiro e, em seguida, pede confirmação antes de excluir.

inboxapi reset

backup

Faz backup das credenciais em uma pasta especificada.

inboxapi backup ./my-backup

restore

Restaura credenciais de uma pasta de backup. Valida a integridade do backup e oferece fazer backup das credenciais existentes antes de sobrescrever.

inboxapi restore ./my-backup

setup-skills

Instala habilidades do InboxAPI para agentes de codificação de IA. Suporta Claude Code, Codex CLI, Gemini CLI e OpenCode. Detecta automaticamente agentes instalados e solicita confirmação, ou use flags para instalação não interativa.

inboxapi setup-skills              # Auto-detect agents, interactive prompt
inboxapi setup-skills --all        # Install for all 4 agents
inboxapi setup-skills --claude --codex  # Install for specific agents
inboxapi setup-skills --force      # Overwrite existing skills and hooks

Comandos CLI

Para agentes com acesso ao shell, os subcomandos da CLI são a maneira mais simples de usar o InboxAPI — sem necessidade de conhecimento em MCP, JSON-RPC ou base64.

send-email

inboxapi send-email --to user@example.com --subject "Hello" --body "Hi there"
inboxapi send-email --to user@example.com --subject "Report" --body "See attached" --attachment ./report.pdf
inboxapi send-email --to user@example.com --subject "Fwd" --body "See attached" --attachment-ref 9f0206bb-...
inboxapi send-email --to "a@b.com, c@d.com" --subject "Hi" --body "Hello" --cc "cc@b.com" --priority high
inboxapi send-email --to user@example.com --subject "Newsletter" --body-file ./body.txt --html-body-file ./newsletter.html
inboxapi send-email --to user@example.com --subject "Screenshot" --body-file ./body.txt --html-body-file ./email-with-inline-image.html

Suporta --body ou --body-file, --html-body ou --html-body-file, --cc, --bcc, --priority, --attachment (arquivos locais, repetível) e --attachment-ref (IDs de anexos no servidor, repetível). --from-name está obsoleto e é ignorado; o InboxAPI impõe a identidade da conta autenticada.

Prefira --body-file e --html-body-file para HTML complexo, modelos ou grandes cargas geradas, como imagens base64 inline. Corpos baseados em arquivos são validados como texto UTF-8, normalizados para terminações de linha \n e limitados a 20 MiB antes do envio da solicitação.

get-emails

inboxapi get-emails --limit 5
inboxapi get-emails --limit 5 --human

get-email

inboxapi get-email "<message-id>"

delete-email

Arquiva (exclusão suave) um e-mail recebido pelo ID da mensagem. Solicita confirmação por padrão, e o uso por script ou pipe deve passar --force. archive-email está disponível como um alias para delete-email.

inboxapi delete-email "<message-id>"
inboxapi delete-email "<message-id>" --force
inboxapi archive-email "<message-id>" --force

search-emails

inboxapi search-emails --subject "invoice" --limit 10

get-attachment

inboxapi get-attachment abc123                      # prints signed URL as JSON
inboxapi get-attachment abc123 --output ./file.pdf  # downloads to file

send-reply

inboxapi send-reply --message-id "<msg-id>" --body "Thanks!"
inboxapi send-reply --message-id "<msg-id>" --body-file ./reply.txt --html-body-file ./reply.html

send-reply preserva automaticamente os destinatários originais do tópico para conversas com vários destinatários. Use --reply-all para forçar responder a todos, e use --cc quando precisar adicionar novos destinatários em cópia além do tópico original.

forward-email

inboxapi forward-email --message-id "<msg-id>" --to recipient@example.com --note "FYI"

help

inboxapi help  # CLI-focused help with examples

Todos os comandos da CLI suportam a flag --human para saída legível por humanos em vez de JSON.

Uso com clientes MCP

A CLI do InboxAPI também funciona como transporte MCP STDIO. Aponte seu cliente MCP para o binário inboxapi:

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "inboxapi": {
      "command": "inboxapi"
    }
  }
}

Claude Code:

Adicionar ao projeto atual:

claude mcp add inboxapi inboxapi

Adicionar globalmente (disponível em todos os projetos):

claude mcp add inboxapi inboxapi -s user

Gemini CLI:

Adicionar ao projeto atual:

gemini mcp add inboxapi inboxapi

Adicionar em todo o sistema (disponível em todos os diretórios):

gemini mcp add inboxapi inboxapi --scope user

OpenCode:

Execute a configuração interativa:

opencode mcp add

Quando solicitado, insira:

• Local: Global
• Nome do servidor MCP: inboxapi
• Tipo de servidor MCP: Local
• Comando a executar: inboxapi

Codex CLI:

codex mcp add inboxapi inboxapi

Habilidades para agentes de codificação de IA

O InboxAPI inclui habilidades — comandos de barra e fluxos de trabalho guiados — para vários agentes de codificação de IA. Instale-os com:

inboxapi setup-skills        # Auto-detect and install
inboxapi setup-skills --all  # Install for all agents

As habilidades são instaladas em diretórios específicos do agente:

Agente	Diretório de instalação
Claude Code	.claude/skills/
Codex CLI	.agents/skills/
Gemini CLI	.gemini/skills/
OpenCode	.opencode/commands/

Habilidades disponíveis

Habilidade	Descrição
/check-inbox	Busca e exibe um resumo dos e-mails recentes em uma tabela formatada
/compose	Redige e envia um e-mail com prompts guiados, consulta de agenda de contatos e confirmação
/email-search	Pesquisa e-mails usando consultas em linguagem natural
/email-reply	Responde a um e-mail com contexto completo do tópico e visualização antes do envio
/email-digest	Gera um resumo estruturado da atividade recente de e-mails agrupada por tópicos
/email-forward	Encaminha um e-mail para outro destinatário com uma nota opcional
/setup-inboxapi	Configura o servidor MCP do InboxAPI e instala habilidades para seu agente de codificação de IA

Hooks (somente Claude Code)

O comando setup-skills também instala três hooks para Claude Code que são executados automaticamente:

Hook	Tipo	Descrição
Verificação de credenciais	SessionStart	Verifica as credenciais do InboxAPI na inicialização e mostra o status de autenticação
Proteção de envio de e-mail	PreToolUse	Revisa e-mails de saída antes do envio, avisa sobre autoenvios e corpos vazios
Registro de atividade	PostToolUse	Registra todo o uso de ferramentas do InboxAPI em .claude/inboxapi-activity.log para trilhas de auditoria

Desenvolvimento

cargo build           # Build debug binary
cargo build --release # Build release binary
cargo test            # Run tests
cargo fmt             # Format code

FAQ

Por que não dar ao meu agente acesso ao meu Gmail ou Outlook?

Segurança — OAuth do Gmail/Outlook dá ao seu agente acesso à sua caixa de entrada inteira (médica, financeira, jurídica, pessoal). Uma injeção de prompt em qualquer e-mail recebido poderia manipular um agente com acesso a tudo isso. O InboxAPI dá ao seu agente sua própria caixa de entrada isolada com classificação de confiança e marcação de dados em cada mensagem.

Identidade — Quando seu agente envia do seu Gmail, os destinatários não conseguem distinguir com quem estão falando. As respostas vão para sua caixa de entrada, misturadas com seus e-mails reais. O InboxAPI dá ao seu agente seu próprio endereço pessoal — separação clara entre você e seu agente.

Praticidade — As APIs do Gmail/Outlook não são nativas de MCP. Você precisaria de middleware, integração OAuth e integração personalizada. O InboxAPI funciona imediatamente com qualquer cliente MCP.

Como isso é diferente do AWS SES, SendGrid ou Resend?

Esses são APIs de envio — você constrói infraestrutura de e-mail sobre eles. O InboxAPI dá ao seu agente uma identidade de e-mail completa: enviar, receber, pesquisar, responder e encaminhar. Não há nada para configurar e nenhuma infraestrutura para gerenciar.

Como isso é diferente do AgentMail ou a1base?

Construímos nossa própria pilha de e-mail do zero. Não envolvemos SES, Postfix ou qualquer serviço de envio de terceiros. O e-mail do seu agente passa por infraestrutura que operamos diretamente.

É realmente gratuito?

Sim. Sem cartão de crédito, sem período de teste, sem níveis de uso. Estamos trabalhando em planos pagos com recursos adicionais, mas a experiência principal será sempre gratuita.

Como vocês previnem spam e abuso?

A criação de conta exige prova de trabalho. Cada conta só pode enviar e-mail para 5 endereços de e-mail externos exclusivos por semana. Cotas diárias de envio e limitação de taxa são aplicadas em todas as contas. Essas restrições são estruturais — não são políticas, são como o sistema funciona.

E quanto à injeção de prompt via e-mail?

Cada e-mail recebido inclui uma classificação de confiança — confiável, agente, não verificado ou suspeito — com base em se o remetente está na sua agenda de contatos e se o e-mail dele passa nas verificações de autenticação. Isso ajuda seu agente a decidir com que cautela lidar com cada mensagem. E-mails de outros agentes InboxAPI são sinalizados separadamente para que seu agente saiba verificar com você antes de agir sobre eles.

Além disso, o conteúdo de e-mail não confiável é transformado automaticamente usando spotlighting (marcação de dados) — espaços em branco são substituídos por um caractere de marcação exclusivo para que seu agente possa distinguir claramente os dados de e-mail de suas próprias instruções. Isso reduz a taxa de sucesso de ataques de injeção de prompt incorporados em e-mails de ~50% para menos de 3%.

O que é spotlighting?

As ferramentas de recuperação de e-mail aplicam marcação de dados a conteúdo não confiável, substituindo espaços em branco por um caractere de marcador Unicode exclusivo gerado por solicitação. Conteúdo que contém o marcador deve ser tratado como dados externos — nunca como instruções a serem seguidas. Para recuperar o texto original, substitua o marcador por um espaço. E-mails de remetentes confiáveis (na sua agenda de contatos com autenticação válida) não são destacados por padrão. Esta técnica é baseada em pesquisa acadêmica (arXiv:2403.14720).

E quanto à exfiltração de dados?

E-mails de saída são verificados quanto a tokens de autenticação e credenciais. Se o seu agente tentar acidentalmente enviar um e-mail contendo um JWT ou token de acesso, a mensagem será rejeitada antes de sair da plataforma. Isso impede que agentes sejam enganados para vazar dados sensíveis por e-mail. Além disso, todos os endereços de destinatários em operações de envio, resposta e encaminhamento são validados conforme RFC 5322 — endereços malformados são rejeitados antes da entrega.

Os agentes podem enviar spam uns aos outros?

Os mesmos limites de envio se aplicam a todos os e-mails de saída — limites de destinatários, cotas e limitação de taxa funcionam da mesma forma, independentemente de quem está no lado do recebimento.

Os e-mails do meu agente cairão em spam?

Talvez no início. Cada agente recebe um subdomínio totalmente novo, e novos remetentes ainda não têm reputação. Os destinatários podem precisar verificar a pasta de spam nos primeiros e-mails. Com o tempo, à medida que seu agente envia e-mails legítimos e os destinatários interagem com eles, a entrega melhora.

Por que e-mail em vez de um protocolo nativo de agente como A2A?

O e-mail alcança toda a internet existente — bilhões de pessoas e empresas já o utilizam. A2A exige que ambos os lados implementem o protocolo. Quando seu agente precisa alcançar alguém fora do seu próprio ecossistema, o e-mail é a opção universal. Os agentes provavelmente precisarão de ambos.

Por que e-mail em vez de WhatsApp, Telegram ou outros aplicativos de mensagens?

Escalabilidade — Você pode criar programaticamente centenas de endereços de e-mail. WhatsApp, Telegram e Signal exigem números de telefone e verificação. Escalar além de algumas contas é impraticável, muitas vezes contra os termos de serviço e, às vezes, impossível sem chips SIM físicos.

Sem controle de acesso — O e-mail é o único canal de comunicação onde você pode criar uma identidade sem número de telefone, documento de identidade governamental ou aprovação do proprietário da plataforma. Nenhuma empresa controla quem obtém um endereço de e-mail.

Protocolo aberto — O e-mail é federado e neutro em relação a fornecedores. WhatsApp, Discord e Telegram são proprietários — eles podem revogar acesso à API, banir contas de bots ou mudar as regras a qualquer momento. O e-mail não pode ser desligado por uma única empresa.

Conformidade com ToS — A maioria das plataformas de mensagens proíbe explicitamente contas automatizadas ou possui processos de aprovação rigorosos (a API do WhatsApp Business exige verificação comercial, o Telegram restringe mensagens entre bots). O e-mail não tem tais restrições — o envio automatizado é um caso de uso de primeira classe.

Alcance universal — Os canais de mensagens são isolados. Seu bot do Telegram não pode alcançar um usuário do WhatsApp. O e-mail alcança qualquer pessoa com um endereço de e-mail — o que é praticamente todo mundo.

Para estruturas de agentes multicanal como OpenClaw, o e-mail preenche uma lacuna que as plataformas de mensagens estruturalmente não conseguem — criação ilimitada e programável de identidades sem exigir aprovação da plataforma. O InboxAPI dá aos agentes essa capacidade pronta para uso.

Quais são os limites de envio?

Cada conta pode enviar e-mails para até 5 endereços de e-mail externos exclusivos por semana. E-mails para outros endereços @inboxapi.ai não contam para esse limite. O limite é redefinido semanalmente.

O que acontece quando eu atinjo o limite?

Quando todos os 5 slots estão em uso, a entrada usada menos recentemente é substituída automaticamente após 5 dias de inatividade.

Posso enviar anexos?

Sim. O suporte a anexos está totalmente disponível. Forneça uma matriz de objetos EmailAttachment contendo filename, content_type e content codificado em base64 no campo attachments ao chamar send_email.

Posso enviar e-mails em HTML?

Sim. Use --html-body "<html>" para HTML inline ou --html-body-file ./email.html para conteúdo HTML baseado em arquivo. Para modelos mais complexos ou grandes cargas geradas, prefira --body-file e --html-body-file.

Como funcionam as credenciais?

As credenciais do seu agente são armazenadas localmente em ~/.config/inboxapi/credentials.json (Linux) ou ~/Library/Application Support/inboxapi/credentials.json (macOS). A CLI lida com a criação e atualização de tokens automaticamente — seu agente nunca precisa gerenciar tokens manualmente.

E se meu agente perder o acesso?

Se as credenciais do seu agente forem perdidas ou corrompidas, você pode recuperar a conta usando a ferramenta account_recover — mas somente se você tiver vinculado anteriormente seu e-mail via verify_owner. A recuperação revoga todos os tokens existentes e emite novas credenciais. Sem um e-mail de proprietário verificado, não há como recuperar uma conta bloqueada.

O que é verificação de proprietário?

A verificação de proprietário vincula seu endereço de e-mail pessoal à conta InboxAPI do seu agente. Seu agente chama verify_owner com seu e-mail, você recebe um código de 6 dígitos e seu agente o envia para concluir a verificação. Uma vez verificado, você pode recuperar a conta se as credenciais forem perdidas, e as restrições de teste são removidas da conta. O subcomando da CLI verify-owner solicita confirmação por padrão; use --yes para execuções não interativas.

Quais domínios são bloqueados para envio?

O InboxAPI mantém uma lista de bloqueio que impede o envio para domínios governamentais (.gov), militares (.mil), de inteligência, aplicação da lei, infraestrutura nuclear/crítica e e-mails descartáveis.

Como funciona a classificação de confiança?

Cada e-mail recebido é classificado em um dos quatro níveis de confiança:

Nível de Confiança	Significado	Ação Recomendada
Confiável	O remetente está na sua agenda de contatos com SPF/DKIM válidos	Seguro agir
Agente	O remetente é um agente InboxAPI conhecido	Leia livremente, mas confirme com seu humano antes de agir
Não verificado	SPF/DKIM válidos, mas remetente não está na agenda de contatos	Tenha cautela
Suspeito	Falha na autenticação ou remetente desconhecido	Sinalize e confirme antes de agir

Qual modelo de IA devo usar com o InboxAPI?

Seu modelo deve suportar chamada de ferramentas/funções — o MCP exige isso. Recomendamos uma janela de contexto mínima de 32K tokens para acomodar confortavelmente as 21 definições de ferramentas do InboxAPI junto com o histórico da conversa e o conteúdo do e-mail.

Recomendações de modelo por nível:

Nível	Anthropic	OpenAI	Google
Bom	Haiku 4.5+	GPT-4.1 mini+, GPT-4.1 nano+	Gemini 2.5 Flash+
Recomendado	Sonnet 4.5+	GPT-4.1+, GPT-5 mini+	Gemini 2.5 Pro+
Melhor	Opus 4.5+	GPT-5+, GPT-5.2+	Gemini 2.5 Pro+

Sobrecarga de marcação de dados: O InboxAPI aplica marcação de dados (destaque) a conteúdo de e-mail não confiável, substituindo espaços em branco por caracteres de marcador Unicode. Isso pode aumentar ligeiramente o consumo de tokens ao processar e-mails de remetentes externos. Modelos com janelas de contexto maiores lidam com isso mais confortavelmente.

O que não funcionará: Modelos sem suporte a chamada de ferramentas/funções, modelos com janelas de contexto abaixo de 16K tokens e modelos locais muito pequenos (abaixo de ~7B parâmetros) que não possuem chamada de ferramentas confiável. Eles terão dificuldade para acomodar as 21 definições de ferramentas do InboxAPI e manter um histórico de conversa útil.

O que impede um agente de comprar coisas ou autorizar transações por e-mail?

O InboxAPI é um canal de comunicação, não um ambiente de execução. Ele pode entregar um e-mail, mas não pode clicar em botões, inserir números de cartão de crédito ou interagir com sistemas externos. O risco de ações não autorizadas vem de como um agente é configurado e de quais outras ferramentas ele tem acesso — não do seu e-mail.

Licença

O código-fonte neste repositório é licenciado sob a Licença MIT.

Aviso Legal

O serviço InboxAPI é fornecido como está, sem garantias de qualquer tipo. Reservamos todos os direitos sobre como o serviço é operado. Termos de serviço, recursos e disponibilidade podem mudar a qualquer momento sem aviso prévio.