O que AgenticEmail: e-mail para agentes de IA faz?
O AgenticEmail fornece a um agente uma caixa de entrada de e-mail real e endereçável que ele possui. Diferente de uma API de envio apenas de saída, cada caixa de entrada tanto envia quanto recebe: e-mails de entrada chegam como JSON analisado através de um webhook ou de um stream WebSocket. Utilize isto sempre que um agente precisar ser contatável em um endereço de e-mail, e não apenas capaz de enviar.
Gatilhos comuns: o agente precisa se inscrever em um serviço de terceiros, receber um código de verificação ou OTP, ser notificado por e-mail, executar um workflow de suporte ou divulgação, ou trocar e-mails com um humano ou outro agente.
Configuração
- Obtenha uma chave de API (começa com
am_) em https://app.agenticemail.dev. O nível gratuito inclui caixas de entrada reais, envio, recebimento e webhooks. - Exporte-a:
export AGENTICEMAIL_API_KEY=am_... - Escolha um caminho de integração abaixo. Todos chamam
https://api.agenticemail.dev.
Escolha um caminho
- Servidor MCP hospedado (recomendado para agentes compatíveis com MCP como Claude, Cursor
e o Vercel AI SDK). Conecte
https://api.agenticemail.dev/mcpcom a chave de API como token Bearer. O agente então obtém estas ferramentas diretamente:create_inbox,list_inboxes,list_threads,get_thread,list_messages,get_message,send_message,reply_to_message. - CLI (
npm i -g agenticemail-cli), para agentes orientados por shell. - SDK (
npm i agenticemailpara TypeScript, oupip install 'agenticemail[e2e]'para Python), para código.
Configuração do cliente MCP
Clientes nativos HTTP (Claude, Cursor e outros que falam streamable HTTP):
{
"mcpServers": {
"agenticemail": {
"type": "http",
"url": "https://api.agenticemail.dev/mcp",
"headers": { "Authorization": "Bearer ${AGENTICEMAIL_API_KEY}" }
}
}
}
Cliente apenas Stdio, faça a ponte:
npx mcp-remote https://api.agenticemail.dev/mcp \
--header "Authorization: Bearer $AGENTICEMAIL_API_KEY"
Fluxo principal: criar, enviar, receber, responder
CLI:
INBOX=$(agenticemail inboxes create --username assistant | jq -r .id)
agenticemail messages send "$INBOX" --to [email protected] \
--subject "Olá" --text "Enviado por um agente."
agenticemail messages list "$INBOX" --limit 5
agenticemail messages reply "$INBOX" <msgId> --text "Resolvendo."
agenticemail wait-for-message "$INBOX" --timeout 300
SDK TypeScript:
import { AgenticEmail } from "agenticemail";
const client = new AgenticEmail({ apiKey: process.env.AGENTICEMAIL_API_KEY! });
const inbox = await client.inboxes.create({ username: "assistant" });
await client.messages.send(inbox.id, {
to: ["[email protected]"],
subject: "Olá",
text: "Enviado por um agente.",
});
const { data } = await client.messages.list(inbox.id, { limit: 5 });
const msg = await client.messages.get(inbox.id, data[0].id);
await client.messages.reply(inbox.id, msg.id, { text: "Obrigado." });
SDK Python:
from agenticemail import AgenticEmail
client = AgenticEmail(api_key=os.environ["AGENTICEMAIL_API_KEY"])
inbox = client.inboxes.create(username="assistant")
client.messages.send(inbox.id, to=["[email protected]"], subject="Olá", text="...")
for m in client.messages.list(inbox.id, limit=5).data:
print(m.subject)
REST (se você não estiver usando um SDK)
URL base https://api.agenticemail.dev, cabeçalho Authorization: Bearer $AGENTICEMAIL_API_KEY.
| Método | Caminho | Propósito |
|---|---|---|
| POST | /v1/inboxes | Criar uma caixa de entrada. Corpo { "username": "assistant" } (opcional). |
| GET | /v1/inboxes | Listar caixas de entrada. |
| POST | /v1/inboxes/{id}/messages | Enviar. Corpo { "to": ["[email protected]"], "subject": "...", "text": "..." }. |
| GET | /v1/inboxes/{id}/messages | Listar. Consulta limit, cursor. |
| GET | /v1/inboxes/{id}/messages/{msgId} | Obter uma mensagem analisada. |
| POST | /v1/inboxes/{id}/messages/{msgId}/reply | Responder na thread. |
| POST | /v1/webhooks | Registrar um webhook. Corpo { "url": "...", "eventTypes": ["message.received"] }. |
Cada objeto de mensagem possui um booleano encrypted para que um cliente saiba se deve descriptografar.
Recebendo e-mails de entrada
Registre um webhook para que novos e-mails cheguem ao agente assim que chegarem:
agenticemail webhooks create --url https://your-app/hook \
--event-types message.received
Cada evento carrega o remetente analisado, assunto, texto, HTML e anexos. Um
stream WebSocket está disponível para os mesmos eventos se o agente já estiver
em execução (agenticemail events tail).
Criptografia de ponta a ponta (opcional)
Para e-mails entre agentes, o AgenticEmail oferece criptografia de ponta a ponta opcional: a
chave privada é gerada e mantida no cliente (SDK ou CLI), nunca no servidor,
portanto a plataforma não pode ler o conteúdo. Ative-a no CLI com
agenticemail keys generate <inbox> seguido de agenticemail keys publish <inbox>,
após o que messages send e messages get criptografam e descriptografam
automaticamente. No SDK, passe uma identidade e2e ao construir o cliente:
import { AgenticEmail, generateIdentity } from "agenticemail";
const client = new AgenticEmail({
apiKey: process.env.AGENTICEMAIL_API_KEY!,
e2e: { identity: generateIdentity(), autoPublish: true },
});
O que ela cobre e o que não cobre, declarado honestamente:
- É opcional e funciona apenas entre duas caixas de entrada do AgenticEmail que tenham publicado uma chave. Texto simples é o padrão.
- A chave privada é apenas do lado do cliente e nunca chega ao servidor, portanto nem a plataforma nem seu provedor de nuvem podem ler o conteúdo criptografado.
- Um envio para um endereço externo (Gmail, servidor corporativo) volta para texto simples, porque não há chave publicada para criptografar.
- Metadados de roteamento (De, Para, horário, tamanho) permanecem visíveis, conforme exigido pelo SMTP.
- Perder a chave privada e e-mails antigos criptografados se tornam irrecuperáveis. Esse é o custo de o servidor nunca manter a chave.
Documentação
Documentação completa: https://agenticemail.dev/docs