Validate Email (v2)

Submit an email to the agentic validator — async or sync

POST /api/v2/emails/validate

Validate Email (v2)

cURL

curl --request POST \
  --url https://api.example.com/api/v2/emails/validate \
  --header 'Content-Type: application/json' \
  --data '
{
  "email_text": "<string>",
  "mode": "<string>",
  "metadata": {
    "audience_hint": "<string>",
    "jurisdiction": "<string>"
  },
  "document_category": "<string>",
  "llm_provider": "<string>",
  "llm_model": "<string>"
}
'

import requests

url = "https://api.example.com/api/v2/emails/validate"

payload = {
    "email_text": "<string>",
    "mode": "<string>",
    "metadata": {
        "audience_hint": "<string>",
        "jurisdiction": "<string>"
    },
    "document_category": "<string>",
    "llm_provider": "<string>",
    "llm_model": "<string>"
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    email_text: '<string>',
    mode: '<string>',
    metadata: {audience_hint: '<string>', jurisdiction: '<string>'},
    document_category: '<string>',
    llm_provider: '<string>',
    llm_model: '<string>'
  })
};

fetch('https://api.example.com/api/v2/emails/validate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/api/v2/emails/validate",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'email_text' => '<string>',
    'mode' => '<string>',
    'metadata' => [
        'audience_hint' => '<string>',
        'jurisdiction' => '<string>'
    ],
    'document_category' => '<string>',
    'llm_provider' => '<string>',
    'llm_model' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/api/v2/emails/validate"

	payload := strings.NewReader("{\n  \"email_text\": \"<string>\",\n  \"mode\": \"<string>\",\n  \"metadata\": {\n    \"audience_hint\": \"<string>\",\n    \"jurisdiction\": \"<string>\"\n  },\n  \"document_category\": \"<string>\",\n  \"llm_provider\": \"<string>\",\n  \"llm_model\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/api/v2/emails/validate")
  .header("Content-Type", "application/json")
  .body("{\n  \"email_text\": \"<string>\",\n  \"mode\": \"<string>\",\n  \"metadata\": {\n    \"audience_hint\": \"<string>\",\n    \"jurisdiction\": \"<string>\"\n  },\n  \"document_category\": \"<string>\",\n  \"llm_provider\": \"<string>\",\n  \"llm_model\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/v2/emails/validate")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"email_text\": \"<string>\",\n  \"mode\": \"<string>\",\n  \"metadata\": {\n    \"audience_hint\": \"<string>\",\n    \"jurisdiction\": \"<string>\"\n  },\n  \"document_category\": \"<string>\",\n  \"llm_provider\": \"<string>\",\n  \"llm_model\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

202 Accepted (async)

{
  "api_version": "v2",
  "job_id": "a1b2c3d4e5f6",
  "status": "queued",
  "mode": "async",
  "submitted_at": "2026-06-25T12:00:00.123456+00:00",
  "poll": { "method": "GET", "url": "/api/v2/jobs/a1b2c3d4e5f6" },
  "usage": { "monthly_count": 42, "annual_count": 1234 }
}

{
  "api_version": "v2",
  "error": { "code": "missing_email", "message": "email_text is required" }
}

Submit email content to the agentic email validator. By default the request is processed asynchronously: the endpoint returns a job_id you poll via Get Validation Results (v2). Set mode: "sync" to run the validation inline and receive the completed result in a single response.

Request Body

email_text · string

The email content to validate. This is the canonical field; text_snippet (string) and email_bytes (base64-encoded UTF-8) are accepted as aliases. One of email_text, text_snippet, or email_bytes is required.

mode · string · default: "async"

Execution mode: async (default) returns 202 with a job_id to poll; sync runs the agentic graph inline and returns the completed result with 200. Sync requests above the size cap (default 20,000 characters) or that fail inline automatically fall back to async.

metadata · object

Optional metadata merged into the job. document_type is always forced to email so the request routes to the agentic engine.

Show common metadata fields

audience_hint · string

Intended audience, e.g. retail_US, professional_US.

jurisdiction · string

Regulatory jurisdiction, e.g. US.

document_category · string

Explicit scenario id to validate against, e.g. scenario_email_general. When omitted, the validator matches scenarios by metadata: every email matches an audience-agnostic baseline carrying core signals — material non-public information (MNPI), market manipulation, high-pressure sales, and client-data privacy — and audience_hint: retail_US additionally applies retail-disclosure signals. Your account’s active custom rules (from policy imports) are evaluated as well. If no scenario/signals match at all, the job fails rather than returning a false approved.

llm_provider · string

Provider hint (openai, anthropic, gemini). Honored only if the customer is configured to allow provider override; otherwise the customer’s assigned provider is used.

llm_model · string

Model hint, e.g. claude-sonnet-4-6. Subject to the same override rule as llm_provider.

Response

api_version · string

Always v2.

job_id · string

Unique identifier for the validation job.

status · string

queued for async submissions. For sync responses the full status vocabulary applies (completed / failed).

mode · string

Mode the request was actually processed in: async or sync. A sync request that fell back returns async.

submitted_at · string

ISO 8601 UTC timestamp when the job was created, e.g. 2026-06-25T12:00:00.123456+00:00.

poll · object

Where to poll for the result (async only).

Show poll properties

method · string

Always GET.

url · string

Poll URL, e.g. /api/v2/jobs/{job_id}.

usage · object

Billing usage counters (when usage tracking succeeds).

Show usage properties

monthly_count · integer

Validations this month.

annual_count · integer

Validations this year.

For the sync response body (HTTP 200), the envelope is identical to a completed poll — see Get Validation Results (v2) — with "mode": "sync" added.

Error Responses

Status	Code	Description
400	missing_email	No email content provided (one of email_text, text_snippet, or email_bytes)
400	invalid_email_bytes	email_bytes is not valid base64 UTF-8
400	invalid_mode	mode must be async or sync
500	internal_error	Unexpected server error

202 Accepted (async)

{
  "api_version": "v2",
  "job_id": "a1b2c3d4e5f6",
  "status": "queued",
  "mode": "async",
  "submitted_at": "2026-06-25T12:00:00.123456+00:00",
  "poll": { "method": "GET", "url": "/api/v2/jobs/a1b2c3d4e5f6" },
  "usage": { "monthly_count": 42, "annual_count": 1234 }
}

{
  "api_version": "v2",
  "error": { "code": "missing_email", "message": "email_text is required" }
}

Example

cURL

curl -X POST "https://{api-url}/api/v2/emails/validate" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email_text": "Hey, the quarterly board meeting just wrapped. We missed our revenue targets by $15 million. Sell before the official press release drops on Tuesday.",
    "mode": "async",
    "metadata": { "audience_hint": "retail_US", "jurisdiction": "US" }
  }'

import requests

API_KEY = "YOUR_API_KEY"
API_BASE = "https://{api-url}"

response = requests.post(
    f"{API_BASE}/api/v2/emails/validate",
    headers={
        "x-api-key": API_KEY,
        "Content-Type": "application/json"
    },
    json={
        "email_text": "Hey, the quarterly board meeting just wrapped. We missed our revenue targets by $15 million. Sell before the official press release drops on Tuesday.",
        "mode": "async",
        "metadata": {"audience_hint": "retail_US", "jurisdiction": "US"}
    }
)

print(response.json())  # -> {"job_id": "...", "status": "queued", ...}

const axios = require('axios');

const API_KEY = 'YOUR_API_KEY';
const API_BASE = 'https://{api-url}';

const response = await axios.post(
  `${API_BASE}/api/v2/emails/validate`,
  {
    email_text: 'Hey, the quarterly board meeting just wrapped. We missed our revenue targets by $15 million. Sell before the official press release drops on Tuesday.',
    mode: 'async',
    metadata: { audience_hint: 'retail_US', jurisdiction: 'US' }
  },
  {
    headers: {
      'x-api-key': API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

console.log(response.data);