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

StatusCodeWhat to do
422content_unfinishedFinish the email (the message lists what), then send again.
422address_rejectedGet a correct address. Do not retry the same one.
402verification_allowance_exhaustedTell the account owner; add credits in Billing.
503service_unavailableThe 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.