Enviar SMS com um agente de IA via a API SMS Mailpro™

E-mail é o canal padrão. SMS é o canal da urgência. Quando seu agente de IA precisa alcançar um humano real em segundos — uma queda, um alerta de fraude, um OTP, uma atualização de entrega — o SMS é o que realmente é lido em até um minuto. Este guia mostra como ligar Claude, GPT ou qualquer LLM com tool calling à API SMS Mailpro™, tanto para envios unitários quanto para campanhas em massa.

Resumo

• A API SMS Mailpro™ autentica com id_client + api_key via HTTPS.
• Use /send/add_single.json para SMS unitário e /send/add.json para envios em massa.
• Números em formato internacional E.164 (ex. +5511987654321) ou com prefixo 00 — a API aceita os dois e armazena na forma normalizada.
• Cada endpoint está documentado em 20+ linguagens em nosso portal do desenvolvedor.

Onde SMS guiado por IA realmente faz sentido

Alertas em tempo real

Seu pipeline de monitoramento detecta um pico de erros 5xx. Um agente de IA lê a anomalia, classifica a severidade e dispara um SMS ao engenheiro de plantão com contexto ("API v3 com 12× de taxa de erro nos últimos 5 min, endpoints de CRM afetados") — não um bip vazio. Diagnóstico mais rápido, menos fadiga de alerta.

OTPs e fluxos de dois fatores

O agente recebe uma requisição "autentique este usuário", gera um código de 6 dígitos, guarda com expiração e envia por SMS. O usuário digita de volta, o agente verifica. Hoje é um fluxo customizado; com o próximo endpoint Verify/OTP (veja a roadmap da API SMS), vai ser uma única chamada.

Fallback multicanal

O e-mail não foi aberto em 2 horas, mas é urgente. O agente cai para SMS — "Sua consulta é em 1 hora" — usando o mesmo registro de contato da Mailpro™ v3. Orquestração cross-canal guiada pelo raciocínio do LLM.

Campanhas orientadas a eventos

Black Friday ao meio-dia: o agente escolhe a audiência por frescor ("clientes que abriram algum e-mail nos últimos 14 dias"), escreve uma oferta de 140 caracteres e dispara uma campanha via /send/add.json. Oferta no ar em menos de um minuto, zero cliques em dashboard.

Setup e modelo de preço SMS

id_client + api_key

Mesmo padrão de auth da API e-mail v2. Os dois valores estão na sua conta Mailpro™ em Configurações → Acesso à API. A API SMS usa parâmetros em snake_case (id_client, não IdClient) — pequena diferença em relação a v2, vale sinalizar no prompt do sistema do agente.

Créditos, tarifas por país, saldo de teste

SMS não têm preço fixo: o custo por mensagem depende do país de destino. Verifique o saldo a qualquer momento:

curl "https://api.mailpro.com/sms/credit/get.json?id_client=YOUR_ID&api_key=YOUR_API_KEY"

Resposta:

{ "TotalCredits": 1476 }

Para preços por país, veja os preços Mailpro.

Sandbox

Ainda sem sandbox dedicada — teste com volumes pequenos na conta real. Comece com /send/add_single.json enviando para o seu próprio número antes de abrir a torneira do bulk.

Passo a passo: SMS unitário enviado por um agente de IA

1. Esquema da ferramenta

tools = [{
    "name": "send_sms",
    "description": "Envia um SMS unitário a um número via Mailpro.",
    "input_schema": {
        "type": "object",
        "properties": {
            "to":      {"type": "string", "description": "Número em formato internacional E.164, ex +5511987654321"},
            "message": {"type": "string", "description": "Corpo do SMS, max 160 car. por segmento"}
        },
        "required": ["to", "message"]
    }
}]

2. Formatação dos números

Use o formato internacional E.164: sinal +, código do país, número nacional, sem espaços nem traços. O prefixo 00 no lugar de + também funciona. Exemplos:

• Brasil: +5511987654321
• Portugal: +351912345678
• Estados Unidos: +15551234567
• Angola: +244923456789

Se o agente receber entradas bagunçadas ("(11) 98765-4321"), normalize antes de enviar — bibliotecas como phonenumbers (Python) ou libphonenumber-js (Node) fazem isso sem esforço.

