AgentMail — E-mail para Agentes de IA
O AgentMail fornece endereços de e-mail reais (@theagentmail.net) para agentes de IA com uma API REST. Agentes podem enviar e receber e-mails, cadastrar-se em serviços (GitHub, AWS, Slack, etc.) e obter códigos de verificação. Um sistema de karma previne spam e mantém a reputação do domínio compartilhado elevada.
URL Base: https://api.theagentmail.net
Quando Usar
- Um agente de IA precisa de uma caixa de entrada/saída real para cadastros, fluxos de verificação ou comunicação transacional.
- Você precisa provisionar contas AgentMail, enviar mensagens, ler o conteúdo da caixa de entrada ou registrar webhooks de recebimento.
- Você precisa monitorar o uso de karma ou conectar eventos de e-mail na automação do agente.
Início Rápido
Todas as requisições exigem o cabeçalho Authorization: Bearer am_... (chave de API do dashboard).
Criar uma conta de e-mail (-10 karma)
curl -X POST https://api.theagentmail.net/v1/accounts \
-H "Authorization: Bearer am_..." \
-H "Content-Type: application/json" \
-d '{"address": "[email protected]"}'
Resposta: {"data": {"id": "...", "address": "[email protected]", "displayName": null, "createdAt": 123}}
Enviar e-mail (-1 karma)
curl -X POST https://api.theagentmail.net/v1/accounts/{accountId}/messages \
-H "Authorization: Bearer am_..." \
-H "Content-Type: application/json" \
-d '{
"to": ["[email protected]"],
"subject": "Olá do meu agente",
"text": "Corpo em texto simples",
"html": "<p>Corpo HTML opcional</p>"
}'
Campos opcionais: cc, bcc (arrays de string), inReplyTo, references (strings para encadeamento), attachments (array de {filename, contentType, content} onde content é base64).
Ler caixa de entrada
# Listar mensagens
curl https://api.theagentmail.net/v1/accounts/{accountId}/messages \
-H "Authorization: Bearer am_..."
# Obter mensagem completa (com corpo e anexos)
curl https://api.theagentmail.net/v1/accounts/{accountId}/messages/{messageId} \
-H "Authorization: Bearer am_..."
Verificar karma
curl https://api.theagentmail.net/v1/karma \
-H "Authorization: Bearer am_..."
Resposta: {"data": {"balance": 90, "events": [...]}}
Registrar webhook (recebimento em tempo real)
curl -X POST https://api.theagentmail.net/v1/accounts/{accountId}/webhooks \
-H "Authorization: Bearer am_..." \
-H "Content-Type: application/json" \
-d '{"url": "https://my-agent.example.com/inbox"}'
As entregas do webhook incluem dois cabeçalhos de segurança:
X-AgentMail-Signature-- digest HMAC-SHA256 em hexadecimal do corpo da requisição, assinado com o segredo do webhookX-AgentMail-Timestamp-- timestamp em milissegundos do momento do envio
Verifique a assinatura e rejeite requisições com timestamp mais antigo que 5 minutos para evitar ataques de repetição:
import { createHmac } from "crypto";
const verifyWebhook = (body: string, signature: string, timestamp: string, secret: string) => {
if (Date.now() - Number(timestamp) > 5 * 60 * 1000) return false;
return createHmac("sha256", secret).update(body).digest("hex") === signature;
};
Baixar anexo
curl https://api.theagentmail.net/v1/accounts/{accountId}/messages/{messageId}/attachments/{attachmentId} \
-H "Authorization: Bearer am_..."
Retorna {"data": {"url": "https://signed-download-url..."}}.
Referência Completa da API
| Método | Caminho | Descrição | Karma |
|---|---|---|---|
| POST | /v1/accounts | Criar conta de e-mail | -10 |
| GET | /v1/accounts | Listar todas as contas | |
| GET | /v1/accounts/:id | Obter detalhes da conta | |
| DELETE | /v1/accounts/:id | Excluir conta | +10 |
| POST | /v1/accounts/:id/messages | Enviar e-mail | -1 |
| GET | /v1/accounts/:id/messages | Listar mensagens | |
| GET | /v1/accounts/:id/messages/:msgId | Obter mensagem completa | |
| GET | /v1/accounts/:id/messages/:msgId/attachments/:attId | Obter URL do anexo | |
| POST | /v1/accounts/:id/webhooks | Registrar webhook | |
| GET | /v1/accounts/:id/webhooks | Listar webhooks | |
| DELETE | /v1/accounts/:id/webhooks/:whId | Excluir webhook | |
| GET | /v1/karma | Obter saldo + eventos |
Sistema de Karma
Cada ação tem um custo ou recompensa em karma:
| Evento | Karma | Porquê |
|---|---|---|
money_paid | +100 | Compra de créditos |
email_received | +2 | Alguém respondeu de um domínio confiável |
account_deleted | +10 | Reembolso de karma ao excluir um endereço |
email_sent | -1 | Enviar custa karma |
account_created | -10 | Criar endereços custa karma |
Regras importantes:
- Karma é concedido apenas para e-mails recebidos de provedores confiáveis (Gmail, Outlook, Yahoo, iCloud, ProtonMail, Fastmail, Hey, etc.). E-mails de domínios desconhecidos/descartáveis não geram karma.
- Você só ganha karma uma vez por remetente até que o agente responda. Se o remetente X enviar 5 e-mails sem resposta, apenas o primeiro gera karma. Responda ao X, e o próximo e-mail de X gerará karma novamente.
- Excluir uma conta reembolsa os 10 karma que custou para criá-la.
Quando o karma chega a 0, envios e criação de conta retornam HTTP 402. Sempre verifique o saldo antes de operações que consomem karma.
SDK TypeScript
import { createClient } from "@agentmail/sdk";
const mail = createClient({ apiKey: "am_..." });
// Criar conta
const account = await mail.accounts.create({
address: "[email protected]",
});
// Enviar e-mail
await mail.messages.send(account.id, {
to: ["[email protected]"],
subject: "Olá",
text: "Enviado por um agente de IA.",
});
// Ler caixa de entrada
const messages = await mail.messages.list(account.id);
const detail = await mail.messages.get(account.id, messages[0].id);
// Anexos
const att = await mail.attachments.getUrl(accountId, messageId, attachmentId);
// att.url é uma URL de download assinada
// Webhooks
await mail.webhooks.create(account.id, {
url: "https://my-agent.example.com/inbox",
});
// Karma
const karma = await mail.karma.getBalance();
console.log(karma.balance);
Tratamento de Erros
import { AgentMailError } from "@agentmail/sdk";
try {
await mail.messages.send(accountId, { to: ["[email protected]"], subject: "Oi", text: "Olá" });
} catch (e) {
if (e instanceof AgentMailError) {
console.log(e.status); // 402, 404, 401, etc.
console.log(e.code); // "INSUFFICIENT_KARMA", "NOT_FOUND", etc.
console.log(e.message);
}
}
Padrões Comuns
Cadastrar em um serviço e ler e-mail de verificação
const account = await mail.accounts.create({
address: "[email protected]",
});
// Use o endereço para se cadastrar (automação de navegador, API, etc.)
// Aguarde o e-mail de verificação
for (let i = 0; i < 30; i++) {
const messages = await mail.messages.list(account.id);
const verification = messages.find(m =>
m.subject.toLowerCase().includes("verify") ||
m.subject.toLowerCase().includes("confirm")
);
if (verification) {
const detail = await mail.messages.get(account.id, verification.id);
// Extraia o link/código de verificação de detail.bodyText ou detail.bodyHtml
break;
}
await new Promise(r => setTimeout(r, 2000));
}
Enviar e-mail e aguardar resposta
const sent = await mail.messages.send(account.id, {
to: ["[email protected]"],
subject: "Pergunta sobre pedido #12345",
text: "Você pode verificar o status?",
});
for (let i = 0; i < 60; i++) {
const messages = await mail.messages.list(account.id);
const reply = messages.find(m =>
m.direction === "inbound" && m.timestamp > sent.timestamp
);
if (reply) {
const detail = await mail.messages.get(account.id, reply.id);
// Processar resposta
break;
}
await new Promise(r => setTimeout(r, 5000));
}
Tipos
type Account = { id: string; address: string; displayName: string | null; createdAt: number };
type Message = { id: string; from: string; to: string[]; subject: string; direction: "inbound" | "outbound"; status: string; timestamp: number };
type MessageDetail = Message & { cc: string[] | null; bcc: string[] | null; bodyText: string | null; bodyHtml: string | null; inReplyTo: string | null; references: string | null; attachments: AttachmentMeta[] };
type AttachmentMeta = { id: string; filename: string; contentType: string; size: number };
type KarmaBalance = { balance: number; events: KarmaEvent[] };
type KarmaEvent = { id: string; type: string; amount: number; timestamp: number; metadata?: Record<string, unknown> };
Limitações
- Use esta skill apenas quando a tarefa corresponder claramente ao escopo descrito acima.
- Não trate a saída como substituta para validação, testes ou revisão por especialistas específicos do ambiente.
- Pare e peça esclarecimentos se as entradas, permissões, limites de segurança ou critérios de sucesso necessários estiverem ausentes.