> ## Documentation Index
> Fetch the complete documentation index at: https://zerodrift.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Validation v2 (Agentic Email)

> The agentic email-validation API — richer findings, async or sync

The **v2** validation API exposes ZeroDrift's agentic email validator. It runs an
LLM-driven graph that profiles the email, plans which compliance signals to
evaluate, runs them in parallel, adversarially verifies each finding, and
synthesizes a final assessment.

v2 lives under `/api/v2/` and is **additive** — all v1 routes are unchanged. Use
v2 when you want the richer, signal-based output (`violations` with reasoning and
verifier notes, plus an `email_profile`); use v1 if you depend on the existing
`fixes` / `fixes_group` shape.

## Endpoints

| Method | Path                      | Purpose                                        |
| ------ | ------------------------- | ---------------------------------------------- |
| `POST` | `/api/v2/emails/validate` | Submit an email for validation (async or sync) |
| `GET`  | `/api/v2/jobs/{job_id}`   | Poll job status / fetch the result             |

Both require the same `x-api-key` authentication as v1.

## Async vs. sync

<ParamField body="mode" type="string" default="async">
  `async` (default) creates a job and returns `202` immediately with a `job_id`
  and poll URL — identical lifecycle to v1, just a cleaner envelope. `sync` runs
  the agentic graph inline and returns the completed result in a single `200`
  response.
</ParamField>

Sync mode is intended for short emails. If the email exceeds the sync size cap
(default 20,000 characters) or inline execution fails, the API **automatically
falls back to async** and returns the `202` envelope — a submission is never
lost.

## How v2 differs from v1

* **Signal-based `violations`** — each finding carries `signal_id`, `severity`,
  `confidence`, the offending `quote` with character offsets, model `reasoning`,
  a `verifier_note` from the adversarial check, and a suggested `fix`.
* **`email_profile`** — the agent's structured read of the email (intent, tone,
  claims, audience signals, disclosures present) is surfaced alongside violations.
* **Stable status vocabulary** — `queued`, `processing`, `completed`, `failed`
  (v1's internal `started` / `in_progress` / `done` are not leaked).
* **Versioned envelope** — every response carries `"api_version": "v2"`.

## Typical flow

<Steps>
  <Step title="Submit">
    `POST /api/v2/emails/validate` with `email_text`. Returns `202` + `job_id`
    (async) or `200` + full result (sync).
  </Step>

  <Step title="Poll">
    For async, `GET /api/v2/jobs/{job_id}` until `status` is `completed` or
    `failed`.
  </Step>

  <Step title="Act">
    Read `result.overall_status` and `result.violations` to surface findings.
  </Step>
</Steps>