3. Chamar /send/add_single.json

curl -X POST "https://api.mailpro.com/sms/send/add_single.json" \
  -d "id_client=YOUR_ID&api_key=YOUR_API_KEY" \
  -d "to=+5511987654321" \
  -d "message=Seu código de verificação é 482913. Válido 10 min."

Resposta:

{
  "Result": "OK",
  "IdSend": 98765,
  "RemainingCredits": 1474
}

4. Status de entrega na resposta

Result: "OK" significa que o SMS foi aceito pelo gateway — ainda não entregue no aparelho. Para confirmação de entrega (DLR), ouça o próximo webhook sms.delivered (veja a roadmap da API SMS). Por enquanto, RemainingCredits indica que o envio foi cobrado.

SMS em massa: atingir uma lista inteira

Gerenciar listas de números (/list, /phone)

Listas de SMS são o equivalente dos cadernos de endereços de e-mail. Endpoints para listar, adicionar, editar e deletar listas e números ficam em /list/*.json e /phone/*.json.

Enviar uma campanha com /send/add.json

curl -X POST "https://api.mailpro.com/sms/send/add.json" \
  -d "id_client=YOUR_ID&api_key=YOUR_API_KEY" \
  -d "id_list=11088" \
  -d "message=Black Friday: 30% off até meia-noite. mailp.ro/bf2026"

O endpoint coloca a campanha na fila e dispara SMS para cada número da lista.

Agendado vs imediato

Adicione plan_date=2026-11-27T12:00:00 para agendar. Omita para envio imediato. O agente pode escolher o horário conforme o fuso dos destinatários — mas atenção ao tempo agregado: 10.000 SMS podem levar vários minutos para atravessar o gateway.

Importar números em massa via arquivo

Assim como a API de e-mail, a API SMS agora expõe um endpoint de upload de arquivo:

Construindo um agente de IA que envia SMS? Os planos do Mailpro incluem a API de SMS, relatórios de entrega e o volume necessário — a um preço previsível.

curl -X POST "https://api.mailpro.com/sms/import/upload.json" \
  -F "id_client=YOUR_ID" \
  -F "api_key=YOUR_API_KEY" \
  -F "id_list=11088" \
  -F "[email protected]" \
  -F "webhook_url=https://example.com/hooks/import-done"

A primeira coluna do CSV deve se chamar Phone ou PhoneNumber. Números são normalizados no servidor; entradas inválidas são ignoradas (e reportadas no sumário do job). Spec completa na seção Import da referência SMS.

Exemplos de código

Python (agente → SMS com retry)

import anthropic, requests, time

def send_sms(to, message, retries=3):
    for attempt in range(retries):
        r = requests.post(
            "https://api.mailpro.com/sms/send/add_single.json",
            data={
                "id_client": MAILPRO_ID, "api_key": MAILPRO_KEY,
                "to": to, "message": message
            }
        )
        if r.status_code == 429:
            time.sleep(2 ** attempt)  # backoff exponencial
            continue
        return r.json()
    raise Exception("Falha no envio SMS após retentativas")

Node.js (webhook Express → Claude → SMS)

import express from "express";
import Anthropic from "@anthropic-ai/sdk";

const app = express();
const ai = new Anthropic();

app.post("/alert", async (req, res) => {
  const { severity, message } = req.body;
  const resp = await ai.messages.create({
    model: "claude-sonnet-4-5",
    max_tokens: 256,
    tools: [/* esquema send_sms */],
    messages: [{ role: "user", content: `Alerta ${severity}: ${message}. Notifique plantão.` }]
  });
  for (const b of resp.content) {
    if (b.type === "tool_use") {
      await fetch(`https://api.mailpro.com/sms/send/add_single.json`, {
        method: "POST",
        body: new URLSearchParams({
          id_client: ID, api_key: KEY,
          to: b.input.to, message: b.input.message
        })
      });
    }
  }
  res.sendStatus(200);
});

cURL

curl -X POST "https://api.mailpro.com/sms/send/add_single.json" \
  -d "id_client=YOUR_ID&api_key=YOUR_API_KEY" \
  -d "to=+5511987654321" \
  -d "message=Seu backup Mailpro foi concluído com sucesso às 03:04 UTC."

