Como enviar e-mails e SMS com um agente de IA (guia da API Mailpro™)

Um agente de IA que só sabe conversar é um chatbot. Um agente de IA capaz de enviar o e-mail, mandar um SMS para o cliente e atualizar o cadastro do contato é um colega de equipe. Este guia mostra como conectar o Claude, o GPT ou qualquer LLM que suporte tool calling às APIs da Mailpro™, para que o seu agente envie e-mails e SMS sozinho, com segurança, e com cada mensagem registrada e rastreável.

Resumo

• A Mailpro™ oferece três APIs HTTPS que o seu agente pode chamar: a Email API v2 (e-mails transacionais e campanhas), a CRM API v3 (contatos, listas, tags) e a SMS API.
• Cada ação fica encapsulada em uma pequena ferramenta (tool): o modelo decide quando chamá-la e o seu código faz a requisição HTTP.
• Autentique-se com um token OAuth 2.0 limitado aos scopes de que o agente precisa, nunca com a sua chave de API principal dentro de um prompt.
• Use webhooks (email.delivered, email.bounced, sms.delivered…) para que o agente saiba o que realmente aconteceu.
• Mantenha uma etapa de aprovação humana para envios em massa e destinatários desconhecidos.

Por que dar ao seu agente de IA o poder de enviar e-mails e SMS?

Porque a maior parte do valor de um agente está no que ele faz depois de entender o pedido. Um agente de suporte que redige uma resposta é útil; um que envia a resposta, confirma o reembolso por SMS e marca o contato com a tag "reembolsado" fecha o chamado. Tarefas típicas que já funcionam bem hoje:

• Acompanhamento de pedidos e reservas — um e-mail de confirmação com uma nota pessoal escrita pelo agente, mais um SMS de lembrete na véspera.
• Triagem do suporte — o agente classifica o chamado, responde por e-mail às solicitações simples e encaminha o restante para uma pessoa.
• Códigos de uso único e alertas — o agente gera um código, envia por SMS e confere quando o usuário responde.
• Resumos diários — o agente lê os dados do dia e envia um único e-mail de resumo em vez de quarenta notificações.

O que são as APIs da Mailpro™, em 30 segundos?

