Clientes HTTP: conectar tu sistema a la API desde cualquier lenguaje

La API de arrobaMail es REST sobre HTTPS con JSON: no hay SDK obligatorio ni protocolo propietario. Si tu lenguaje puede hacer un request HTTP, puede hablar con la API. Esta página es la referencia de cómo conectarse —URL base, autenticación, headers, errores y límites—; si lo que querés es hacer tu primera llamada en tres pasos, empezá por el quickstart.

Nunca pongas tu API Key ni tu token en el front-end ni en un repositorio público. Guardalos como variables de entorno del lado del servidor. En los ejemplos usamos los marcadores TU_USUARIO, TU_PASSWORD y TU_TOKEN.

URL base

Todas las rutas cuelgan de la base, sobre tu servidor de envío:

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

El {servidor} es el host que te asignamos (la API es multi-servidor). Lo ves en tu panel; usá siempre el tuyo, no uno genérico. Todos los endpoints de la referencia son relativos a esa base —por ejemplo GET /v3/api/campaigns.

Autenticación: token JWT

La autenticación es por JWT. El flujo es de dos pasos:

1. Pedís un token con tus credenciales en POST /auth/getToken.
2. Mandás ese token en el header Authorization: Bearer <token> en cada request siguiente.

# 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..." }

El token tiene una vigencia: cuando expira, volvés a pedir otro. No lo hardcodees —guardalo en memoria y renovalo cuando una respuesta te devuelva 401.

Headers que vas a usar

Header	Valor	Cuándo
Authorization	Bearer TU_TOKEN	En todos los requests autenticados
Content-Type	application/json	Cuando enviás cuerpo (POST/PUT/PATCH)
Accept	application/json	Recomendado siempre

Ejemplos por cliente

Misma operación —listar campañas— desde cuatro clientes. Cambian la sintaxis, no la lógica: token en el header y JSON de ida y vuelta.

# 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 una operación de escritura (crear algo), el patrón es el mismo más Content-Type: application/json y el cuerpo en JSON. El detalle de cada endpoint —método, parámetros y forma del cuerpo— está en la referencia.

Manejo de errores

La API usa los códigos de estado HTTP estándar. Programá tu cliente para distinguirlos:

Código	Significa	Qué hacer
200 / 201	OK / creado	Seguir
400	Pedido mal formado	Revisar el cuerpo y los parámetros
401	Token ausente o vencido	Pedir un token nuevo y reintentar
403	Sin permiso para esa operación	Revisar el alcance de tu cuenta
404	Recurso inexistente	Revisar el ID / la ruta
429	Demasiados requests	Esperar y reintentar con backoff
5xx	Error del servidor	Reintentar con backoff; si persiste, avisanos

Tratá siempre el cuerpo de la respuesta de error como JSON: suele traer un mensaje que explica qué falló. No asumas que un 2xx vacío es un error.

Límites de tasa y buenas prácticas

• Respetá los límites. Ante un 429, no martilles el endpoint: esperá y reintentá con backoff exponencial (1s, 2s, 4s…).
• Reusá el token mientras siga vigente; no pidas uno nuevo en cada request.
• Paginá los listados largos en vez de traer todo de una.
• Timeouts y reintentos en tu cliente para errores de red y 5xx.
• Idempotencia: al crear recursos, guardá el ID que te devuelve para no duplicar si reintentás.

Probar sin escribir código: Postman / Insomnia

Para explorar la API antes de programar, cualquier cliente gráfico sirve:

1. Creá un environment con dos variables: base (https://{servidor}.arrobamail.com/v3/api) y token.
2. Hacé el POST {{base}}/auth/getToken con tus credenciales y guardá el token en la variable.
3. En el resto de los requests, seteá el header Authorization: Bearer {{token}} a nivel colección.

Así probás endpoints, ves las respuestas reales y después trasladás lo que funcionó a tu código.

Próximos pasos

• ¿Tu primera llamada, paso a paso? El quickstart de la API.
• ¿El catálogo de endpoints? La referencia.
• ¿Reaccionar a eventos (aperturas, compras) en vez de consultar? Mirá webhooks.
• ¿Operar con un asistente de IA sin escribir código? La integración por MCP.