# Sign-up policy rehearsal

Adding email validation to a sign-up form is a bet: you stop some junk and you may turn away real customers. You do not have to guess. Your past sign-ups already tell you who went on to pay. `salchimail-local rehearse` replays each rule over them and counts what it would have blocked.

It runs on your machine. By default nothing is sent to anyone.

The examples on this page are the tool's real output on **synthetic test data**: invented sign-ups on `.example` domains with a simulated DNS. The numbers show the format of the report. They say nothing about your sign-ups.

## What you need

Install the tool as described in [Local-first verification](https://docs.salchimail.com/local-first.md). Then export your past sign-ups to a CSV (or JSONL) with two columns:

```csv
email,outcome
ana@discrimina.example,paid
nora@discrimina.example,
tom@mailinator.com,fraud
```

| `outcome` | Counted as |
| --- | --- |
| `paid`, `activated` | **Good**: a customer you would not want to lose |
| `fraud`, `spam`, `chargeback` | **Junk**: a sign-up you would have liked to stop |
| empty | **No outcome**: you do not know. It is not counted as junk |

A true/false column works as well: `--outcome-column paid`. The last 90 days of sign-ups are a sensible sample.

If you also keep a history file in the format of [Local-first verification](https://docs.salchimail.com/local-first.md), pass it with `--history`: `payment` and `activation` events count as good; `fraud` events and hard bounces of your own email count as junk.

## Run it

```sh
salchimail-local rehearse --signups signups.csv --out detail.csv
```

```text
Sign-up policy rehearsal: 13 sign-ups (5 good: paid or activated; 2 junk: flagged or hard-bounced; 6 with no outcome)

RULE                             WOULD BLOCK  GOOD LOST  JUNK STOPPED  NO OUTCOME  WHAT IT DOES
reject_syntax                    1            0          0             1           Reject addresses with invalid syntax
require_mx                       3            0          1             2           Reject domains that cannot receive mail
reject_invalid                   4            0          1             3           Reject what basic mode calls invalid (the two rules above)
block_disposable                 2            1          1             0           Block disposable domains
block_legacy                     1            1          0             0           Block domains of discontinued providers
block_free                       0            0          0             0           Block free webmail (Gmail, Outlook, Yahoo...)
reject_invalid_block_disposable  6            1          2             3           Reject invalid and block disposable (the documented sign-up pattern)

Read with care: addresses are checked as they are today, not as they were on the sign-up date; sign-ups that an earlier rule already rejected are not in your data; and small counts prove little.
```

Each row is one rule you could turn on:

| Rule | It blocks | With the API |
| --- | --- | --- |
| `reject_syntax` | Addresses that are not valid email syntax | `invalid` · `syntax_invalid` |
| `require_mx` | Domains that cannot receive mail | `invalid` · `domain_not_found`, `domain_null_mx`, `domain_no_mail_host` |
| `reject_invalid` | Both of the above: everything `basic` mode calls `invalid` | `verdict` is `invalid` |
| `block_disposable` | Disposable domains | `risky` · `disposable_domain` |
| `block_legacy` | Domains of discontinued providers | `risky` · `legacy_domain` |
| `block_free` | Free webmail (Gmail, Outlook, Yahoo…), as "work email only" forms do | `flags.free` is `true` |
| `reject_invalid_block_disposable` | The pattern of [Verify at sign-up](https://docs.salchimail.com/signup-verification.md) | `invalid`, or `disposable_domain` |

`detail.csv` has one row per sign-up with its outcome and the rules that would have blocked it, so you can look at the good customers behind a number before you decide.

## Read the numbers

In the synthetic example above, `reject_invalid` would have stopped 4 sign-ups and none of them was a customer: a safe rule. `block_disposable` would have stopped 1 junk sign-up and lost 1 customer who activated: a rule to think about, or to turn into a warning instead of a block.

Three things limit what the report can prove. The tool prints them every time:

- **Addresses are checked as they are today**, not as they were on the sign-up date. A domain may have died, or joined the disposable list, since then.
- **You only see the sign-ups that got in.** If a rule was already active, the sign-ups it rejected are not in your data.
- **Small counts prove little.** With a handful of paying customers, read counts, not percentages.

## Optional: rules that need a mailbox check

The rules above need no API call. Two more depend on what the mail server says about each mailbox, so they need the API in `mailbox` mode and credits. First see what would be sent:

```sh
salchimail-local rehearse --signups signups.csv --dry-run
```

The dry run sends nothing and lists the addresses. Sign-ups that a local rule already rejects are never sent, and addresses go in two waves, one per domain first, as in [Local-first verification](https://docs.salchimail.com/local-first.md). If you agree, set the most mailbox credits to spend:

```sh
export SALCHIMAIL_API_KEY=sk_live_…
salchimail-local rehearse --signups signups.csv --budget 500
```

```text
Sign-up policy rehearsal: 13 sign-ups (5 good: paid or activated; 2 junk: flagged or hard-bounced; 6 with no outcome)

RULE                             WOULD BLOCK  GOOD LOST  JUNK STOPPED  NO OUTCOME  WHAT IT DOES
reject_syntax                    1            0          0             1           Reject addresses with invalid syntax
require_mx                       3            0          1             2           Reject domains that cannot receive mail
reject_invalid                   4            0          1             3           Reject what basic mode calls invalid (the two rules above)
block_disposable                 2            1          1             0           Block disposable domains
block_legacy                     1            1          0             0           Block domains of discontinued providers
block_free                       0            0          0             0           Block free webmail (Gmail, Outlook, Yahoo...)
reject_invalid_block_disposable  6            1          2             3           Reject invalid and block disposable (the documented sign-up pattern)
mailbox_reject_invalid           5            0          1             4           Reject what mailbox mode calls invalid
mailbox_reject_invalid_risky     10           3          2             5           Reject invalid and risky in mailbox mode

Mailbox rules use the 6 of 13 addresses that got an answer from the API.
Read with care: addresses are checked as they are today, not as they were on the sign-up date; sign-ups that an earlier rule already rejected are not in your data; and small counts prove little.
```

`mailbox_reject_invalid` adds the mailboxes the server says do not exist. `mailbox_reject_invalid_risky` also rejects every `risky` result, catch-all servers included; in the synthetic example that would have lost 3 customers. Remember that `mailbox` mode can take up to 30 seconds, so at sign-up it belongs in a background job, not in the form ([timings](https://docs.salchimail.com/signup-verification.md)).

## Then write the policy

Turn on the rules the rehearsal showed to be safe, with the pattern of [Verify at sign-up](https://docs.salchimail.com/signup-verification.md): call the API from your server in `basic` mode, reject what you decided to reject, and **accept the sign-up whenever the call fails**. Run the rehearsal again in a few months: your sign-ups change.

An AI agent can do the whole job in your repository: find the users table, export the two columns, run the rehearsal, show you the table and write the code and its tests. The skill is [`salchimail-local`](https://docs.salchimail.com/skills/salchimail-local/SKILL.md).
