Deliverability check

Ask "will this land?" before you send. The deliverability check scores email content for spam triggers, deliverability, and engagement issues and returns an actionable verdict — the same analysis behind the dashboard's AI Deliverability Score. It is a pure pre-send check: nothing is sent and no email is logged.

Overview

Method	Path	Description
`POST`	`/api/v1/deliverability/check`	Score email content; returns a verdict. Does not send.

Requires a key with the deliverability:check scope (a full-access key has it). Checks are unmetered — the same "unlimited scans" as the editor — bounded by the standard per-key rate limit.

Why check before sending

Anyone can generate an email. Whether it reaches the inbox depends on content quality and sender reputation. Run the check in your send pipeline and branch on the verdict — gate on DANGER, surface issues for a human or an agent to fix, then send. Each issue carries a stable code so you can decide programmatically.

The verdict object

Field	Type	Description
`score`	`number`	Overall deliverability score, 0–100 (higher is better).
`verdict`	`string`	GOOD, WARNING, or DANGER — a quick gate for send / fix / abort.
`summary`	`string`	One-sentence overall assessment.
`issues`	`Issue[]`	Specific, actionable problems found (see below). Empty when none.
`suggestions`	`string[]`	Optional improvement ideas beyond the concrete issues.

Issue

Field	Type	Description
`code`	`string`	Stable category an agent can branch on: subject, content, structure, or spam.
`severity`	`string`	high, medium, or low.
`title`	`string`	Short label for the issue.
`description`	`string`	What the issue is and why it matters.
`fix`	`string`	Concrete suggestion to resolve it.

Check deliverability

POST/api/v1/deliverability/check

Send a subject and the body as html and/or text. Returns 200 with the verdict. Nothing is sent and no email log row is written.

Request body

Field	Type	Required	Description
`subject`	`string`	required	The subject line to score.
`html`	`string`	optional	HTML body to analyze. Provide this and/or text (HTML is preferred).
`text`	`string`	optional	Plaintext body. Used when html is omitted. At least one of html/text is required.

Response

"color:#ff7b72">import { PristineSend } "color:#ff7b72">from "pristinesend"

"color:#ff7b72">const ps = "color:#ff7b72">new PristineSend(process.env.PRISTINESEND_API_KEY!)

// A pre-send check — nothing is sent. Decide send / fix / abort "color:#ff7b72">from the verdict.
"color:#ff7b72">const v = "color:#ff7b72">await ps.deliverability.check({
  subject: "Your June invoice is ready",
  html: "<p>Hi — your invoice for June is attached.</p>",
})

console.log(v.score, v.verdict) // e.g. 82 "GOOD"
if (v.verdict === "DANGER") {
  for ("color:#ff7b72">const issue of v.issues) {
    console.log(`[${issue.code}/${issue.severity}] ${issue.title} — ${issue.fix}`)
  }
  // ...fix the content, then send.
}

Errors

All errors use the standard envelope. The codes specific to this endpoint:

Status	code	When
`400`	`missing_field`	No subject, or neither html nor text supplied.
`400`	`invalid_field`	subject/html/text present but not a string.
`401`	`unauthorized`	Missing or invalid API key.
`403`	`insufficient_scope`	The key lacks the deliverability:check scope.
`429`	`rate_limited`	Per-key rate limit exceeded.
`503`	`service_unavailable`	The analysis backend is temporarily unavailable — retry.

See the full Error codes reference for the canonical envelope and the complete list.