As três aceitam o mesmo token OAuth 2.0 (emitido uma única vez em https://api.mailpro.com/oauth/token), retornam JSON e compartilham uma cota mensal de requisições por conta. Cada endpoint está documentado, com exemplos de requisição e resposta, no portal para desenvolvedores da Mailpro™.

Como um agente de IA chama uma API de e-mail ou SMS?

Por meio de tool calling (a Anthropic chama de tool use, a OpenAI de function calling). Você descreve cada ação como uma ferramenta com um esquema JSON. Quando o modelo decide que uma ação é necessária, ele retorna uma chamada de ferramenta com argumentos; o seu código valida esses argumentos, chama a API da Mailpro™ e devolve o resultado ao modelo. O modelo nunca tem acesso às suas credenciais e nunca faz a requisição HTTP por conta própria.

Se você preferir não escrever o loop, as mesmas ferramentas podem ser expostas por meio de um servidor MCP (Model Context Protocol), que o Claude Desktop, o Claude Code e o Cursor conseguem usar diretamente. As chamadas de API por trás são as mesmas.

Exemplo mínimo: o Claude envia um e-mail e um SMS

1. Obtenha um token com scopes limitados

curl -X POST https://api.mailpro.com/oauth/token \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "scope=email:send email:read sms:send"

Crie o client ID e o secret na sua conta Mailpro™, em Settings → API access (Configurações → acesso à API). O token de acesso vale por 20 minutos; o seu código solicita um novo quando ele expira.

2. Defina as ferramentas

tools = [
  {
    "name": "send_email",
    "description": "Envia um e-mail transacional para um único destinatário.",
    "input_schema": {
      "type": "object",
      "properties": {
        "to": {"type": "string"},
        "subject": {"type": "string"},
        "html": {"type": "string"}
      },
      "required": ["to", "subject", "html"]
    }
  },
  {
    "name": "send_sms",
    "description": "Envia um SMS (máx. 160 caracteres) para um único número de celular.",
    "input_schema": {
      "type": "object",
      "properties": {
        "to": {"type": "string", "description": "Formato internacional, por ex. +41791234567"},
        "message": {"type": "string"}
      },
      "required": ["to", "message"]
    }
  }
]

3. Execute as chamadas de ferramenta

import requests

API = "https://api.mailpro.com"
SENDER_ID = 201  # obtido com GET /v2/senderEmail/list

def run_tool(name, args, token):
    h = {"Authorization": f"Bearer {token}"}
    if name == "send_email":
        r = requests.post(f"{API}/v2/send/sendmail.json", headers=h, data={
            "IDEmailExp": SENDER_ID,
            "EmailData": args["to"],
            "Subject": args["subject"],
            "BodyHTML": args["html"],
            "ActivateStatistics": "true",
        })
    elif name == "send_sms":
        r = requests.post(f"{API}/sms/send/add_single.json", headers=h, data={
            "to": args["to"],
            "message": args["message"],
        })
    else:
        return {"error": "unknown tool"}
    return r.json()

Conecte run_tool ao seu loop habitual do Claude (ou da OpenAI): envie a mensagem do usuário com tools, execute cada chamada de ferramenta que o modelo retornar e devolva o resultado como tool result. A chamada de e-mail retorna um IdSingleSend; a de SMS retorna um Id. Guarde os dois: são eles que permitem acompanhar a entrega.

Prefere não programar? Os e-mails automáticos da Mailpro enviam confirmações, lembretes e alertas a partir de gatilhos que você configura em poucos cliques.

Como o agente sabe se a mensagem foi entregue?

Uma resposta 200 significa que a Mailpro™ aceitou a mensagem, não que ela chegou à caixa de entrada ou ao celular. Há duas formas de fechar o ciclo:

• Consulta periódica (polling) — GET /v2/send/{IdSingleSend}/status.json retorna queued, sent, delivered, deferred ou bounced para um e-mail transacional.
• Webhooks (recomendado) — você se inscreve uma vez com POST /webhooks e a Mailpro™ envia um evento assinado para o seu servidor: email.delivered, email.bounced, email.opened, sms.delivered, sms.failed e outros. Cada requisição traz um cabeçalho HMAC X-Mailpro-Signature para você verificar que ela veio mesmo da Mailpro™.

Repasse esses eventos ao agente e ele poderá reagir sozinho: reenviar por e-mail um SMS que falhou, ou sinalizar para uma pessoa um endereço com bounce.

Segurança e boas práticas para envios feitos por IA

Dê ao agente um token com scopes limitados, não as suas chaves

Os tokens OAuth carregam scopes como email:send, email:read, contacts:read ou sms:send. Um agente que só envia confirmações não precisa de contacts:write. Uma chamada fora dos seus scopes falha com 403 insufficient_scope. Guarde o client secret em variáveis de ambiente no servidor; nunca o coloque em um prompt.

Mantenha uma pessoa no circuito para envios de risco

Deixe o agente enviar sozinho as mensagens individuais, mas exija aprovação para campanhas (/v2/send/campaign, /sms/send/add), para destinatários fora das suas listas de contatos e para qualquer mensagem que fale de dinheiro. Uma simples lista de permissões (allowlist) de domínios ou listas de destinatários no código das suas ferramentas impede que um prompt mal-intencionado acabe disparando um envio em massa para os seus clientes.

Respeite a cota e espere antes de tentar de novo após um erro

As suas requisições de API compartilham uma cota mensal entre as APIs de Email, CRM e SMS (consulte com GET /v2/account/limits.json). Um agente preso em um loop pode esgotá-la rapidamente: limite o número de chamadas de ferramenta por conversa e, diante de respostas 429 e 5xx, tente de novo com espera exponencial (exponential backoff) em vez de repetir imediatamente.

Respeite o consentimento e os descadastramentos

Contatos descadastrados e na lista negra são ignorados automaticamente, e a API avisa você disso. Não deixe o agente contornar essa regra. Para SMS, confira as regras de cada país de destino antes de enviar mensagens de marketing.

Registre tudo

Salve cada chamada de ferramenta com os argumentos, a resposta da API e o ID retornado. Quando um cliente perguntar "por que eu recebi isto?", você consegue responder em segundos.

Estudo de caso (fictício): a "LoopKart" deixa o Claude escrever os e-mails pós-compra

A LoopKart é uma pequena loja virtual que vende equipamentos de cozinha recondicionados. Os e-mails pós-compra eram um único modelo igual para todo mundo. A equipe conectou o Claude à Email API da Mailpro™ com uma única ferramenta send_email: depois de cada pedido, o agente lê o pedido e o histórico do cliente, escreve um parágrafo curto e personalizado (dicas de cuidado para o produto exato, uma observação se for um cliente recorrente) e envia o e-mail por meio de /v2/send/sendmail. Uma segunda ferramenta envia um SMS quando o pacote é despachado. Pedidos acima de um valor definido, e qualquer mensagem que mencione reembolso, aguardam o clique de uma pessoa antes do envio. A configuração levou dois dias, a maior parte gasta escrevendo e testando a regra de aprovação.

Perguntas frequentes

Quais modelos de IA funcionam com a API da Mailpro™?

Qualquer modelo que suporte tool calling ou function calling: Claude, GPT, Gemini, Mistral e modelos open source servidos com um framework de tool calling. A API em si é HTTPS e JSON simples, então o modelo só precisa de uma camada de integração leve.

Preciso de um plano pago da Mailpro™ para começar?

Não. Você pode começar no plano gratuito, testar tudo e fazer upgrade quando o seu volume justificar. Veja os preços da Mailpro.

O agente pode enviar para uma lista inteira?

Sim, com /v2/send/campaign para e-mail e /sms/send/add para SMS. Recomendamos uma etapa de aprovação humana para esses envios.

Existe um servidor MCP?

Você pode expor as mesmas ferramentas por meio de qualquer framework de servidor MCP; as chamadas por trás são as mostradas acima.

Para saber mais

• E-mails transacionais e campanhas em detalhe: API de e-mails transacionais para agentes de IA
• Contatos, listas e tags: Automatize o seu CRM com IA
• SMS, códigos e lembretes: Enviar SMS com um agente de IA
• Chegar à caixa de entrada: entrega de e-mail
• O gateway SMS propriamente dito: API SMS da Mailpro