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. 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, 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

curl
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 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:

curl
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. If you agree, set the most mailbox credits to spend:

curl
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).

Then write the policy

Turn on the rules the rehearsal showed to be safe, with the pattern of Verify at sign-up: 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.

View this page as Markdown