# EmailIQ — Full LLM / Agent Reference

> Instant Email Intelligence API for AI Agents using x402 micropayments.
> **Generated from app config** — do not hand-edit prices; run `scripts/render_discovery.py`.

## Quick facts

| Field | Value |
| --- | --- |
| Endpoint (single) | `POST /email/intelligence` (operationId `analyzeEmail`) |
| Endpoint (batch) | `POST /email/intelligence/batch` (operationId `analyzeEmailBatch`) — 2–25 emails |
| Price (single) | 0.10 USDC per successful paid call (atomic `100000`) |
| Price (batch) | 0.50 USDC flat per successful batch (atomic `500000`; max 25) |
| Network | `eip155:8453` · asset `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` |
| Auth | x402 `PAYMENT-SIGNATURE` — no API keys (or prepaid / gateway) |
| MCP | `https://emailiq.dev/mcp` · tools `analyze_email`, `analyze_email_batch` |
| Cache | Payer-scoped HMAC email hash · TTL 86400s · header `X-EmailIQ-Cache` |
| Idempotency | Optional `Idempotency-Key` (same key + different body → 422) |

**operationId stability:** `analyzeEmail`, `analyzeEmailBatch`, `demoEmail`, `getHealth` are published — never rename.

## Response contract (recommend first)

Serialized JSON field order for a successful single analysis:

1. `recommend` — `accept` | `challenge` | `reject`
2. `reasons` — closed enum codes (never free-text)
3. `score` — 0–100
4. `bounce_risk` — `low` | `medium` | `high` (high if score < 40 / disposable / no MX / invalid; medium if score < 70 or role/weak auth; else low)
5. existing intelligence fields (`email`, `valid_syntax`, …)
6. `enrichment` — object or **null** when unknown (never fabricated)
7. `processing_time_ms`

### Reason codes

| code | meaning |
| --- | --- |
| `auth_records_ok` | SPF, DKIM selector, and DMARC all present. |
| `auth_triad_ok` | Legacy alias of auth_records_ok. |
| `bounce_risk_high` | Derived bounce_risk is high. |
| `bounce_risk_low` | Derived bounce_risk is low. |
| `bounce_risk_medium` | Derived bounce_risk is medium. |
| `corporate_domain` | Non-consumer domain with business-like enrichment signals. |
| `disposable_domain` | Domain is a known disposable/temp mailbox provider. |
| `disposable_mailbox` | Legacy alias of disposable_domain. |
| `dkim_missing` | No common-selector DKIM TXT found. |
| `dmarc_missing` | No DMARC policy found (same signal as no_dmarc). |
| `domain_missing` | Legacy alias of domain_not_found. |
| `domain_not_found` | Domain does not resolve in DNS. |
| `free_provider` | Consumer/free mailbox provider (gmail, outlook, …). |
| `invalid_syntax` | Local-part/domain failed RFC-oriented syntax rules. |
| `mx_present` | At least one MX host is present. |
| `no_dmarc` | No DMARC policy (v=DMARC1) at _dmarc. |
| `no_mx` | Domain resolves but has an empty MX set. |
| `role_account` | Local-part looks like a role account (admin, support, info, …). |
| `score_high` | Composite score ≥ 75. |
| `score_low` | Composite score < 40. |
| `score_medium` | Composite score 40–74. |
| `spf_missing` | No TXT SPF (v=spf1) found. |
| `weak_spf` | SPF record missing or not usable (v=spf1 not found). |

### Batch response

```json
{
  "results": [{ "index": 0, "email": "...", "recommend": "accept", "..." : "..." }],
  "summary": { "accept": 1, "challenge": 0, "reject": 0, "errors": 0 },
  "count": 2,
  "processing_time_ms": 98.2
}
```

Duplicates are computed once and returned per input index. Soft per-item failures use `error_code` (not HTTP 500 for the whole batch). Settle once per batch.

## Payment (x402)

Without `PAYMENT-SIGNATURE` (and without prepaid/gateway), paid routes return **HTTP 402** with:

- Header `PAYMENT-REQUIRED` — spec-encoded V2 envelope (do not hand-modify)
- JSON body includes `next`: `retry the same request with a signed x402 PAYMENT-SIGNATURE header`
- `amount_atomic` / `price`, `max_batch`, `endpoints`, `free_trial` → `/demo/email`, `docs`

| Route | USDC | atomic |
| --- | --- | --- |
| `POST /email/intelligence` | 0.10 | `100000` |
| `POST /email/intelligence/batch` | 0.50 | `500000` |
| `POST /credits/purchase` | 5.00 | `5000000` |

Batch size outside 2–25 → **422 before payment verification**.

## Cache / don't pay twice

- Domain DNS/enrich TTL cache (shared, no billing effect)
- Payer-scoped result cache keyed by `(payer_address, HMAC(email))` — on hit after verify, **skip settlement**, `X-EmailIQ-Cache: hit-no-charge`
- In-process by default; optional `REDIS_URL`. Multi-machine Fly → prefer Redis or single machine.

## Gateway mode

Marketplaces (xpay, FluxA, FiatDock) inject `X-EmailIQ-Gateway-Secret`. Valid secret → skip x402 (platform already charged). See `integrations/`.

## Discovery

- `https://emailiq.dev/llms.txt` · `https://emailiq.dev/llms-full.txt`
- `https://emailiq.dev/.well-known/agents.json` (proposal format)
- `https://emailiq.dev/openapi.json` · `https://emailiq.dev/robots.txt` · `https://emailiq.dev/sitemap.xml`