API Reference

Deliverability check

Ask "is this ready?" before you send. The deliverability check scores email content against fixed rules — the same rules behind the deliverability score in the campaign editor — and returns a verdict, the issues found, and what each one costs. The same email always gets the same 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, and this endpoint has its own limit of 20 requests per minute, separate from the 1,000/minute your other calls share.

Why check before sending

Anyone can generate an email. Whether it reaches the inbox depends on what filters actually weigh: where the links go, the balance of text and images, honest personalisation and a clean subject — plus your sender reputation, which no content check can see. Run the check in your send pipeline and branch on the verdict: hold on DANGER, surface issues for a human or an agent to improve, then send. Each issue carries a stable rule and code so you can decide programmatically.

The check reads the content you send and never opens the links or pictures in it, so it cannot tell you whether an address answers. In the app, the review page and the approval screen open them, and the editor does when you press Check links: those screens can add a link that doesn't open or a picture that doesn't load to the same score. This endpoint never does, so the same content can score higher here than on the review page.

The verdict object

Field	Type	Description
`score`	`number`	0–100, higher is better. Always 100 minus the points of the issues listed, never below 0, so it is explained by them.
`verdict`	`string`	DANGER when something is unfinished (don't send it as is), GOOD at 90 or above, otherwise WARNING.
`summary`	`string`	A short summary, such as "2 things to improve" or "Looks good".
`issues`	`Issue[]`	What would make the email better, most important first (see below). Empty when there is nothing to improve.
`suggestions`	`string[]`	The suggestions of the first three issues, for a quick summary.

Issue

Field	Type	Description
`code`	`string`	Stable category an agent can branch on: subject, content, structure, or spam.
`severity`	`string`	high means unfinished — the campaign editor holds a send until it is resolved. medium costs 10 points or more, low less.
`title`	`string`	What was noticed, in a sentence.
`description`	`string`	Why it matters.
`fix`	`string`	What would be better.
`rule`	`string`	The rule that raised it — a stable identifier, such as link_shortener, for branching on one finding.
`points`	`number`	What this issue costs. The score is 100 minus the sum, never below 0.

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 / improve / hold "color:#ff7b72">from the verdict.
"color:#ff7b72">const v = "color:#ff7b72">await ps.deliverability.check({
  subject: "Your June invoice is ready",
  html: "color:#a5d6ff">'<p>Hi {{ first_name }} — your invoice for June is ready.</p><p><a href="https://bit.ly/june-invoice">View your invoice</a></p>',
})

console.log(v.score, v.verdict) // 82 "WARNING"
if (v.verdict === "DANGER") {
  // Something is unfinished (a placeholder link, an empty image spot). Don't send it "color:#ff7b72">as is.
  throw "color:#ff7b72">new Error(v.issues.filter((i) => i.severity === "high").map((i) => i.title).join(" "))
}
for ("color:#ff7b72">const issue of v.issues) {
  console.log(`-${issue.points} ${issue.title} ${issue.fix}`)
}

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`	`rate_limit_unavailable`	The rate limit could not be checked, so the request was refused — retry.

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