Assistentes de IA
Conecte a sua ferramenta de IA à Postal
Conectar é dar a um assistente de IA permissão para trabalhar na sua conta da Postal. Depois disso, você pede em português e ele consulta contatos e envios, manda e-mails e cria campanhas, só dentro do que você autorizou.
Em poucas palavras
Como funciona
São três passos, e o que muda de uma ferramenta para outra é onde você cola o endereço.
1. Escolha a sua ferramenta
Cada uma tem um passo a passo próprio, com o que copiar e onde colar.
2. Entre com a sua conta
Você informa o endereço da Postal, escolhe o time e clica em Permitir. Algumas ferramentas aceitam também uma chave de API.
3. Peça em português
Por exemplo: “liste os meus domínios”. O assistente usa as ações da Postal e responde na conversa.
Ferramentas
Escolha a sua ferramenta
São 12 ferramentas, de assistentes de conversa a editores de código e criadores de apps. O selo diz, sem rodeios, o quanto já testamos.
Cursor
Conecte o editor Cursor à Postal para consultar domínios, entregas e templates e enviar e-mails de teste sem sair do código.
Ver como conectarTestado por nósClaude
Adicione a Postal como conector personalizado no Claude (web, desktop e celular) e peça para ele consultar e enviar e-mails em linguagem natural.
Ver como conectarTestado por nósClaude Code
Adicione a Postal ao Claude Code com um comando e use o terminal para diagnosticar entregas e enviar e-mails de teste.
Ver como conectarCompatível pela especificaçãoCodex
Configure a Postal no Codex (CLI, extensão de IDE e app) com algumas linhas no config.toml.
Ver como conectarTestado por nósGitHub Copilot
Use a Postal no GitHub Copilot: no VS Code por OAuth, no Copilot CLI e no agente de nuvem do Copilot com uma chave de API.
Ver como conectarCompatível pela especificaçãoGemini
Conecte a Postal ao Gemini CLI (e ao Antigravity, que o substitui para quem não tem plano pago) para consultar e enviar e-mails pelo terminal.
Ver como conectarCompatível pela especificaçãov0
Conecte a Postal ao v0 para que ele consulte seus domínios e templates e envie e-mails de teste enquanto gera o app.
Ver como conectarCompatível pela especificaçãoBolt
Adicione a Postal como conector personalizado do Bolt para consultar e enviar e-mails enquanto você constrói o projeto.
Ver como conectarCompatível pela especificaçãoLovable
Conecte a Postal ao Lovable como servidor MCP personalizado para usar seus dados de e-mail no chat do projeto.
Ver como conectarCompatível pela especificaçãoReplit
Adicione a Postal como servidor MCP no Replit Agent e use seus domínios, templates e envios no projeto.
Ver como conectarTestado por nósChatGPT
Adicione a Postal como servidor MCP personalizado no ChatGPT e converse com seus dados de e-mail.
Ver como conectarCompatível pela especificaçãoWindsurf
Conecte a Postal ao Cascade do Windsurf (agora na documentação do Devin Desktop) com um bloco no mcp_config.json.
Ver como conectarO que cada selo quer dizer está na matriz de compatibilidade.
Servidor MCP
O que o servidor da Postal oferece
A Postal tem um servidor MCP, o padrão aberto que os assistentes de IA usam para falar com outros sistemas. É ele que você conecta.
Um endereço só, para todas as ferramentas
A URL é a mesma para todos os apps. O domínio da API é https://api.postal.so e o endpoint é /mcp.
- Transporte: Streamable HTTP sem estado. Só POST em
/mcp; não há o transporte antigo HTTP+SSE. Se o app der a escolha entre HTTP e SSE, escolha HTTP. - 34 ferramentas que o assistente pode usar, além de 2 recursos (domínios e guia de início) e 2 roteiros prontos (escrever e enviar uma campanha, diagnosticar entrega).
- Duas formas de entrar: com a sua conta (OAuth) ou com uma chave de API.
https://api.postal.so/mcpAutenticação
Duas formas de entrar
A maior parte das ferramentas aceita as duas. A página de cada uma diz qual é o caminho recomendado.
OAuth 2.1 (recomendado)
Cada pessoa entra com a própria conta da Postal e escolhe um time na tela de permissão. O app se registra sozinho e o acesso dura 1 hora, renovado por um código de 30 dias que muda a cada uso.
Chave de API em cabeçalho
Para apps que aceitam cabeçalhos fixos: Authorization: Bearer ps_..., com uma chave criada no painel, em Chaves de API. A chave de acesso total (full_access) vê as 34 ferramentas; a chave só de envio (sending_access) vê só send_email e track_event.
Bom saber
- As ferramentas rodam os mesmos endpoints da API REST: mesma validação, cota diária, pausa de envio, lista de supressão e limite de requisições por segundo do plano (resposta 429
rate_limit_exceeded). - As listas trazem no máximo 100 itens por chamada (padrão 20), em páginas. Peça menos itens quando puder.
send_emailaceitaidempotency_key: repetir a chamada não envia o e-mail duas vezes.
Acessos
Escopos: o que cada acesso permite
Um escopo é uma permissão. A Postal tem três, do mais restrito ao mais amplo.
| Acesso | O que libera | Ferramentas |
|---|---|---|
Ler seus dadosmcp:read | Ver e-mails, domínios, contatos, segmentos, tópicos, templates, broadcasts, automações, formulários, conversas das inboxes, métricas e uso. 22 ferramentas (list_*, get_*). | 22 ferramentaslist_domains, get_email, get_metrics |
Enviar e-mails e eventosmcp:send | Enviar e agendar e-mails de domínios verificados e registrar eventos para automações. 2 ferramentas. Sozinho não permite ver o status do e-mail (get_email pede mcp:read). | 2 ferramentassend_email, track_event |
Gerenciar tudomcp:full | Tudo dos anteriores, mais criar, alterar e apagar contatos e templates, criar e enviar broadcasts (send_broadcast exige confirm: true), cancelar e-mails agendados e trabalhar nas inboxes (organizar, responder, criar rascunho). 10 ferramentas de escrita. | 10 ferramentassend_broadcast, create_contact, reply_to_inbox_thread |
mcp:full inclui os outros dois. Os apps pedem os três escopos por padrão (o servidor os anuncia no cabeçalho WWW-Authenticate) e a tela de consentimento concede o conjunto pedido; a pessoa escolhe o time, não os escopos.
Para limitar, fixe o escopo na configuração do app quando ele permitir (Claude Code: oauth.scopes; Codex: scopes; Cursor: bloco auth com client id registrado por você) ou use uma chave de API sending_access (só envio).
Passo a passo
Valide a conexão
Antes de configurar um app, confirme que o servidor responde e que o app encontrará o servidor de autorização. Não precisa ser técnico para conectar: esta parte é para quem quer ver a prova.
Veja se a descoberta do OAuth responde
O comando abaixo pede à Postal os dados da entrada por conta. Deve responder 200 com um JSON (issuer, authorization_endpoint, token_endpoint, registration_endpoint e code_challenge_methods_supported ["S256"]). Se responder 403 ou uma página HTML, algo na frente do servidor está bloqueando o caminho /.well-known e os apps com OAuth não vão conseguir conectar. Nesse caso, avise a gente pelo formulário de contato.
curl -i https://api.postal.so/.well-known/oauth-authorization-serverConfira o desafio de autenticação
Sem token, o servidor deve recusar e dizer onde está a entrada: a resposta esperada é 401, com o cabeçalho WWW-Authenticate abaixo.
curl -i -X POST https://api.postal.so/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"teste","version":"1"}}}'WWW-Authenticate: Bearer resource_metadata="https://api.postal.so/.well-known/oauth-protected-resource/mcp",
scope="mcp:read mcp:send mcp:full"Liste as ferramentas com uma chave de API
Com uma chave de acesso total, a lista deve ter 34 ferramentas; com uma chave só de envio, 2. Troque ps_... pela sua chave. Testamos esta linha de comando na versão 2.12.0 do Inspector; os nomes das opções podem mudar em outras versões.
npx @modelcontextprotocol/inspector --cli https://api.postal.so/mcp \
--transport http \
--header "Authorization: Bearer ps_..." \
--method tools/listOu use a interface web, entrando com a conta
Rode o comando, escolha o transporte Streamable HTTP, cole o endereço do servidor e conecte. O Inspector conduz o login da Postal no navegador: escolha o time e permita. Os nomes exatos dos botões mudam entre versões do Inspector. Depois de conectar, a lista deve mostrar as 34 ferramentas (send_email, list_domains, list_contacts...), e rodar get_usage deve devolver o uso do plano do time escolhido.
npx @modelcontextprotocol/inspectorConfira a conexão no painel
A conexão aparece em Configurações › Conexões de IA, com o app, o time e a última utilização. É lá também que você revoga.
Situação de cada uma
Matriz de compatibilidade
Uma linha por ferramenta: como ela entra, que transporte usa e o quanto já testamos.
| Ferramenta | Tipo | Como entra | Transporte | Situação |
|---|---|---|---|---|
| Cursor | Editor | Conta (OAuth) ou chave de API | HTTP | Compatível pela especificação |
| Claude | Assistente | Conta (OAuth) | HTTP | Testado por nós |
| Claude Code | Linha de comando | Conta (OAuth) ou chave de API | HTTP | Testado por nós |
| Codex | Linha de comando | Conta (OAuth) ou chave de API | HTTP | Compatível pela especificação |
| GitHub Copilot | Editor | Conta (OAuth) ou chave de API | HTTP | Testado por nós |
| Gemini | Linha de comando | Conta (OAuth) ou chave de API | HTTP | Compatível pela especificação |
| v0 | Criador de apps | Conta (OAuth) ou chave de API | HTTP | Compatível pela especificação |
| Bolt | Criador de apps | Conta (OAuth) ou chave de API | HTTP | Compatível pela especificação |
| Lovable | Criador de apps | Conta (OAuth) ou chave de API | Não informado | Compatível pela especificação |
| Replit | Criador de apps | Chave de API ou conta (OAuth) | Não informado | Compatível pela especificação |
| ChatGPT | Assistente | Conta (OAuth) | HTTP | Testado por nós |
| Windsurf | Editor | Chave de API ou conta (OAuth) | HTTP | Compatível pela especificação |
Rodamos testes automatizados da Postal com os documentos e os endereços de retorno reais que o app publica, e com o cliente oficial do SDK do MCP. Não é um teste dentro do aplicativo de verdade. A página de cada ferramenta traz a nota completa do que foi e do que não foi verificado.
Seguimos a especificação e a documentação do app, mas ainda não testamos com o app de verdade. A página de cada ferramenta traz a nota completa do que foi e do que não foi verificado.
O que “testado por nós” quer dizer, exatamente
Verificado por teste automatizado da Postal com os artefatos reais que o app publica (documento de metadados do cliente, URIs de retorno documentadas) e com o cliente oficial do SDK MCP. Não é um teste dentro do produto do app.
Como testamos (28/10/2026). Servidor local de teste (php artisan serve, SQLite) exercitado por um cliente Node com @modelcontextprotocol/sdk 1.32.2 (descoberta, registro dinâmico, PKCE, token, refresh com rotação, initialize, tools/list, tools/call, chave de API em cabeçalho), pelo MCP Inspector em modo CLI e por testes automatizados (PHPUnit) que usam os documentos de metadados reais publicados por Claude, Claude Code, ChatGPT e VS Code.
Isso não é um selo do fabricante. Em nenhuma das ferramentas da tabela rodamos a conexão dentro do aplicativo de verdade: por isso cada página mostra, além do selo, a nota completa do que foi e do que não foi verificado.
Antes de conectar
Perguntas frequentes
Preciso de um plano específico?
Depende do plano. O time precisa ter o recurso Servidor MCP no plano; sem ele, o servidor responde com o erro 403 plan_limit_reached. Algumas ferramentas também têm regras próprias de plano ou de permissão (por exemplo, quem pode adicionar conectores): elas aparecem em “Antes de começar”, na página de cada uma. Veja os planos em Preços.
Posso limitar o que o assistente faz?
Em parte. Os acessos são de três níveis (ler, enviar e gerenciar tudo), na tabela de escopos. Com chave de API, a chave só de envio (sending_access) expõe apenas send_email e track_event. Entrando com a conta, os apps pedem os três escopos por padrão e a tela de permissão concede o conjunto pedido: você escolhe o time, não os escopos. Algumas ferramentas deixam fixar os escopos na configuração (Claude Code, Codex e Cursor, por exemplo); a página de cada uma diz o que vale para ela. Mesmo com acesso total, enviar uma campanha exige confirmação explícita (confirm: true).
Como revogo o acesso?
No painel da Postal, em Configurações › Conexões de IA: cada conexão aparece com o app, o time e a última utilização, e pode ser revogada a qualquer momento. Se você usou uma chave de API, revogue a chave em Chaves de API. Os detalhes estão na documentação do servidor MCP e em Autenticação.
Meus dados vão para a empresa da IA?
Só o que a ferramenta consultar. Quando você pede algo, a ferramenta chama as ações da Postal e recebe o resultado (por exemplo, a lista dos seus domínios ou os dados de um e-mail). Esse resultado passa a fazer parte da conversa e fica sob as regras da empresa dessa ferramenta. A Postal só responde ao que a ferramenta pedir, dentro dos acessos que você autorizou, e cada conexão age em um único time. Leia a política da ferramenta que escolher e dê só o acesso de que precisa. Sobre os dados na Postal, veja a Política de privacidade.
E se a conexão falhar?
- Confira o endereço:
https://api.postal.so/mcp, com/mcpno fim, e o tipo de conexão HTTP. A Postal não oferece SSE. - Veja se o time tem o recurso "Servidor MCP" no plano. Sem ele, o servidor responde 403
plan_limit_reached. - Para enviar e-mails, o time precisa ter ao menos um domínio verificado.
- Cada conexão age em um único time. Para usar outro, conecte de novo e escolha o outro.
- Rode os testes de “Valide a conexão”, acima. Se a descoberta do OAuth não responder 200, os apps com OAuth não conseguem conectar.
- Resposta 429 (
rate_limit_exceeded): o limite de requisições por segundo do plano foi atingido. Espere um pouco e tente de novo. - Ainda não resolveu? Veja “Se der problema” na página da ferramenta e a documentação do servidor MCP, ou fale com a gente pelo formulário de contato.
Quer conectar a sua ferramenta?
Crie a sua conta e conecte o seu assistente. Se precisar de ajuda, fale com a gente pelo formulário de contato.