Guides
Strict mode
By default PristineSend sends an API email whenever it can: a transactional email is never skipped, and if an address check cannot answer, the email goes. That is right for password resets and receipts. It is not what you want from an AI agent, which can make a typo, leave a placeholder in a link, or invent an address. In strict mode such an email is refused instead of sent, with a reason the agent can act on.
Overview
Strict mode applies to POST /api/v1/send, POST /api/v1/send/batch and the MCP send_email tool. A strict email is refused when:
- its content is unfinished (below);
- its recipient's address is misspelt, a throwaway address, not deliverable, or likely to bounce (below);
- the check could not run, for example because the address lookup did not answer. You get a
503 and can try again; a strict email is never sent unchecked.
Everything else works as for any other key: the do-not-send list, the emails-per-contact limit and the security review of API email still apply.
Turning it on
For an API key: tick Strict mode when you create the key in Settings → Developer, or on the key in the list afterwards. It works on live and test keys. Rotating a key keeps its setting.
For agents connected through MCP: turn on Strict mode for connected agents in Settings → Developer. It covers every agent connected to the account. It is off until you turn it on.
Only the account's Owner can change either setting.
Unfinished content
The email is refused with 422 content_unfinished when the deliverability check finds one of the four things that mean it is not finished: no subject, an empty picture spot, a link left as a placeholder (such as https://example.com or localhost), or a placeholder picture. The message names each one. Nothing is written and no address is checked.
The address check
First the address is checked for free: its syntax, a reserved domain, a misspelt mail provider (gmial.com) and a known throwaway domain. If it passes, we use what we already know about it: the answer of a strict check of the same address in the last 30 days, or the contact's own verification from the last 180 days. Only when we know nothing is the address looked up.
The email is refused with 422 address_rejected when the answer is misspelt, throwaway, not deliverable, or likely to bounce (a delivery confidence under 46 of 100). Role addresses such as info@ are not refused for being role addresses. A refused email is logged as skipped, so it shows in your email logs and an email.skipped webhook carries details.reason: "address_check".
A ps_test_ key never looks an address up: it gets the free checks and anything we already know, and its email is captured as usual.
What a check costs
The free checks and an answer we already have cost nothing. A lookup uses one of your plan's monthly verifications. Once those are used, it costs 1.5 cents from your verification credits, taken in whole cents as the total adds up. With no verifications left and too few credits to pay for the check, the email is refused with 402 verification_allowance_exhausted; add credits in Billing, or send it with a key that is not strict. An address that appears twice in one batch is checked once.
What your code sees
| Status | Code | What to do |
|---|
| 422 | content_unfinished | Finish the email (the message lists what), then send again. |
| 422 | address_rejected | Get a correct address. Do not retry the same one. |
| 402 | verification_allowance_exhausted | Tell the account owner; add credits in Billing. |
| 503 | service_unavailable | The check could not run. Retry after Retry-After. |
In a batch each item gets its own answer, with the same codes. An example refusal:
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
{
"error": {
"code": "address_rejected",
"message": "Not sent (strict mode): this address looks misspelt (did you mean jane@gmail.com?).",
"param": "to",
"request_id": "req_8f3c9a1b2d4e5f6071829304"
}
}
import { PristineSend, PristineSendError } from "pristinesend"
const ps = new PristineSend(process.env.PRISTINESEND_AGENT_KEY!) // a strict key
try {
await ps.emails.send({ to, subject, html })
} catch (err) {
if (err instanceof PristineSendError) {
switch (err.code) {
case "address_rejected": // ask the person for a correct address
case "content_unfinished": // finish the email, then send again
case "verification_allowance_exhausted": // tell the account owner
return { sent: false, reason: err.message }
}
}
throw err // 503s are retried by the SDK; anything else is a real failure
}
Retries
With an Idempotency-Key, a content_unfinished refusal is stored and replayed, because the same content always gets the same answer. address_rejected, 402 and 503 are not stored: a retry with the same key is checked again, so it goes through once credits are added or the check can run.