Para a mesma chamada em uma vintena de outras linguagens (PHP, Go, Ruby, C#, Java, Swift…), veja a referência SMS — cada endpoint traz o snippet equivalente.

Em breve: Verify/OTP e Phone Lookup

Duas features na roadmap da API SMS são especialmente úteis para integrações de agentes de IA:

Endpoint Verify / OTP

Em vez de construir seu próprio fluxo OTP (gerar código, guardar, enviar, verificar), os próximos endpoints /verify/start e /verify/check fazem tudo: geração de código, hash, rate limits, templates multilíngues, contagem de tentativas. O agente só chama /verify/start e depois /verify/check.

HLR Phone Lookup

O próximo endpoint /phone/lookup retornará em tempo real info da operadora (mobile / fixo / voip), detecção de portabilidade (MNP) e alcançabilidade. Essencial para limpar listas de leads antes de uma campanha SMS — não faz sentido disparar para número desativado.

Ambas usarão o mesmo modelo de auth, ficando imediatamente consumíveis por um agente de IA.

Dicas e armadilhas

Respostas em PascalCase (como v2 e-mail)

A API SMS Mailpro™ retorna Result, IdSend, RemainingCredits — PascalCase. Bate com v2 e-mail, diferente de v3 CRM (snake_case). Informe no prompt do sistema.

Tratamento de STOP e supressão de números

Usuários podem responder STOP para se descadastrar. Hoje nosso gateway cuida disso e bloqueia envios futuros automaticamente. O próximo endpoint /suppressions vai expor a lista de supressão como recurso de API — para auditoria e gestão manual.

LGPD/GDPR e consentimento

Sempre tenha consentimento explícito antes de enviar SMS de marketing. Para SMS transacional (OTP, alertas disparados por ação do usuário), o consentimento é implícito. O agente ne Exception("Falha no envio SMS após retentativas")

Node.js (webhook Express → Claude → SMS)

import express from "express";
import Anthropic from "@anthropic-ai/sdk";

const app = express();
const ai = new Anthropic();

app.post("/alert", async (req, res) => {
  const { severity, message } = req.body;
  const resp = await ai.messages.create({
    model: "claude-sonnet-4-5",
    max_tokens: 256,
    tools: [/* esquema send_sms */],
    messages: [{ role: "user", content: `Alerta ${severity}: ${message}. Notifique plantão.` }]
  });
  for (const b of resp.content) {
    if (b.type === "tool_use") {
      await fetch(`https://api.mailpro.com/sms/send/add_single.json`, {
        method: "POST",
        body: new URLSearchParams({
          id_client: ID, api_key: KEY,
          to: b.input.to, message: b.input.message
        })
      });
    }
  }
  res.sendStatus(200);
});

cURL

curl -X POST "https://api.mailpro.com/sms/send/add_single.json" \
  -d "id_client=YOUR_ID&api_key=YOUR_API_KEY" \
  -d "to=+5511987654321" \
  -d "message=Seu backup Mailpro foi concluído com sucesso às 03:04 UTC."

Para a mesma chamada em uma vintena de outras linguagens (PHP, Go, Ruby, C#, Java, Swift…), veja a referência SMS — cada endpoint traz o snippet equivalente.

Em breve: Verify/OTP e Phone Lookup

Duas features na roadmap da API SMS são especialmente úteis para integrações de agentes de IA:

Endpoint Verify / OTP

Em vez de construir seu próprio fluxo OTP (gerar código, guardar,r via /send/add_single.json. Em breve um endpoint dedicado /verify/start + /verify/check faz tudo em uma chamada. Veja a roadmap da API SMS.

Quanto custa um SMS?

Varia conforme o país de destino. Veja preços para a tabela atual.

A API suporta números internacionais?

Sim, a Mailpro™ envia para 200+ países. Use o formato E.164 (+<código do país><número>, ex. +5511987654321) ou o prefixo 00 equivalente — a API aceita os dois.

Como bloqueio um número que respondeu STOP?

Hoje é automático no gateway. O próximo endpoint /suppressions vai permitir listar, adicionar e remover números suprimidos via API — útil para sincronizar com seu banco de preferências.