API v3 quickstart: de cero a tu primer envío

Si querés operar arrobaMail desde tu propio sistema —dar de alta contactos, enviar campañas, leer estadísticas— el camino es la API REST v3: JSON sobre HTTP, autenticación con JWT, y nada de SDK obligatorio. Esta guía es el atajo: en tres requests pasás de cero a tu primer envío.

1. El plan: tres requests

Toda la integración base se reduce a tres llamadas HTTP: te autenticás (y guardás un token), das de alta un contacto en una lista, y enviás. Con eso ya estás operando. Después podrás sumar consultas de estadísticas, segmentaciones y más —pero el núcleo es esto—.

La URL base de la API es https://envios.arrobamail.com/v3/api/ (reemplazá envios por el servidor asignado a tu cuenta).

2. Autenticarte: el token JWT

Todo arranca pidiendo un token. Es un pase temporal que autoriza tus llamadas:

POST /auth/getToken
Content-Type: application/json

{ "username": "tu_usuario", "pass": "tu_contraseña", "rememberMe": true, "locale": "es" }

Recibís un token. A partir de acá, toda llamada protegida lo lleva en el header:

Authorization: Bearer {token}

Clave: el campo es pass, no password. Y con rememberMe: true el token dura hasta 365 días (cómodo para producción); en false, es corto (ideal para pruebas).

3. Tené listos el remitente y la lista

Antes de enviar, dos cosas tienen que existir en tu cuenta:

• Un remitente verificado. Para enviar, el from debe estar certificado con SPF/DKIM. Si no lo está, la API rechaza el envío. (Lo verificás una vez; está en verificá tu remitente.)
• Una lista. Con GET /lists obtenés tus listas y sus IDs. Anotá el de la lista destino —es un string cifrado, no un número—.

4. Dar de alta un contacto

Sumás (o confirmás) al suscriptor que va a recibir, en esa lista:

POST /lists/:id/subscribers
Authorization: Bearer {token}

{ "email": "cliente@dominio.com", "name": "Cliente" }

Clave: el contacto tiene que quedar en estado Activo. Si tu lista usa double opt-in y queda Pendiente, no va a recibir envíos ni a disparar automatizaciones.

5. Enviar

La llamada que encola el envío. Con el nombre, el asunto, el HTML, el remitente y la lista:

POST /campaigns
Authorization: Bearer {token}

{ "campname": "Mi_primera", "asunto": "Hola desde la API",
  "html": "<h1>Funciona</h1>", "fromname": "Tu Empresa",
  "frommail": "info@tudominio.com", "listid": ["TU_LIST_ID"],
  "tracklinks": 1, "trackreads": 1 }

Recibís un encid (el identificador de la campaña). Guardalo para consultar después.

6. Verificar y seguir en tu lenguaje

Con el encid consultás cómo fue:

GET /campaigns/{encid}/stats/subscriber-actions
Authorization: Bearer {token}

Te dice si se entregó, si abrieron y si hubo clics. Y listo: ya integraste arrobaMail con tu sistema.

Esta guía usó pseudo-HTTP para que se entienda el flujo. El código real, listo para copiar en curl, Node, PHP o Python, está en el quickstart de la API (con pestañas por lenguaje), y el detalle de cada endpoint —todos sus parámetros y respuestas— en la referencia.

Errores frecuentes a evitar

• Mandar password en vez de pass. El campo de la contraseña es pass. Es el tropiezo número uno.
• Remitente sin verificar. Si el frommail no está certificado, el envío se rechaza. Verificalo antes.
• Tratar el listid como número. Es un string cifrado. Pasalo tal cual lo da GET /lists.
• Olvidar el espacio en el header. Tiene que decir exactamente Authorization: Bearer {token}, con el espacio después de Bearer.

Próximos pasos

1. Agarrá el código en tu lenguaje en el quickstart de la API.
2. Profundizá cada endpoint en la referencia.
3. Para enviar correos individuales por evento, mirá enviar emails transaccionales.