API de Email de Entrada: Como Receber Email Programaticamente para Agentes de IA

Uma API de email de entrada permite que seu aplicativo receba email programaticamente. Em vez de consultar uma caixa de correio ou escanear uma caixa de entrada, as mensagens recebidas sao entregues ao seu codigo em tempo real via webhooks. Para agentes de IA que precisam ler, entender e responder emails, uma API de email de entrada e o bloco fundamental que torna possiveis os fluxos de trabalho de email autonomos.

Este guia explica como as APIs de email de entrada funcionam, como configurar uma com o AgentSend, e por que o modelo de webhook por caixa de correio e mais adequado para agentes de IA do que abordagens tradicionais como polling IMAP ou parsing de entrada em nivel de dominio.

O Que E uma API de Email de Entrada?

Uma API de email de entrada e um servico que aceita email de entrada em seu nome e o entrega ao seu aplicativo como dados estruturados. O fluxo tipico funciona assim: registros MX direcionam o email de entrada para os servidores do provedor da API, o provedor analisa o email bruto em um payload estruturado (remetente, assunto, corpo, anexos, cabecalhos), e entao entrega esse payload para uma URL de webhook que voce configura.

A vantagem chave sobre o recebimento de email tradicional e que seu aplicativo nunca gerencia um servidor de email. Nao ha conexao IMAP para manter, nenhum intervalo de polling POP3 para ajustar e nenhum parsing MIME bruto para implementar. Voce recebe um payload JSON limpo via HTTP POST, processa-o e responde com um codigo de status 200. Essa e toda a integracao.

Para agentes de IA, isso importa porque os agentes precisam reagir ao email de entrada em tempo real. Um agente de suporte ao cliente nao pode esperar cinco minutos pela proxima consulta IMAP para descobrir um novo ticket. Uma API de webhook de email entrega a mensagem no momento em que chega, permitindo que seu agente comece o processamento imediatamente.

Como o Email de Entrada Funciona no AgentSend

A API de recebimento de email do AgentSend e construida em torno de webhooks por caixa de correio. Quando voce cria uma caixa de correio, pode configurar uma URL de webhook que recebe cada mensagem de entrada para essa caixa de correio especifica. Cada caixa de correio e isolada — nao ha camada de roteamento compartilhada onde voce precisa inspecionar enderecos de destinatarios e despachar para o handler correto.

Cada entrega de webhook inclui uma assinatura HMAC no cabecalho X-AgentSend-Signature. Seu aplicativo verifica essa assinatura usando o segredo de webhook da sua caixa de correio para confirmar que o payload foi enviado pelo AgentSend e nao foi adulterado em transito. Se seu endpoint estiver temporariamente indisponivel, o AgentSend retenta a entrega com backoff exponencial por ate 24 horas.

Configurando o Email de Entrada

Comecar com a API de caixa de correio do AgentSend requer dois passos: criar uma caixa de correio com uma URL de webhook e depois tratar os payloads de entrada.

Passo 1: Criar uma Caixa de Correio com Webhook

Usando cURL:

curl -X POST https://api.agentsend.io/v1/inboxes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "support-agent",
    "webhook_url": "https://yourapp.com/webhooks/inbound-email",
    "webhook_secret": "whsec_your_secret_here"
  }'

Usando Python:

import requests

resp = requests.post(
    "https://api.agentsend.io/v1/inboxes",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "name": "support-agent",
        "webhook_url": "https://yourapp.com/webhooks/inbound-email",
        "webhook_secret": "whsec_your_secret_here",
    },
)
inbox = resp.json()
print(inbox["email"])  # support-agent@yourteam.agentsend.io

Passo 2: Tratar o Payload do Webhook

Quando um email chega, o AgentSend envia um payload JSON para sua URL de webhook. Aqui esta um handler minimo em Python usando Flask:

import hmac, hashlib
from flask import Flask, request, jsonify

app = Flask(__name__)
WEBHOOK_SECRET = "whsec_your_secret_here"

@app.route("/webhooks/inbound-email", methods=["POST"])
def handle_inbound():
    # Verify HMAC signature
    signature = request.headers.get("X-AgentSend-Signature")
    expected = hmac.new(
        WEBHOOK_SECRET.encode(),
        request.data,
        hashlib.sha256,
    ).hexdigest()

    if not hmac.compare_digest(signature, expected):
        return jsonify({"error": "invalid signature"}), 401

    payload = request.json
    sender = payload["from"]
    subject = payload["subject"]
    body = payload["body_text"]
    thread_id = payload["thread_id"]

    # Pass to your AI agent for processing
    process_with_agent(sender, subject, body, thread_id)

    return jsonify({"status": "ok"}), 200

API de Email de Entrada vs Abordagens Tradicionais

Existem varias maneiras de receber email programaticamente. Veja como as abordagens mais comuns se comparam para casos de uso de agentes de IA.

A diferenca critica e o isolamento. Mailgun e SendGrid operam em nivel de dominio: voce aponta os registros MX do seu dominio para os servidores deles, e todo o email de entrada para esse dominio chega a um unico endpoint de webhook. Voce e responsavel por inspecionar o endereco do destinatario em cada payload e rotea-lo para o agente correto. Com o AgentSend, cada caixa de correio tem seu proprio webhook, seu proprio segredo de assinatura e seu proprio historico de threads. Nao ha logica de roteamento para construir ou manter.

API de Caixa de Correio: Criando Caixas Programaticamente

Um dos aspectos mais poderosos de uma API de caixa de correio e a capacidade de criar caixas de correio dinamicamente. Quando sua plataforma integra um novo cliente, provisiona um novo agente de IA ou inicia um novo fluxo de trabalho, voce pode criar uma caixa de correio dedicada com uma unica chamada API. Cada caixa de correio recebe seu proprio endereco de email automaticamente — sem configuracao DNS, sem configuracao manual, sem esperar por propagacao.

Isso e particularmente util para arquiteturas multi-agente. Um sistema de suporte ao cliente poderia criar caixas de correio separadas para perguntas de faturamento, suporte tecnico e gerenciamento de contas. Cada caixa de correio e roteada para um agente especializado com seu proprio endpoint de webhook e seu proprio historico de conversacao. Escalar de um agente para cinquenta e um loop de chamadas API, nao um projeto de migracao DNS.

Casos de Uso para APIs de Email de Entrada

Uma API de email de entrada desbloqueia uma variedade de fluxos de trabalho de agentes autonomos que sao dificeis ou impossiveis de construir com infraestrutura de email tradicional.

• Agentes de suporte ao cliente — Recebem tickets de suporte via email, classificam a intencao, resolvem perguntas comuns automaticamente e escalam problemas complexos para agentes humanos com o contexto completo da conversa.
• Agentes de pesquisa — Assinam newsletters, recebem relatorios e processam fluxos de informacao de entrada. O agente le cada email, extrai dados relevantes e atualiza uma base de conhecimento sem intervencao humana.
• Agentes de agendamento — Recebem solicitacoes de reuniao e respostas de disponibilidade via email. O agente analisa o conteudo, verifica calendarios e envia respostas de confirmacao — tudo atraves de seu proprio endereco de email dedicado.
• Agentes com foco em envio e tratamento de respostas — Agentes que enviam prospecao fria, sequencias de follow-up ou notificacoes podem receber e processar respostas atraves da mesma caixa de correio, mantendo o contexto completo da conversacao.

Em cada caso, a API de email de entrada elimina a carga de infraestrutura. Seu codigo de agente se concentra em entender e responder mensagens, nao em manter conexoes IMAP, analisar MIME ou rotear emails para o handler correto.