Active

Markov Mail API

v3.0.0 · Email fraud detection at the edge · GitHub

Email Validation

POST/validateScore an email address

Request

curl -s -X POST https://fraud.erfi.dev/validate \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","name":"Jane Doe"}'

Request fields: email (required), name (optional — improves identity signals), consumer (optional), flow (optional)

Response

{
  "valid": true,
  "riskScore": 0.12,
  "decision": "allow",
  "signals": {
    "entropyScore": 0.34,
    "formatValid": true,
    "isDisposableDomain": false,
    "randomForestScore": 0.12,
    "patternType": "natural",
    "mxSignals": { "hasRecords": true, "primaryProvider": "google" }
  },
  "fingerprint": { "hash": "a1b2c3...", "country": "US" },
  "latency_ms": 8
}

Decisions: allow (score < 0.35), warn (0.35–0.64), block (≥ 0.65). Blocked non-/validate POSTs return 403.

POST/*Auto-validates any POST with email field

POST/signupExample: signup with fraud detection

POST/loginExample: login with fraud detection

POST/newsletterExample: newsletter with fraud detection

Configuration

GET/admin/configGet current merged configAPI Key

GET/admin/config/defaultsGet default config valuesAPI Key

PUT/admin/configReplace full configAPI Key

PATCH/admin/configDeep-merge partial configAPI Key

POST/admin/config/resetReset to defaultsAPI Key

POST/admin/config/validateValidate without savingAPI Key

Example: Update thresholds

curl -X PATCH https://fraud.erfi.dev/admin/config \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"riskThresholds":{"block":0.70,"warn":0.40}}'

Config fields: riskThresholds, baseRiskScores, features, logging, headers, actionOverride, riskWeights, rateLimiting, adjustments, ood

Analytics & Data

GET/admin/analytics?type=summaryPre-built query (13 types)API Key

POST/admin/analyticsCustom SQL queryAPI Key

GET/admin/analytics/queriesList all query typesAPI Key

GET/admin/analytics/infoDatabase info & guidanceAPI Key

POST/admin/analytics/truncateDelete old validation dataAPI Key

DELETE/admin/analytics/test-dataRemove test patternsAPI Key

Example: Query block reasons

curl https://fraud.erfi.dev/admin/analytics?type=blockReasons&hours=48 \
  -H "X-API-Key: $KEY"

Query types: summary, blockReasons, riskDistribution, topCountries, highRisk, performance, timeline, fingerprints, disposableDomains, patternFamilies, identitySignals, geoSignals, mxProviders

Disposable Domains

GET/admin/disposable-domains/metadataDomain list statsAPI Key

POST/admin/disposable-domains/updateRefresh from GitHub sourcesAPI Key

DELETE/admin/disposable-domains/cacheClear domain cacheAPI Key

71,000+ disposable email domains tracked. Auto-refreshed every 6 hours via cron.

TLD Risk Profiles

GET/admin/tld-profiles/metadataProfile stats & risk tiersAPI Key

GET/admin/tld-profiles/:tldGet single TLD profileAPI Key

PUT/admin/tld-profiles/:tldUpdate TLD risk profileAPI Key

POST/admin/tld-profiles/syncSync hardcoded profiles to KVAPI Key

DELETE/admin/tld-profiles/cacheClear TLD cacheAPI Key

Example: Adjust TLD risk

curl -X PUT https://fraud.erfi.dev/admin/tld-profiles/xyz \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"riskScore":0.8,"riskTier":"high","notes":"abuse reports"}'

Allowed fields: riskScore (0-1), riskTier, category, notes, registrationVolume, abuseRate

Model Training

GET/admin/training/datasetDataset stats (counts, labels)API Key

GET/admin/training/dataset/downloadDownload full training datasetAPI Key

DELETE/admin/training/datasetPrune old samplesAPI Key

POST/admin/training/triggerStart container retrainingAPI Key

GET/admin/training/statusTraining history & statusAPI Key

POST/admin/training/modelUpload & deploy trained modelAPI Key

Example: Trigger retraining

curl -X POST https://fraud.erfi.dev/admin/training/trigger \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"nTrees":20,"maxDepth":6}'

Pipeline: Feature vectors collected from live traffic → Container trains RF model → Platt calibration → Guardrails → Auto-deploy to KV

Cache Management

DELETE/admin/cache/allClear all cachesAPI Key

DELETE/admin/cache/modelsClear model caches onlyAPI Key

DELETE/admin/cache/heuristicsClear heuristics cacheAPI Key

DELETE/admin/config/cacheClear config cacheAPI Key

Cache TTLs: Config 60s, Heuristics 60s, Models 5min, MX DNS 15min (10k entry LRU), TLD profiles 24h

Authentication & System

GET/admin/healthHealth checkAPI Key

GET/debugRequest signals & fingerprintAPI Key

GET/admin/ab-test/statusA/B experiment statusAPI Key

POST/dashboard/authDashboard login (rate-limited)

GET/dashboardAnalytics dashboardSession

Auth methods: X-API-Key header or Authorization: Bearer <key> for admin endpoints. Dashboard uses HttpOnly session cookies (24h TTL). Login rate-limited to 5 attempts/min/IP.

Decision	Score Range	HTTP Response
`allow`	< 0.35	200 OK
`warn`	0.35 – 0.64	200 OK + headers
`block`	≥ 0.65	403 Forbidden (non-/validate)

Open Dashboard GitHub

Markov Mail v3.0.0 · Cloudflare Workers · 48-feature RF · Platt-calibrated · <20ms P50