REST API Reference

Complete reference for the Emailens REST API, preview emails, manage API keys, audit domains, and create share links.

The Emailens API is hosted at https://emailens.dev/api.

All endpoints expecting authentication require an Authorization: Bearer ek_live_... header or an x-api-key header.

Endpoints Overview

POST /api/preview: Run the 14-point audit engine and per-client transforms.
POST /api/share: Generate a public shareable preview URL.
GET /api/keys: List active API keys and 30-day usage metrics.
POST /api/keys: Create a new API key.
DELETE /api/keys/[id]: Revoke an API key.
GET /api/domains: List monitored sending domains and DNS health scores.
POST /api/domains: Add a new sending domain for continuous drift monitoring.
DELETE /api/domains/[id]: Remove a monitored domain.
POST /api/deliverability: On-demand DNS audit (SPF, DKIM, DMARC, MX, BIMI).
POST /api/mcp: Hosted Model Context Protocol (MCP) JSON-RPC endpoint.

POST /api/preview

Accepts HTML, React Email (JSX), or MJML and returns client-specific transforms, CSS warnings, compatibility scores, dark mode variants, and quality audits.

Request

curl -X POST https://emailens.dev/api/preview \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ek_live_..." \
  -d '{
    "html": "<html><body><h1>Hello World</h1></body></html>",
    "format": "html",
    "clients": ["gmail-web", "outlook-windows", "apple-mail"],
    "title": "Welcome Email v2"
  }'

Request Body

Field	Type	Required	Description
`html`	`string`	Yes	Email markup (HTML, JSX, or MJML, max 500KB)
`format`	`string`	No	`"html"` (default), `"jsx"`, `"mjml"`, or `"maizzle"`
`clients`	`string[]`	No	Filter to specific client IDs. Omit to run all 21 clients
`title`	`string`	No	Title for dashboard saving (authenticated requests)

Response

{
  "id": "abc123def456",
  "overallScore": 88,
  "transforms": [
    {
      "clientId": "gmail-web",
      "html": "<html>...</html>",
      "warnings": []
    }
  ],
  "compatibilityScores": {
    "gmail-web": { "score": 100, "errors": 0, "warnings": 0, "info": 0 },
    "outlook-windows": { "score": 68, "errors": 2, "warnings": 3, "info": 0 }
  },
  "spamReport": { "score": 95, "triggers": [] },
  "sizeReport": { "bytes": 42150, "clippingRisk": false },
  "linkReport": { "total": 4, "broken": 0, "insecure": 0 },
  "accessibilityReport": { "score": 92, "issues": [] },
  "darkMode": {
    "gmail-web": { "html": "<html>...</html>", "warnings": [] }
  }
}

Additional reports

The response also carries the analyses that power the web app. Each is present on every request and may be null when the check does not apply.

Field	What it covers
`spamReport`	Spam-trigger heuristics over subject and body
`linkReport`	Broken, insecure and untracked links
`accessibilityReport`	Alt text, contrast, semantic structure
`imageReport`	Image weight, dimensions, blocked-image fallbacks
`inboxPreview`	Subject, preheader and sender as the inbox list renders them
`sizeReport`	Total size against the Gmail clipping threshold
`templateReport`	Framework-specific template checks
`overflowReport`	Horizontal overflow measured in a rendered page
`visualReport`	Layout differences between clients
`darkContrast`	Contrast in the dark-mode variants
`mobileContrast`	Contrast at mobile widths
`designReport`	Typography and spacing consistency
`vmlReport`	VML inside `<!--[if mso]>` blocks, invisible to other parsers
`plainText`	Generated text/plain alternative

POST /api/share

Create a public share link for a saved preview result.

curl -X POST https://emailens.dev/api/share \
  -H "Authorization: Bearer ek_live_..." \
  -H "Content-Type: application/json" \
  -d '{"previewId": "abc123def456"}'

Response:

{
  "id": "shr_xyz789",
  "url": "https://emailens.dev/share/shr_xyz789"
}

POST /api/deliverability

Perform an immediate on-demand DNS deliverability audit for any domain.

curl -X POST https://emailens.dev/api/deliverability \
  -H "Authorization: Bearer ek_live_..." \
  -H "Content-Type: application/json" \
  -d '{"domain": "yourcompany.com"}'

Response:

{
  "domain": "yourcompany.com",
  "score": 94,
  "spf": { "valid": true, "record": "v=spf1 include:_spf.google.com ~all", "lookups": 3 },
  "dkim": { "valid": true, "selector": "google" },
  "dmarc": { "valid": true, "policy": "reject", "record": "v=DMARC1; p=reject; rua=mailto:dmarc@yourcompany.com" },
  "mx": { "valid": true, "hosts": ["aspmx.l.google.com"] },
  "bimi": { "valid": true, "indicatorUrl": "https://yourcompany.com/logo.svg" }
}

POST /api/mcp

Hosted JSON-RPC 2.0 Streamable HTTP endpoint for AI assistants (Cursor, Claude Desktop, Windsurf).

curl -X POST https://emailens.dev/api/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ek_live_..." \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

On this page