Letterjudge API

Letterjudge validates email addresses through a multi-step pipeline: format check, MX DNS lookup, live SMTP probe, catch-all detection, disposable domain blocking, and role address flagging. Every check produces a weighted confidence score from 0.0 to 1.0.

All requests are REST + JSON over HTTPS. No SDK required. A single curl command gets you started.

Base URL

https://api.letterjudge.com

Authentication

All requests to /validate and /usage require an API key passed in the X-Api-Key request header. You receive your key when you create an account.

X-Api-Key: lj_live_[.....]

Key format

API keys are formatted as: the prefix lj_live_ followed by encoded characters.

Validate an email address

Runs the full validation pipeline and returns a structured result with a confidence score. Each step only executes if the previous one passed. Bad format exits immediately; SMTP only fires when the domain has MX records.

Query parameters

Request headers

curl "https://api.letterjudge.com/[email protected]" \
  -H "X-Api-Key: lj_live_xKj4mN8pQr3vL7wEsTuBcDa"

curl "https://api.letterjudge.com/[email protected]&smtp=false" \
  -H "X-Api-Key: lj_live_xKj4mN8pQr3vL7wEsTuBcDa"

curl "https://api.letterjudge.com/[email protected]&threshold=0.5" \
  -H "X-Api-Key: lj_live_xKj4mN8pQr3vL7wEsTuBcDa"

Response schema

All responses are JSON. The validation response includes every check result and the computed score.

Score weights

Score is clamped to [0.0, 1.0]. Typical thresholds: ≥0.4 lenient (MX only), ≥0.6 balanced (MX + inconclusive SMTP), ≥0.7 strict (confirmed SMTP).

Get usage and plan info

Returns your current plan, usage counters, and billing period. Available from your dashboard.

Response fields

Get 30-day usage history

Returns a daily breakdown of validation requests for the last 30 calendar days. Each entry covers one UTC day. Days with no activity have a count of 0. Available from your dashboard.

Response

An array of exactly 30 objects, oldest first (day 0 = 30 days ago, day 29 = today).

[
  { "date": "2025-05-24", "count": 35 },
  { "date": "2025-05-25", "count": 42 },
  { "date": "2025-05-26", "count": 0  },
  ...
  { "date": "2025-06-22", "count": 91 }
]

Rendered example

The dashboard shows this data as a bar chart in the Usage History card. Today's bar is brighter; past days are dimmer. Days with no activity are skipped.

API keys

Free and Starter accounts have one active API key at a time (creating a new key revokes the previous one). Pro accounts can hold up to 5 active keys simultaneously; Business accounts have no limit. Keys are hashed before storage. The full key is only shown once (at signup or after a rotation). The dashboard always displays the first 12 characters followed by masked dots.

Rotating your key from the dashboard

The easiest way to rotate your key is from the dashboard. Open the API Key panel, and below the key text box, click Rotate key. Confirm the prompt and your new key appears. Copy it before leaving the page. The old key is revoked the moment you confirm.

List all keys on the account (active and revoked). Requires session cookie.

[
  {
    "id":           "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "key_prefix":   "lj_live_xKj4",
    "created_at":   "2025-01-15T09:00:00+00:00",
    "last_used_at": "2025-06-01T14:32:10+00:00",
    "is_active":    true
  }
]

Issue a new API key. For Free and Starter plans, all existing active keys are revoked immediately (key rotation). For Pro and Business plans, the new key is added alongside existing ones (up to 5 for Pro, unlimited for Business). The full key is returned once — store it before closing the page. This is the endpoint the dashboard Rotate key button calls under the hood.

curl -X POST "https://api.letterjudge.com/keys" \
  --cookie "lj_jwt=<session-cookie>"

{
  "key":    "lj_live_xKj4mN8pQr3vL7wEsTuBcDaFgHiJoYn2zb",
  "prefix": "lj_live_xKj4"
}

