Automatizar seu CRM com IA: guia da API Contact Mailpro™ v3

A maior parte dos dados de CRM é inserida duas vezes — uma em um formulário, outra na sua cabeça quando você esquece de atualizar o formulário. Agentes de IA fecham essa lacuna. Dê a Claude, GPT ou Gemini uma API de gerenciamento de contatos e uma descrição clara da tarefa, e eles saberão criar ou atualizar contatos, aplicar tags, construir segmentos e limpar dados sem que um humano toque uma interface. Este guia mostra exatamente como fazer isso com a API Contact Mailpro™ v3.

Resumo

• A CRM v3 é só JSON (snake_case), autenticada por JWT Bearer Token.
• Pegue um token via POST /v3/token — válido por 365 dias.
• Contatos são identificados por UUIDs; listas, tags e campos por inteiros.
• Cada endpoint está documentado em 20+ linguagens em nosso portal do desenvolvedor.

Por que expor seu CRM a um agente de IA?

Agentes como nova camada de entrada

Entrada de CRM por formulário é um problema resolvido — e mal resolvido há 20 anos. Agentes permitem pular o formulário. Um usuário digita "novo lead: Alice da ShopCorp, interessada no plano enterprise, retornar semana que vem". O agente parseia, chama POST /v3/Contact com dados estruturados, aplica a tag "interesse-enterprise" e agenda o follow-up. Zero digitação em formulário.

Três cenários concretos

• Enriquecimento de leads. Um webhook dispara a partir de um formulário; o agente enriquece com fontes públicas, upsertea o contato na Mailpro™ v3, e marca com um lead score.
• Higiene de listas. Cron semanal; o agente consulta listas em busca de duplicatas, dados velhos, contatos não classificados, e remaneja tags.
• Segmentação dinâmica. "Move todos que abriram a campanha de promoção para o segmento warm-leads" — o agente lê estatísticas de v2 e chama v3 para retaggar.

Autenticar um agente de IA com JWT

POST /v3/token com grant password

A forma mais simples:

curl -X POST "https://api.mailpro.com/v3/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password" \
  -d "[email protected]" \
  -d "password=YOUR_API_KEY"

Resposta:

{
  "access_token": "eyJhbGciOi...",
  "token_type": "bearer",
  "expires_in": 31535999,
  "refresh_token": "eyJhbGciOi..."
}

Guarde o access_token com segurança (variável de ambiente no servidor, cofre) e envie como Authorization: Bearer <token> em cada chamada v3 subsequente.

Vida útil do token: 365 dias

Tokens Mailpro™ são longevos por design — agentes de IA rodam continuamente, você não quer tempestades de refresh. Se precisar rotacionar, use o fluxo de refresh token ou emita um novo token periodicamente.

Grants de terceiros

Se você constrói uma integração Zapier, Make ou Microsoft Flow, use os grants dedicados (zapier, microsoft-flow, etc.). Eles emitem um JWT com papel ThirdParty. A maioria das integrações de agentes fica bem com o grant password.

Passo a passo: "Claude, adicione este contato, tag VIP, coloque na lista 42"

É aqui que o design da v3 brilha: um prompt, três chamadas de API, zero interface.

1. Esquemas das ferramentas

Dê ao agente três ferramentas estreitas — fão uma grande. Ferramentas estreitas são escolhidas mais corretamente pelo modelo.

tools = [
    {
        "name": "upsert_contact",
        "description": "Cria ou atualiza um contato Mailpro pelo e-mail.",
        "input_schema": {
            "type": "object",
            "properties": {
                "email":      {"type": "string", "format": "email"},
                "first_name": {"type": "string"},
                "last_name":  {"type": "string"},
                "fields":     {"type": "object", "description": "Valores de campos personalizados"}
            },
            "required": ["email"]
        }
    },
    {
        "name": "tag_contact",
        "description": "Aplica uma tag a um contato pelo UUID.",
        "input_schema": {
            "type": "object",
            "properties": {
                "contact_id": {"type": "string"},
                "tag_name":   {"type": "string"}
            },
            "required": ["contact_id", "tag_name"]
        }
    },
    {
        "name": "add_to_list",
        "description": "Adiciona um contato a uma lista Mailpro pelo ID.",
        "input_schema": {
            "type": "object",
            "properties": {
                "contact_id": {"type": "string"},
                "list_id":    {"type": "integer"}
            },
            "required": ["contact_id", "list_id"]
        }
    }
]

