Clientes HTTP: conectar seu sistema à API a partir de qualquer linguagem

A API do arrobaMail é REST sobre HTTPS com JSON: não há SDK obrigatório nem protocolo proprietário. Se sua linguagem consegue fazer um request HTTP, consegue falar com a API. Esta página é a referência de como se conectar —URL base, autenticação, headers, erros e limites—; se o que você quer é fazer sua primeira chamada em três passos, comece pelo quickstart.

Nunca coloque sua API Key nem seu token no front-end nem em um repositório público. Guarde-os como variáveis de ambiente do lado do servidor. Nos exemplos, usamos os marcadores TU_USUARIO, TU_PASSWORD e TU_TOKEN.

URL base

Todas as rotas partem da base, sobre o seu servidor de envio:

https://{servidor}.arrobamail.com/v3/api/

O {servidor} é o host que atribuímos a você (a API é multisservidor). Você vê isso no seu painel; use sempre o seu, não um genérico. Todos os endpoints da referência são relativos a essa base —por exemplo GET /v3/api/campaigns.

Autenticação: token JWT

A autenticação é por JWT. O fluxo tem dois passos:

1. Você pede um token com suas credenciais em POST /auth/getToken.
2. Você envia esse token no header Authorization: Bearer <token> em cada request seguinte.

# 1) Obtener el token
curl -X POST "https://{servidor}.arrobamail.com/v3/api/auth/getToken" \
  -H "Content-Type: application/json" \
  -d '{"username":"TU_USUARIO","password":"TU_PASSWORD"}'
# → { "token": "eyJhbGciOi..." }

O token tem uma validade: quando expira, você pede outro. Não o deixe fixo no código —guarde-o em memória e renove quando uma resposta te devolver 401.

Headers que você vai usar

Header	Valor	Quando
Authorization	Bearer TU_TOKEN	Em todos os requests autenticados
Content-Type	application/json	Quando você envia corpo (POST/PUT/PATCH)
Accept	application/json	Recomendado sempre

Exemplos por cliente

Mesma operação —listar campanhas— a partir de quatro clientes. Muda a sintaxe, não a lógica: token no header e JSON de ida e volta.

# curl
curl "https://{servidor}.arrobamail.com/v3/api/campaigns" \
  -H "Authorization: Bearer TU_TOKEN" \
  -H "Accept: application/json"

// Node.js (fetch nativo, v18+)
const res = await fetch('https://{servidor}.arrobamail.com/v3/api/campaigns', {
  headers: {
    Authorization: `Bearer ${process.env.ARROBAMAIL_TOKEN}`,
    Accept: 'application/json',
  },
})
if (!res.ok) throw new Error(`HTTP ${res.status}`)
const data = await res.json()

// PHP (cURL)
$ch = curl_init('https://{servidor}.arrobamail.com/v3/api/campaigns');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('ARROBAMAIL_TOKEN'),
    'Accept: application/json',
  ],
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

# Python (requests)
import os, requests

resp = requests.get(
    "https://{servidor}.arrobamail.com/v3/api/campaigns",
    headers={
        "Authorization": f"Bearer {os.environ['ARROBAMAIL_TOKEN']}",
        "Accept": "application/json",
    },
    timeout=15,
)
resp.raise_for_status()
data = resp.json()

Para uma operação de escrita (criar algo), o padrão é o mesmo mais Content-Type: application/json e o corpo em JSON. O detalhe de cada endpoint —método, parâmetros e formato do corpo— está na referência.

Tratamento de erros

A API usa os códigos de status HTTP padrão. Programe seu cliente para distingui-los:

Código	Significa	O que fazer
200 / 201	OK / criado	Seguir
400	Pedido mal formado	Revisar o corpo e os parâmetros
401	Token ausente ou expirado	Pedir um token novo e tentar de novo
403	Sem permissão para essa operação	Revisar o alcance da sua conta
404	Recurso inexistente	Revisar o ID / a rota
429	Requests demais	Esperar e tentar de novo com backoff
5xx	Erro do servidor	Tentar de novo com backoff; se persistir, avise a gente

Trate sempre o corpo da resposta de erro como JSON: costuma trazer uma mensagem que explica o que falhou. Não presuma que um 2xx vazio é um erro.

Limites de taxa e boas práticas

• Respeite os limites. Diante de um 429, não martele o endpoint: espere e tente de novo com backoff exponencial (1s, 2s, 4s…).
• Reutilize o token enquanto estiver válido; não peça um novo a cada request.
• Pagine as listagens longas em vez de trazer tudo de uma vez.
• Timeouts e retentativas no seu cliente para erros de rede e 5xx.
• Idempotência: ao criar recursos, guarde o ID que a API devolve para não duplicar se você tentar de novo.

Testar sem escrever código: Postman / Insomnia

Para explorar a API antes de programar, qualquer cliente gráfico serve:

1. Crie um environment com duas variáveis: base (https://{servidor}.arrobamail.com/v3/api) e token.
2. Faça o POST {{base}}/auth/getToken com suas credenciais e guarde o token na variável.
3. No restante dos requests, configure o header Authorization: Bearer {{token}} no nível da coleção.

Assim você testa endpoints, vê as respostas reais e depois transporta o que funcionou para o seu código.

Próximos passos

• Sua primeira chamada, passo a passo? O quickstart da API.
• O catálogo de endpoints? A referência.
• Reagir a eventos (aberturas, compras) em vez de consultar? Veja webhooks.
• Operar com um assistente de IA sem escrever código? A integração por MCP.