Revoke a specific key by ID without issuing a replacement. Use the ID from GET /keys.

{ "revoked": true }

Password reset

To reset your password, go to the sign-in page and click Forgot password. Enter your account email and you will receive a reset link within a few minutes. The link expires after one hour and can only be used once.

After clicking the link, enter your new password (minimum 8 characters). Your existing API key is not affected by a password reset.

Subscription

Plans and billing are managed from your dashboard. The dashboard shows your current plan, quota used this period, days until reset, and next billing date.

Upgrading

Click Upgrade on the dashboard billing panel to move to a higher plan. The new quota applies immediately once payment is confirmed.

Managing your subscription

Click Manage billing on the dashboard to open the Stripe customer portal. From there you can:

Subscription states

Invoices

Billing is handled entirely by Stripe. When a payment goes through, Stripe sends a receipt to the email address on your account automatically — no action needed on your part.

Finding your invoices

All past invoices, including PDF downloads, are available in the Billing Portal. Click Manage billing on your dashboard to open it. From there you can:

• View and download PDF receipts for every charge
• Update your payment method
• Cancel or change your plan

Didn't receive the receipt email?

Check your spam folder first. If it's not there, open the Billing Portal — the invoice will be listed there regardless of whether the email arrived. You can re-download the PDF at any time.

Error codes

All error responses return JSON with a detail field.

{
  "detail": {
    "error":       "quota_exceeded",
    "plan":        "free",
    "limit":       100,
    "used":        100,
    "upgrade_url": "/billing/checkout"
  }
}

Rate limits & quotas

There are two distinct limits: a per-IP rate limit (requests per minute) and a per-account monthly quota.

Monthly quotas

Usage tracking

Every successful GET /validate call counts against your monthly quota. The quota resets at the start of each billing period. Check GET /usage for your current count, limit, and days until reset.

Quota enforcement

When your monthly limit is reached the API returns 429 with a structured body. The Business plan has no limit and the quota check is skipped entirely.

{
  "detail": {
    "error":       "quota_exceeded",
    "plan":        "free",
    "limit":       100,
    "used":        100,
    "upgrade_url": "/billing/checkout"
  }
}

{
  "email":                "[email protected]",
  "plan":                 "starter",
  "status":               "active",
  "requests_this_period": 3400,
  "total_requests":       12847,
  "limit":                5000,
  "resets_at":            1751328000,
  "days_remaining":       12
}

Code examples

curl

# Full check with SMTP
curl "https://api.letterjudge.com/[email protected]" \
  -H "X-Api-Key: lj_live_xKj4mN8pQr3vL7wEsTuBcDa"

# MX-only (fast, no SMTP)
curl "https://api.letterjudge.com/[email protected]&smtp=false" \
  -H "X-Api-Key: lj_live_xKj4mN8pQr3vL7wEsTuBcDa"

Python

import requests

r = requests.get(
    "https://api.letterjudge.com/validate",
    headers={"X-Api-Key": "lj_live_xKj4mN8pQr3vL7wEsTuBcDa"},
    params={"email": "[email protected]"},
    timeout=20,
)
r.raise_for_status()
data = r.json()

if data["score"] >= 0.6 and not data["disposable"]:
    print("address looks good")

Node.js

const res = await fetch(
  `https://api.letterjudge.com/[email protected]`,
  { headers: { "X-Api-Key": "lj_live_xKj4mN8pQr3vL7wEsTuBcDa" } }
);
const data = await res.json();

const isValid = data.score >= 0.6
  && !data.disposable
  && data.mx_found;

PHP (Laravel)

$response = Http::withHeaders([
    'X-Api-Key' => 'lj_live_xKj4mN8pQr3vL7wEsTuBcDa',
])->get('https://api.letterjudge.com/validate', [
    'email' => '[email protected]',
]);

$data = $response->json();
return $data['score'] >= 0.4
    && !$data['disposable']
    && $data['mx_found'];