AllyOneMail / Autenticación

Autenticación

Las integraciones se autentican con una API key por cliente, con alcances. El panel usa sesión de usuario (JWT), que la API también acepta.

API key

X-API-Key: zm_live_...

Crea la clave en el panel de AllyOneMail (o con POST /api/v1/auth/api-keys, usando una clave admin). El valor completo solo aparece al crearla; AllyOneMail guarda solo su hash (SHA-256). Si la pierdes, genera otra y revoca la anterior. El prefijo zm_live_ viene del nombre anterior de la plataforma.

Alcances

Alcance	Permite
`send`	Envío por `/api/v1/send`.
`read`	Lectura: dominios, eventos, supresiones, webhooks, facturación, calentamiento.
`domains`	Registrar y modificar dominios.
`suppress`	Solo agregar supresiones (`POST /api/v1/suppressions`) — se usa para sincronizar bajas.
`privacy`	Derechos del titular: `/api/v1/privacy/export` y `/erasure`.
`admin`	Todo, incluidos webhooks, usuarios y claves. Úsalo solo donde haga falta.

Una llamada fuera del alcance de la clave responde 403 insufficient_scope.

Probar la clave

GET/api/v1/auth/me

curl https://smtp.allyone.com.br/api/v1/auth/me \
  -H "X-API-Key: zm_live_..."

{ "authType": "api_key", "clientId": "c1f0...", "agencyId": "a7d2...", "role": "api_key", "scopes": ["send", "read"] }

Para saber si la API está disponible sin autenticar: GET /api/status.

Rate limit

Por clave: el límite por minuto configurado en la clave (por defecto: 1.000). Al superarlo, 429 api_rate_limit_exceeded; el contador se reinicia al minuto siguiente.
Por IP: 500.000 solicitudes por hora, con headers X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset.

Detalles y formato de los errores en Errores y límites.

Referencia completa

La especificación OpenAPI de todas las rutas de integración está publicada en smtp.allyone.com.br/docs (JSON en /docs/json) — impórtala en Postman o Insomnia, o genera un cliente.