API de e-mails transacionais para agentes de IA: guia Mailpro™ v2

Se você leu nosso guia pilar sobre agentes de IA e a API Mailpro™, já sabe por que conectar um agente de IA a uma API de e-mail é o caminho mais curto entre "chatbot" e "colega digital". Este artigo aprofunda uma API específica — a Mailpro™ Email API v2 — com um setup funcional tanto para envio transacional quanto para campanhas, pilotados por Claude, GPT ou qualquer LLM com tool calling.

Resumo

• A Mailpro™ Email API v2 aceita IdClient + ApiKey via HTTPS — nenhum SDK necessário.
• Os dois endpoints mais usados são /send/sendmail.json (transacional) e /send/campaign.json (em lote).
• Qualquer LLM com tool calling pode pilotar a API por meio de um wrapper mínimo.
• Cada endpoint está documentado em 20+ linguagens em nosso portal do desenvolvedor.

E-mail guiado por IA: os casos de uso que importam

Confirmações de pedido inteligentes

Confirmações padrão têm forma de template. Seu agente de IA pode ir além: escrever uma nota pessoal ("Obrigado por escolher o XL Azul, um favorito dos clientes") e anexar recomendações dinâmicas, depois chamar a API de e-mail para disparar tudo. Você mantém a confiabilidade do template e ganha o calor de uma nota humana.

Triagem automática de suporte

Quando chega um ticket, o agente classifica, rascunha a resposta e — se a confiança for alta — envia direto. Tickets de baixa confiança vão para um humano. Esse modelo híbrido é exatamente o que times de suporte em produção estão implantando hoje.

Geração de digests

Em escala, executivos querem resumos, não enchentes. Um agente lê 40 faturas por dia e emite um digest às 18h: "Hoje: 12 pagas, 3 em atraso, 2 para revisão". Um e-mail, zero ruído. A API Email Mailpro™ cuida da entrega; o LLM, da síntese.

Setup em 5 minutos

1. Pegar seu IdClient e ApiKey

Ambos ficam na sua conta Mailpro™ em Configurações → Acesso à API. IdClient é um ID numérico; ApiKey é um GUID. Mantenha a chave em sigilo — trate como senha.

2. Conferir com /account/credits.json

Antes de ligar o Claude, confirme que as credenciais funcionam:

curl "https://api.mailpro.com/v2/account/credits.json?IdClient=YOUR_ID&ApiKey=YOUR_API_KEY"

Você deve receber um JSON com o saldo de créditos de e-mail. Em 401, revise a chave. Em 500, veja nossa página de status.

3. Explorar a referência completa

Cada endpoint está documentado — com formato de requisição/resposta e um painel "experimentar agora" — na referência da API Email v2. Abra numa segunda aba e deixe à mão.

Passo a passo: Claude envia um e-mail transacional

Usamos Claude da Anthropic neste exemplo, mas o mesmo padrão funciona com function calling da OpenAI ou tool use do Gemini — muda o SDK, a arquitetura não.

1. Definir o esquema da ferramenta

tools = [{
    "name": "send_transactional_email",
    "description": "Envia um e-mail pontual a um único destinatário via Mailpro.",
    "input_schema": {
        "type": "object",
        "properties": {
            "to":      {"type": "string", "format": "email"},
            "subject": {"type": "string"},
            "html":    {"type": "string", "description": "Corpo HTML completo"},
            "from":    {"type": "string", "description": "Endereço de remetente validado"}
        },
        "required": ["to", "subject", "html", "from"]
    }
}]

2. Escrever o prompt do sistema

Configurando envios transacionais? Os e-mails automáticos do Mailpro disparam na hora a cada gatilho — recibos, confirmações, alertas — com entrega confiável.

Você é um assistente que ajuda agentes de customer success a rascunhar e
enviar e-mails de follow-up. Quando o humano confirmar, use a ferramenta
`send_transactional_email`. Seja conciso, cordial, e inclua sempre um
link de call-to-action claro.

3. Interpretar a chamada e bater em /send/sendmail.json

import requests, json, anthropic

def execute_tool(name, args):
    if name != "send_transactional_email":
        return {"error": "ferramenta desconhecida"}
    r = requests.post(
        "https://api.mailpro.com/v2/send/sendmail.jsonu2122 para personalização por contato — a API resolve na hora do envio com os dados da sua lista.
    

Lançar a campanha com /send/campaign.json

curl -X POST "https://api.mailpro.com/v2/send/campaign.json" \
  -d "IdClient=YOUR_ID&ApiKey=YOUR_API_KEY" \
  -d "AddressBookId=42" \
  -d "IDMessage=9001" \
  -d "PlanDate=2026-05-01T09:00:00"

PlanDate é opcional — omita e a campanha sai na hora. Inclua e a Mailpro™ agenda para você. Bom padrão: deixe o agente escolher PlanDate conforme o fuso do destinatário.

Personalização com placeholders

Placeholders como [FirstName] e [LastName] são padrão; campos personalizados ([Field1], [Field2]…) mapeiam as colunas customizadas da sua lista na ordem em que você as definiu. O agente não precisa saber os valores — referencia o placeholder no HTML gerado e a API preenche por destinatário.

Importar contatos em massa pelo upload do agente

Quando a primeira ação do fluxo do agente é "adicionar 500 leads novos", você não quer 500 chamadas individuais. Use o endpoint /import/upload.json que acrescentamos recentemente:

curl -X POST "https://api.mailpro.com/v2/import/upload.json" \
  -F "IdClient=YOUR_ID" \
  -F "ApiKey=YOUR_API_KEY" \
  -F "AddressBookId=42" \
  -F "[email protected]" \
  -F "WebhookUrl=https://example.com/hooks/import-done"

O endpoint coloca o arquivo na fila e retorna um ImportJobId imediatamente. Ao final, a Mailpro™ faz POST de um callback ao seu WebhookUrl com "Body=<h1>Obrigado Ana!</h1>" \ -d "[email protected]"

Para a mesma chamada em cerca de vinte outras linguagens (PHP, Go, Ruby, C#, Java, Swift…), abra a referência da API Email v2 — cada endpoint traz o snippet equivalente pronto para copiar.

Armadilhas e dicas

• Campos de resposta em PascalCase. v2 devolve Result, IDSend, RemainingCredits (não camelCase). Se o agente faz parsing, diga isso no prompt do sistema — senão ele alucina result e idSend.
• Endereços descadastrados são ignorados silenciosamente. Use Force=1 em /email/add apenas com consentimento explícito; ele contorna a checagem de opt-out, e é risco de LGPD/GDPR caso contrário.
• Rate limit: 500 requisições/minuto por chave. Agrupe contatos em /email/add (bulk) em vez de uma /email/addSingle por contato.
• Fique com JSON. XML é suportado (sufixo .xml), mas JSON é mais rápido de parsear e combina melhor com a saída de tool call de LLMs.

Estudo de caso (fictício): "NovaFit" — rede de academias com lembretes de aula personalizados por IA

A NovaFit opera 40 academias e envia e-mails de lembrete de aula 24 horas antes de cada reserva. Historicamente os lembretes eram templates ("Oi {primeiro nome}, sua aula de yoga é amanhã às 7h"). O time de growth ligou Claude atrás do sistema de reservas: para cada lembrete, o agente lia o histórico de treinos do membro, notas da última aula e o tipo da aula que vem. Claude esc