2. O raciocínio do agente

Dado o prompt "Adicione Alice Zhang da ShopCorp ([email protected]), tag VIP, coloque-a na lista 42", Claude raciocina:

1. Chamar upsert_contact com {email: "[email protected]", first_name: "Alice", last_name: "Zhang"}.
2. Ler o contact_id retornado.
3. Chamar tag_contact com {contact_id, tag_name: "VIP"}.
4. Chamar add_to_list com {contact_id, list_id: 42}.

Três chamadas de ferramenta, uma intenção do usuário. Isso é o loop do agente.

3. Executar em sequência

def execute_tool(name, args, token):
    base = "https://api.mailpro.com/v3"
    headers = {"Authorization": f"Bearer {token}", "Content-Type": "application/json"}

    if name == "upsert_contact":
        r = requests.post(f"{base}/Contact", headers=headers, json={
            "email": args["email"],
            "first_name": args.get("first_name"),
            "last_name": args.get("last_name"),
            "fields": args.get("fields", {})
        })
        return r.json()

    elif name == "tag_contact":
        r = requests.post(f"{base}/Tag/{args['tag_name']}/Contact",
                          headers=headers, json={"contact_id": args["contact_id"]})
        return r.json()

    elif name == "add_to_list":
        r = requests.post(f"{base}/List/{args['list_id']}/Contact",
                          headers=headers, json={"contact_id": args["contact_id"]})
        return r.json()

4. Tratar regras de negócio (respostas 406)

Cansado da manutenção manual de listas? Os planos do Mailpro incluem a API de Contatos para seu agente de IA manter as listas limpas e segmentadas — automaticamente.

v3 retorna HTTP 406 para violações de regras de negócio, com body JSON assim:

{ "Message": "A contact already exist with the same Email" }

Motivos 406 comuns:

• Email cannot be empty
• Email has an invalid format
• A contact already exist with the same Email
• The email address was unsubscribed permanently
• One or more lists have reached the contact limit

Ensine o agente a ler o campo Message e a se recuperar com elegância: em duplicata, buscar o contato existente e atualizar em vez de desistir. Em e-mail inválido, pedir correção ao usuário.

Campos personalizados e segmentos

Criar um campo personalizado (/v3/Field)

curl -X POST "https://api.mailpro.com/v3/Field" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "lead_score", "field_type": "Number"}'

Construir um segmento com regras (/v3/Segment)

Segmentos são dinâmicos — atualizam quando os dados dos contatos mudam. Agentes adoram: crie um segmento uma vez, as regras capturam contatos para sempre.

"Claude, mova quem abriu a última campanha para o segmento Hot Leads"

Exatamente o tipo de tarefa multi-etapas em que v3 brilha. O agente:

1. Consulta as stats v2 (/stats/open) para achar quem abriu a última campanha.
2. Para cada um, chama v3 para adicionar ao segmento Hot Leads (via tag ou atualizando um campo de score).

Fluxos cross-API como este são exatamente o que agentes de IA unificados destravam.

Importar contatos em escala via agente

Quando o agente reage a um evento "nova lista de leads" (upload de CSV, planilha compartilhada, exportação de CRM), não faça loop um-a-um. Use o endpoint de import em lote:

curl -X POST "https://api.mailpro.com/v3/Import/Upload" \
  -H "Authorization: Bearer $TOKEN" \
  -F "id_list=42" \
  -F "[email protected]" \
  -F "webhook_url=https://example.com/hooks/import-done"

O endpoint retorna um import_job_id imediatamente. Quando o processamento termina, a Mailpro™ faz POST de um callback ao seu webhook_url com os totais (importados / ignorados / inválidos). O agente pode usar o webhook como sinal para rodar ações seguintes ("import pronto → lançar campanha de boas-vindas").

