Map verification categories and statuses to send decisions

A verification result is only useful once it becomes a decision: send, hold, suppress, or check again. SimpleCold gives you two levels to decide on. The category is the broad bucket. The status is the specific reason. Most rules can use the category alone, and the status lets you fine-tune the risky middle.

This guide lists every status, explains what causes it, and gives default actions for three common setups: cold outreach, newsletters and sign-up forms. Copy the tables, then adjust them to your own risk tolerance.

Categories

pending only appears while a check is running. Once you collect the final result it becomes one of the other three. There is no separate unknown bucket: when a mail server won't give a clear answer, the result is risky with the status no_response, and like every finished check it uses a credit. See handle processing results.

Every status, grouped

The status field holds a reason code. Each code belongs to exactly one category and has a fixed failType.

Deliverable

Risky

Undeliverable

The reason shown for each code is fixed, so you can match on the code and show statusMessage as you receive it.

failType helps sort the undeliverable group. permanent means the problem won't fix itself, such as a missing mailbox or a domain that doesn't exist. temporary points to something that may clear up: a server error during the check (server_error). In the risky group, blocked_by_server and no_response are also temporary. If you want to be careful, suppress permanent failures right away and give temporary ones one more check a few days later before suppressing.

Decisions by use case

Cold outreach

Cold email has the least room for error. You have no prior relationship with the recipient, and bounces count against domains you may have spent weeks warming up.

The cold email solutions page covers the wider workflow.

Newsletters and marketing lists

These are people who opted in. You can be more forgiving with risky results, because a real person gave you the address.

Sign-up forms

At sign-up a person is waiting, so the goal is catching mistakes, not filtering hard.

The sign-up guide implements this table.

The same rules in code

Keep the mapping in one place so every service makes the same call. A JavaScript version for cold outreach:

const RISKY_SEND_CAREFULLY = new Set(["accept_all", "mailbox_unconfirmed"]);
const RISKY_RECHECK = new Set(["blocked_by_server", "no_response"]);

export function coldEmailAction(r) {
  if (r.status === "processing") return "recheck";
  switch (r.category) {
    case "deliverable":
      return "send";
    case "undeliverable":
      return r.failType === "temporary" ? "recheck" : "suppress";
    case "risky":
      if (r.status === "disposable" || r.status === "role_address") return "skip";
      if (RISKY_SEND_CAREFULLY.has(r.status)) return "send-carefully";
      if (RISKY_RECHECK.has(r.status)) return "recheck";
      return "review";
    default:
      return "recheck"; // a category added later
  }
}

And in Python for a list job:

def newsletter_action(r: dict) -> str:
    if r["status"] == "processing":
        return "recheck"
    cat = r["category"]
    if cat == "deliverable":
        return "send"
    if cat == "undeliverable":
        return "suppress"
    if cat == "risky":
        return "send"  # opted-in subscribers; suppress on first hard bounce
    return "recheck"

Always include a default branch. New statuses can be added over time, and an unrecognised value should fall into "review" or "recheck", never into "send".

Applying it to a bulk result file

A bulk CSV download keeps your original columns and adds Result, Reason, Reason code, Suggestion and Retry later columns, among others. This script splits it into one file per action:

import csv
from collections import defaultdict


def cold_email_action(r):
    result, code = r["Result"], r["Reason code"]
    if result == "Processing":
        return "recheck"
    if result == "Deliverable":
        return "send"
    if result == "Undeliverable":
        return "recheck" if r["Retry later"] == "Yes" else "suppress"
    if result == "Risky":
        if code in ("disposable", "role_address"):
            return "skip"
        if code in ("accept_all", "mailbox_unconfirmed"):
            return "send-carefully"
        return "recheck"
    return "recheck"


groups = defaultdict(list)
with open("results.csv", newline="", encoding="utf-8-sig") as f:
    reader = csv.DictReader(f)
    fields = reader.fieldnames
    for row in reader:
        groups[cold_email_action(row)].append(row)

for action, rows in groups.items():
    with open(f"results-{action}.csv", "w", newline="", encoding="utf-8") as out:
        w = csv.DictWriter(out, fieldnames=fields)
        w.writeheader()
        w.writerows(rows)
    print(action, len(rows))

Upload results-send.csv to your main campaign and results-send-carefully.csv to the small one, and add results-suppress.csv to your suppression list.

When to re-check

Results age. A deliverable address today can bounce in six months when someone leaves a company. Re-verify before any send to a list older than a few months, and treat no_response and blocked_by_server results as worth another look after a few weeks.

The full status list with descriptions is in the API docs. To run these rules against a whole file, start with run a bulk job end to end.