Batch, rates and errors.

Batch ingest (≤100)

One JSON request with up to 100 messages. Each item has its own idempotency_key. The response lists per-index results and created / failed / replayed counters.

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 .

Deliverability rates

Tenant aggregates over a day window (query days, default 14): ingested, sent, deferred, bounced, complained, sealed, rates and daily series. Same shape in the portal Rates screen.

These are operational tenant metrics, not a public deliverability claim for the product.

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

API key scopes

The Bearer key resolves the tenant. Common scopes:

Envelope, codes and HTTP status

Uniform shape: {"error":{"code":"snake_case","message":"…"}}. The message is human-readable and usually tells you the fix (e.g. "add and verify it in the portal"). Each code always maps to the same HTTP status:

The complete, normative list of codes lives in the repository's OpenAPI contract (docs/openapi.yaml, Error schema). This table covers the errors you will hit while integrating sending.

Machine, portal and admin

Machine API (/v1/* with API key) is for SDKs and MCP. Portal (/v1/portal/*) uses the customer user session. Admin (/v1/admin/*) is the JAAK operator console.

Certified vs plain

Every message carries a certified flag. JSON sends accept the per-message override "certified": false; when omitted, the account default (default_certified) applies. Raw message/rfc822 bodies take no override: they always use the account default. A plain message is delivered the same way, but it never enters the Merkle tree: sealing it answers 422 not_certified and its proof-bundle 422 missing_proof_data. There is no silent upgrade to certified.

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}'

Online evidence and verification

Besides the downloadable proof-bundle —which anyone can check at mailack.com/verificar, in their browser with nothing uploaded—, the API exposes evidence online: /evidence returns the sealed message summary (canonical hash, batch_id, Merkle root, certificate_id, sealed_at) and /v1/verify recomputes the Merkle inclusion proof by message_id and answers valid: true|false. Every verification consult is recorded in the 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": "…"}