O fluxo completo do agente: enriquecimento de vendas

Gatilho: webhook de novo cliente Stripe. Objetivo: o agente deve enriquecer, adicionar ao CRM e enviar um e-mail de boas-vindas.

1. Enriquecer. O agente chama uma API de enriquecimento externa (Clearbit, People Data Labs, scraper próprio) para pegar nome da empresa, cargo, LinkedIn.
2. Upsert na Mailpro™ v3. POST /v3/Contact com e-mail + campos enriquecidos.
3. Tag e lista. O agente marca com stripe-customer e adiciona \u00e0 lista Clientes Pagos.
4. E-mail de boas-vindas. O agente chama a API v2 /send/sendmail.json com boas-vindas personalizadas.

Quatro chamadas, duas APIs, um onboarding sem costuras. Custo humano: zero.

Dicas e armadilhas

snake_case vs PascalCase

v3 é snake_case (first_name, list_id, contact_id). v2 é PascalCase (FirstName, ListId). Se o agente fala com as duas APIs, diga no prompt do sistema para ele não inventar nomes de campo.

Erros de negócio retornam 406, não 400

400 = dados malformados. 406 = dados válidos, mas violam regra de negócio. O agente precisa distinguir — 400 é bug de código; 406 é um resultado normal do qual se recuperar.

50 mil requisições mensais por padrão

v3 tem um teto mensal por conta. Agentes em loop agressivo batem nele. Agrupe com /v3/Contact/Multiple quando possível. O teto està no seu painel da conta.

Estudo de caso (fictício): "CoraSegura" — corretor IA triando 2.000 leads por dia

CoraSegura é um agregador de corretores de seguros. Todo dia, 2.000 leads aterrissam no webhook vindos de comparadores. Antes, dois operadores limpavam e encaminhavam cada lead manualmente. Com Claude ligado à Mailpro™ v3, o fluxo virou:

1. Webhook dispara → Claude recebe o JSON do lead.
2. Claude enriquece (valida e-mail, normaliza telefone para E.164, deduz o produto de seguro a partir do texto livre).
3. Claude chama upsert_contact, aplica tags (auto, residencial, vida), adiciona à lista certa.
4. Claude pontua o lead (0–100) e escreve o score no campo lead_score.
5. Leads com score alto disparam automaticamente um e-mail de boas-vindas v2.

O tempo de processamento por lead caiu de 6 minutos (humano) para 4 segundos (agente). A qualidade dos dados melhorou — Claude é mais rigoroso na validação de e-mail do que humanos cansados. Os dois operadores foram realocados para trabalho de corretagem de verdade.

Próximo passo

Com v3 cuidando do seu CRM e v2 cuidando do envio, falta o SMS. Vá ao nosso guia da API SMS para dar ao agente o último canal. Ou volte ao guia pilar.

Documentação de referência: API CRM v3. Preços: preços Mailpro.

FAQ

A Mailpro v3 suporta OAuth ou só grant password?

Ambos. password é o mais simples; client_credentials para fluxos máquina-a-máquina; zapier, automateio e microsoft-flow são grants dedicados de terceiros que emitem um JWT com papel ThirdParty.

Consigo migrar contatos da Mailpro v2 para v3?

Sim — as duas APIs acessam o mesmo banco de contatos. Um contato criado via v2 é visível e gerenciável via v3, e vice-versa.

Como funcionam campos personalizados com IA?

Crie o campo uma vez via POST /v3/Field com um tipo (Text, Number, Date, Boolean). Daí em diante, o agente pode setar valores nos contatos via fields no payload. Campos personalizados também servem como variáveis de personalização em campanhas.

Qual a diferença entre lista, tag e segmento?

Uma lista é uma coleção estática à qual vocà adiciona contatos explicitamente. Uma tag é um rótulo leve (um contato pode ter vários). Um segmento é uma consulta dinâmica — "todos os contatos onde tag='VIP' e country='BR'" — que se atualiza sozinha quando os dados dos contatos mudam. Veja também nosso guia de entregabilidade para como uma boa segmentação melhora a entrega.