REST API

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

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

POST /api/preview

The central endpoint. Accepts HTML (or JSX/MJML) and returns per-client transforms, CSS warnings, compatibility scores, dark mode variants, and screenshots.

Request

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

Request body

Field	Type	Required	Description
`html`	`string`	Yes	Email content — HTML, JSX, or MJML (max 500KB)
`format`	`string`	No	Input format: `"html"` (default), `"jsx"`, `"mjml"`, or `"maizzle"`. When set, warnings include framework-specific fix snippets
`clients`	`string[]`	No	Filter to specific client IDs. Omit for all 13 clients
`title`	`string`	No	Preview title (for saved previews, authenticated users only)

Response

{
  "id": "abc123def456",
  "transforms": [
    {
      "clientId": "gmail-web",
      "html": "<html><!-- transformed for Gmail -->...</html>",
      "warnings": [
        {
          "severity": "warning",
          "client": "gmail-web",
          "property": "background-image",
          "message": "background-image has limited support in Gmail Web",
          "suggestion": "Use a solid background color as fallback"
        }
      ]
    }
  ],
  "cssReport": [],
  "compatibilityScores": {
    "gmail-web": { "score": 92, "errors": 0, "warnings": 1, "info": 0 },
    "outlook-windows": { "score": 68, "errors": 2, "warnings": 3, "info": 0 }
  },
  "overallScore": 80,
  "darkMode": {
    "gmail-web": {
      "html": "<html><!-- dark mode variant -->...</html>",
      "warnings": []
    }
  },
  "screenshots": {
    "gmail-web-light": "https://screenshots.emailens.dev/abc123/gmail-web-light.png",
    "gmail-web-dark": "https://screenshots.emailens.dev/abc123/gmail-web-dark.png"
  },
  "compiledHtml": "<!-- only present when format is jsx or mjml -->"
}

Response fields

Field	Type	Description
`id`	`string`	Unique preview ID (nanoid)
`transforms`	`TransformResult[]`	Per-client transformed HTML with warnings
`cssReport`	`CSSWarning[]`	All CSS compatibility warnings
`compatibilityScores`	`Record<string, Score>`	Per-client compatibility scores (0-100)
`overallScore`	`number`	Average score across all clients
`darkMode`	`Record<string, DarkMode>`	Dark mode HTML variants and warnings
`screenshots`	`Record<string, string>`	Screenshot URLs keyed by `{clientId}-{mode}`
`compiledHtml`	`string`	Compiled HTML (only when format is `jsx`, `mjml`, or `maizzle`)

POST /api/share

Create a public share link for a preview result.

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

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

API key management

Manage API keys from the dashboard at Dashboard > API Keys, or use the API endpoints:

GET /api/keys — list your API keys
POST /api/keys — generate a new key
DELETE /api/keys/[id] — revoke a key