Batch, rates y errores.

Ingesta batch (≤100)

Un solo request JSON con hasta 100 mensajes. Cada ítem lleva su propio idempotency_key. La respuesta lista resultados por índice y contadores created / failed / replayed.

curl -s -X POST "$MAILACK_API_URL/v1/messages/batch" \
  -H "Authorization: Bearer $MAILACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "idempotency_key": "order-1",
        "from": "noreply@acme.mx",
        "to": "a@ejemplo.com",
        "subject": "Pedido 1",
        "text": "Gracias"
      },
      {
        "idempotency_key": "order-2",
        "from": "noreply@acme.mx",
        "to": "b@ejemplo.com",
        "subject": "Pedido 2",
        "text": "Gracias"
      }
    ]
  }' | jq .

Rates de entregabilidad

Agregados del tenant en una ventana de días (query days, default 14): ingested, sent, deferred, bounced, complained, sealed, tasas y serie diaria. Misma forma en el portal (pantalla Rates).

Son métricas operativas del tenant, no un claim de entregabilidad pública del producto.

curl -s "$MAILACK_API_URL/v1/rates?days=14" \
  -H "Authorization: Bearer $MAILACK_API_KEY" | jq .

Scopes de API key

La key Bearer resuelve el tenant. Scopes habituales:

Envelope, códigos y HTTP status

Formato uniforme: {"error":{"code":"snake_case","message":"…"}}. El message es legible y suele indicar la corrección (p. ej. "add and verify it in the portal"). Cada código va siempre con el mismo HTTP status:

El listado completo y normativo de códigos vive en el contrato OpenAPI del repositorio (docs/openapi.yaml, schema Error). Esta tabla cubre los errores que verás al integrar el envío.

Machine, portal y admin

Machine API (/v1/* con API key) es la de SDKs y MCP. Portal (/v1/portal/*) usa sesión del usuario del cliente. Admin (/v1/admin/*) es la consola de operadores JAAK.

Certificado vs plain

Cada mensaje lleva una bandera certified. El envío JSON acepta el override por mensaje "certified": false; si lo omites, aplica el default de la cuenta (default_certified). Los cuerpos message/rfc822 no admiten override: siempre usan el default. Un mensaje plain entrega igual, pero no entra al árbol Merkle: sellarlo responde 422 not_certified y su proof-bundle 422 missing_proof_data. No hay upgrade silencioso a certificado.

curl -s -X POST "$MAILACK_API_URL/v1/messages" \
  -H "Authorization: Bearer $MAILACK_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "noreply@acme.mx",
    "to": "cliente@ejemplo.com",
    "subject": "Aviso operativo",
    "html": "<p>Mensaje transaccional sin certificación.</p>",
    "certified": false
  }' | jq '{id, certified}'

Evidencia y verificación online

Además del proof-bundle descargable —que cualquiera puede comprobar en mailack.com/verificar, en su navegador y sin subir nada—, la API expone la evidencia en línea: /evidence devuelve el resumen del mensaje sellado (hash canónico, batch_id, raíz Merkle, certificate_id, sealed_at) y /v1/verify recomputa la prueba de inclusión Merkle por message_id y responde valid: true|false. Cada consulta de verificación queda en el access log.

# Resumen de evidencia del mensaje (hash, batch, raíz Merkle, constancia)
curl -s "$MAILACK_API_URL/v1/messages/$MESSAGE_ID/evidence" \
  -H "Authorization: Bearer $MAILACK_API_KEY" | jq .

# Verificación online de la prueba de inclusión Merkle
curl -s -X POST "$MAILACK_API_URL/v1/verify" \
  -H "Authorization: Bearer $MAILACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"message_id\": \"$MESSAGE_ID\"}" | jq .
# → {"valid": true, "merkle_root": "…", "certificate_id": "…", "sealed_at": "…"}