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

Se você já leu o nosso guia sobre agentes de IA e as APIs da Mailpro™, conhece o esquema: o modelo decide, o seu código envia. Este artigo se aprofunda em uma única API, a Email API v2 da Mailpro™, e apresenta uma configuração funcional para e-mails transacionais e de campanha conduzidos por Claude, GPT ou qualquer LLM compatível com tool calling, com os endpoints e parâmetros exatos.

Em resumo

• URL base https://api.mailpro.com/v2, respostas em JSON, token bearer OAuth 2.0 (ou o método legado IdClient + ApiKey).
• Um e-mail para uma pessoa: POST /send/sendmail.json. Um modelo salvo para uma lista inteira: POST /send/campaign.json.
• Acompanhe cada e-mail transacional com GET /send/{IdSingleSend}/status.json ou com os webhooks email.delivered / email.bounced.
• Importe contatos em massa a partir de um agente com POST /import/upload.json (CSV ou XLSX, até 50 MB).

E-mail conduzido por IA: quais casos de uso valem a pena?

Confirmações de pedido inteligentes

Uma confirmação padrão é um modelo. Um agente pode acrescentar uma nota pessoal ("Obrigado por escolher a Blue XL, a favorita dos nossos clientes") e recomendações relevantes e, em seguida, enviá-la pela API. Você mantém a confiabilidade de um modelo estruturado com o calor de uma mensagem escrita à mão.

Triagem automática do suporte

Quando chega um ticket, o agente o classifica, redige uma resposta e, se tiver confiança suficiente e o assunto constar de uma lista aprovada, envia-a. Todo o resto vai para uma pessoa, com o rascunho anexado.

Resumos em vez de enxurradas

O agente lê os eventos do dia (faturas, cadastros, alertas) e envia um único resumo às 18h: "Hoje: 12 pagas, 3 em atraso, 2 para revisar." Um só e-mail, sem ruído. A API cuida da entrega; o modelo, da síntese.

Como configurar a Email API v2 em 5 minutos?

1. Obtenha as credenciais

Na sua conta Mailpro™, acesse Settings → API access. Para um agente, crie um cliente OAuth e solicite apenas os scopes de que ele precisa, normalmente email:send e email:read. As credenciais legadas IdClient (numérico) e ApiKey (GUID) também funcionam, mas não são limitadas por scopes; por isso, reserve-as para os seus próprios scripts de back-end.

2. Verifique a conexão

curl -H "Authorization: Bearer ACCESS_TOKEN" \
  https://api.mailpro.com/v2/account/credits.json

Você deve receber os seus créditos de e-mail restantes em JSON. Um 401 significa que o token ou a chave estão incorretos; um 403 insufficient_scope significa que falta account:read ao token.

3. Encontre o seu ID de remetente

Os e-mails são enviados a partir de um endereço de remetente validado. GET /senderEmail/list.json retorna esses endereços com os respectivos IDs; é esse ID que você vai passar como IDEmailExp.

Passo a passo: faça o Claude enviar um e-mail transacional

O exemplo usa o Claude, da Anthropic, mas o mesmo esquema funciona com o function calling da OpenAI ou o tool use do Gemini: o SDK muda, a arquitetura não.

1. Defina a ferramenta

tools = [{
  "name": "send_transactional_email",
  "description": "Envia um e-mail para um cliente via Mailpro.",
  "input_schema": {
    "type": "object",
    "properties": {
      "to":      {"type": "string"},
      "subject": {"type": "string"},
      "html":    {"type": "string", "description": "Corpo HTML completo"}
    },
    "required": ["to", "subject", "html"]
  }
}]

2. Escreva o prompt de sistema

Você ajuda os agentes de sucesso do cliente a redigir e enviar e-mails de acompanhamento.
Só chame send_transactional_email depois que a pessoa confirmar.
Seja conciso e cordial, e inclua sempre um link com uma chamada para ação clara.

3. Execute a chamada para /send/sendmail

import requests

def send_transactional_email(args, token, sender_id):
    r = requests.post(
        "https://api.mailpro.com/v2/send/sendmail.json",
        headers={"Authorization": f"Bearer {token}"},
        data={
            "IDEmailExp": sender_id,       # de /senderEmail/list
            "EmailData":  args["to"],      # email,campo1,campo2...
            "Subject":    args["subject"],
            "BodyHTML":   args["html"],
            "ActivateStatistics": "true",  # rastreia aberturas e cliques
        },
    )
    r.raise_for_status()
    return r.json()   # {"SingleSend": {"IdSingleSend": 8001, ...}}

Campos opcionais úteis: DatePlanned (ISO 8601) para agendar em vez de enviar na hora, ReplyTo, BodyText para uma versão em texto simples e attachments. Devolva o JSON ao modelo como resultado da ferramenta para que ele possa avisar o usuário de que o e-mail está a caminho.

