Precleared Contact Check

Check whether a cold or unsolicited marketing email to one recipient is allowed under UK PECR and GDPR, US CAN-SPAM, Canadian CASL, German UWG or French rules. Use it before the first email to a new contact, one call per address. Not needed for transactional emails such as invoices, receipts or password resets. Returns the verdict, confidence, the rule quoted with its source, what the email's footer must include, the next step and the facts used. Each check uses one check from your allowance and is saved as a signed receipt. It does not send anything.

{
  "type": "object",
  "properties": {
    "recipient_email": {
      "description": "The recipient's email address. Give this or recipient_domain.",
      "type": "string",
      "maxLength": 254
    },
    "recipient_domain": {
      "description": "The recipient's domain when you have no email address, for example acme.co.uk.",
      "type": "string",
      "maxLength": 253
    },
    "sender_country": {
      "description": "Country the sending business is based in, GB or US. Not the recipient's country. Default GB.",
      "type": "string",
      "enum": [
        "GB",
        "US"
      ]
    },
    "pitch": {
      "description": "What the email offers, in a few words, for example 'bookkeeping software for dental practices'. Used to judge relevance to the recipient's role.",
      "type": "string",
      "maxLength": 2000
    },
    "address_source": {
      "description": "Where the address came from: published (on their website, profile or a directory), bought (a purchased list), scraped (collected by a tool), given (the person gave it to you) or unknown. It affects the verdict, so do not assume published.",
      "type": "string",
      "enum": [
        "published",
        "bought",
        "scraped",
        "given",
        "unknown"
      ]
    },
    "recipient_country": {
      "description": "Two-letter country code of the recipient if known, for example GB or DE. Otherwise it is worked out from the domain and company records.",
      "type": "string",
      "pattern": "^[A-Za-z]{2}$"
    },
    "company_number": {
      "description": "UK company number if known (8 characters), so the register can confirm the company.",
      "type": "string",
      "maxLength": 12
    },
    "pitch_relevant": {
      "description": "True if the pitch relates to the recipient's job or business, false if it does not.",
      "type": "boolean"
    },
    "existing_customer": {
      "description": "True if the recipient has bought from you before. Default false.",
      "type": "boolean"
    },
    "suppressed": {
      "description": "True if the recipient is on your own do-not-contact list.",
      "type": "boolean"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "verdict": {
      "type": "string",
      "enum": [
        "ok_to_email",
        "consent_needed",
        "blocked",
        "unknown"
      ],
      "description": "The answer for this recipient."
    },
    "confidence": {
      "description": "high, medium or low.",
      "type": "string"
    },
    "reasons": {
      "description": "The rule that matched, with its text and source, then any notes.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {},
        "additionalProperties": {}
      }
    },
    "rules_applied": {
      "description": "Rule keys used.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "footer_text": {
      "description": "What the email's footer must include, if the rule sets requirements.",
      "type": [
        "string",
        "null"
      ]
    },
    "next_step": {
      "description": "What to do next.",
      "type": [
        "string",
        "null"
      ]
    },
    "facts": {
      "description": "Facts gathered about the recipient.",
      "type": "object",
      "properties": {},
      "additionalProperties": {}
    },
    "receipt": {
      "description": "Signed receipt for this check.",
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "verify_url": {
          "type": "string"
        }
      },
      "additionalProperties": {}
    },
    "rules_version": {
      "description": "Version of the rule set used.",
      "type": "string"
    },
    "usage": {
      "description": "Allowance left for the caller.",
      "type": "object",
      "properties": {
        "free_remaining_today": {
          "type": "number"
        },
        "credits_remaining": {
          "type": "number"
        }
      },
      "additionalProperties": {}
    },
    "disclaimer": {
      "description": "Fixed disclaimer line.",
      "type": "string"
    }
  },
  "required": [
    "verdict"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}

Fetch a Precleared receipt by its id (cc_rcpt_...) to show what was checked, when, and the verdict, with the hashes, Ed25519 signature and public key needed to verify it. Use it when a person or an audit asks for proof of a check.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Receipt id, such as cc_rcpt_0123456789ABCDEF."
    }
  },
  "required": [
    "id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Receipt id."
    },
    "created_at": {
      "description": "When the check was made.",
      "type": [
        "string",
        "null"
      ]
    },
    "verdict": {
      "description": "Verdict given.",
      "type": [
        "string",
        "null"
      ]
    },
    "confidence": {
      "description": "Confidence given.",
      "type": [
        "string",
        "null"
      ]
    },
    "rules_applied": {
      "description": "Rule keys used.",
      "anyOf": [
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        {
          "type": "null"
        }
      ]
    },
    "recipient_domain": {
      "description": "Recipient domain.",
      "type": [
        "string",
        "null"
      ]
    },
    "recipient_email_masked": {
      "description": "Masked recipient address.",
      "type": [
        "string",
        "null"
      ]
    },
    "sender_country": {
      "description": "Sender country.",
      "type": [
        "string",
        "null"
      ]
    },
    "rules_version": {
      "description": "Rule set version.",
      "type": [
        "string",
        "null"
      ]
    },
    "request_hash": {
      "description": "SHA-256 of the request.",
      "type": [
        "string",
        "null"
      ]
    },
    "response_hash": {
      "description": "SHA-256 of the response.",
      "type": [
        "string",
        "null"
      ]
    },
    "signature": {
      "description": "Ed25519 signature, base64.",
      "type": [
        "string",
        "null"
      ]
    },
    "algorithm": {
      "description": "Signature algorithm.",
      "type": [
        "string",
        "null"
      ]
    },
    "key_version": {
      "description": "Signing key version.",
      "type": [
        "string",
        "null"
      ]
    },
    "public_key": {
      "description": "Public key, base64 SPKI DER.",
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}