Está integrando envios transacionais? Os e-mails automáticos da Mailpro disparam instantaneamente a cada gatilho — recibos, confirmações, alertas — com uma entrega em que você pode confiar.

4. Confirme a entrega

GET /send/8001/status.json retorna delivered, bounced (com BounceType e o DiagCode do servidor), deferred, sent, scheduled ou queued. Conte com delivered cerca de cinco minutos após a entrega ao servidor. Para um retorno em tempo real, assine os webhooks email.delivered e email.bounced em vez de consultar o status repetidamente.

Campanhas: o agente prepara, uma pessoa aperta enviar

Para um envio a uma lista inteira, o agente trabalha com um modelo salvo em vez de HTML bruto:

curl -X POST https://api.mailpro.com/v2/send/campaign.json \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -d "IDMessage=55" \
  -d "IDEmailExp=201" \
  -d "ListId=101" \
  -d "Campaign=1" \
  -d "TitleCampaign=April newsletter" \
  -d "DatePlanned=2026-05-01T09:00:00"

DatePlanned é opcional: se você o omitir, a campanha sai imediatamente. Um bom esquema é deixar o agente escolher a lista, o modelo e um horário de envio de acordo com o fuso horário do público e, depois, mostrar o plano a uma pessoa que o aprove. As campanhas agendadas ainda podem ser remarcadas com PATCH /send/{IdSend}/reschedule.json ou canceladas com POST /send/{IdSend}/cancel.json.

Personalização com campos

Em /send/sendmail, EmailData recebe o endereço seguido de até 25 valores ([email protected],Alice,Dupont,Paris) que preenchem os campos de personalização do modelo. Nas campanhas, os campos vêm dos dados de cada contato da lista. O agente só precisa colocar o campo no seu HTML; a API o preenche para cada destinatário.

Importe contatos em massa a partir de um arquivo enviado por um agente

Quando o primeiro passo de um fluxo de trabalho é "adicione estes 500 novos leads", não faça 500 chamadas à API. Envie um único arquivo:

curl -X POST https://api.mailpro.com/v2/import/upload.json \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -F "ListId=42" \
  -F "[email protected]" \
  -F "WebhookUrl=https://example.com/hooks/import-done"

O arquivo deve estar em UTF-8, com uma linha de cabeçalho que inclua Email; as demais colunas são associadas aos campos personalizados da lista. O endpoint retorna um ImportJobId imediatamente, processa o arquivo em segundo plano e chama a sua WebhookUrl com a contagem de linhas importadas, ignoradas e inválidas.

Armadilhas e dicas

• Endereços descadastrados são recusados. A API responde "Email address unsubscribed." com um 400. Diga ao agente que isso é definitivo, e não um erro para tentar de novo.
• Fique de olho nos créditos. "Not enough credit available." volta como um 403. Assine o webhook credits.low para que uma pessoa recarregue antes que o agente bata no limite.
• Atenção à cota de requisições. As chamadas à API contam para uma cota mensal compartilhada pelas APIs de Email, CRM e SMS (GET /account/limits.json). Limite as chamadas de ferramentas por conversa e espace as novas tentativas ao receber um 429.
• Fique com o JSON. O XML é suportado com o sufixo .xml, mas o JSON é mais simples para a saída das ferramentas de um LLM.
• Autentique o seu domínio. Mesmo personalizados e escritos por IA, os e-mails continuam precisando de SPF, DKIM e DMARC para chegar à caixa de entrada; veja o nosso guia sobre a entrega de e-mail.

Estudo de caso (fictício): "NovaFit", uma rede de academias com lembretes de aula escritos por IA

A NovaFit administra 40 academias e envia um lembrete 24 horas antes de cada aula reservada. Antes, os lembretes eram um único modelo ("Olá, Anna, a sua aula de ioga é amanhã às 7h"). A equipe colocou o Claude por trás do sistema de reservas: para cada lembrete, o agente lê a frequência recente do aluno e o tipo de aula, escreve uma frase pessoal ("Na semana passada você manteve a postura do guerreiro por um minuto inteiro, pronta para o próximo nível?") e envia o e-mail com /send/sendmail. Os bounces retornam pelo webhook email.bounced e são sinalizados para a recepção. A taxa de abertura dos lembretes subiu de 46% para 63% e a frequência às aulas aumentou 8 pontos, sem nenhuma alteração no volume de e-mails.

Próximos passos

A Email API v2 cuida do envio. Se o seu agente também precisa gerenciar contatos, tags, segmentos e campos personalizados, leia o nosso guia da CRM API v3 para IA. Para mensagens de texto, veja como enviar SMS com um agente de IA. Está comparando uma plataforma gerenciada com um serviço de envio bruto? Confira o nosso guia das melhores alternativas ao Amazon SES. Referência completa: a documentação da Email API v2.