---
name: salchimail-local
description: Clean an email list or rehearse sign-up validation rules on the user's own machine with the salchimail-local tool, so SalchiMail only sees the addresses a mailbox check can resolve. Use when the user wants to clean or verify a list and has their own sending history (ESP or CRM exports, bounce logs, replies), wants to share as little data as possible, asks which addresses would be sent before verifying, or wants to know what a sign-up rule (block disposable domains, require MX, reject invalid) would have blocked among past sign-ups and how many paying customers it would have cost.
compatibility: Needs a shell, read access to the user's exports and the salchimail-local binary (Linux, macOS or Windows; no runtime). Local steps need only DNS. The optional mailbox checks need network access to api.salchimail.com and a SalchiMail API key in SALCHIMAIL_API_KEY.
metadata:
  author: ZENIFICA, S.L.
  version: "0.1.0"
  homepage: https://docs.salchimail.com/local-first
---

# SalchiMail local-first verification

`salchimail-local` runs on the user's machine. It decides what it can from the user's own history (who replied, what bounced), from syntax, a disposable-domain list and DNS, and sends to the SalchiMail API only the addresses where probing the mailbox can add something. It never sends email.

Two commands:

- `clean`: a decision (`send`, `do_not_send`, `review`, `not_checked`) and a readable reason for every address of a list.
- `rehearse`: what each sign-up validation rule would have blocked among past sign-ups, how many good customers it would have lost and how much junk it would have stopped.

Use the `salchimail` skill instead for a single address, for a list with no history when the user just wants every mailbox checked, or for credits and plans.

## Rules you must follow

- **The history never leaves the machine.** Do not upload it, paste it into another service or send it to any API. The tool does not send it either.
- **Do not read the data yourself more than you need.** Look at headers and a few rows to learn the columns, then let a script and the tool process the rows. Read bounce codes and event names, never message bodies. Do not extract names or new addresses from mailboxes or logs.
- **Always run `--dry-run` first and wait for a human yes** before any run with `--budget`. The dry run sends nothing and lists the exact addresses a real run would send.
- **The budget is the user's decision.** Never pick or raise `--budget` yourself.
- The API key comes from the `SALCHIMAIL_API_KEY` environment variable. Never print it, write it to a file or pass it as an argument.
- `review` and `not_checked` are not `invalid`. Never tell the user to delete those addresses.
- Only work on lists the user has a legitimate reason to verify (their own customers, sign-ups or subscribers).

## Get the tool

Check first: `salchimail-local version`. If it is missing, download the binary for the machine and make it executable:

| System | File |
| --- | --- |
| Linux x86-64 | https://docs.salchimail.com/tools/salchimail-local-linux-amd64 |
| Linux ARM64 | https://docs.salchimail.com/tools/salchimail-local-linux-arm64 |
| macOS Apple silicon | https://docs.salchimail.com/tools/salchimail-local-darwin-arm64 |
| macOS Intel | https://docs.salchimail.com/tools/salchimail-local-darwin-amd64 |
| Windows x86-64 | https://docs.salchimail.com/tools/salchimail-local-windows-amd64.exe |
| Windows ARM64 | https://docs.salchimail.com/tools/salchimail-local-windows-arm64.exe |

```sh
curl -fsSLo salchimail-local https://docs.salchimail.com/tools/salchimail-local-linux-amd64
chmod +x salchimail-local
./salchimail-local version
```

Compare its SHA-256 with https://docs.salchimail.com/tools/SHA256SUMS before running it. Tell the user where you saved the binary.

## Clean a list

### 1. Find the user's own history

Ask the user where their sending results live if it is not obvious. Usual places:

| Source | What to export |
| --- | --- |
| Email service (Mailchimp, Brevo, Klaviyo, SendGrid, Mailgun, Postmark, Amazon SES…) | Activity or event export of the last 12 months: delivered, bounced (with type or SMTP code), opened, clicked. Also the suppression or bounce list |
| CRM or help desk | Date of the last inbound message from each contact |
| The application's own database | Tables of email events, bounce webhooks, last login or last order |
| A bounce mailbox or mail server log | Delivery status notifications: recipient, status code and date |

No history at all is fine: run `clean` without `--history`. The tool still resolves syntax, disposable domains and dead domains locally.

### 2. Write `history.csv`

One row per event, three columns: `email,kind,at`. Write a small script for the conversion instead of reading every row. `at` is a date (`2026-11-17`) or an RFC 3339 timestamp.

| `kind` | Use it for | Effect in `clean` |
| --- | --- | --- |
| `reply` | A person wrote back (inbound message from the address) | `send` for 180 days |
| `click` | A link in the user's email was clicked | `send` for 180 days |
| `open` | The email was opened | `send` for 90 days |
| `delivered` | The server accepted the message and no bounce came back | `send` for 90 days |
| `hard_bounce` | Permanent failure about the recipient: "user unknown", `5.1.1`, `5.1.10`, "no such mailbox" | `do_not_send` for 365 days |
| `soft_bounce` | Temporary failure: `4.x.x`, mailbox full, greylisting, timeout | Decides nothing, and cancels older good news |
| `policy_bounce` | Rejected because of the sender or the content: `5.7.x`, "blocked", "spam" | Ignored |
| `auto_reply` | Out-of-office or any automatic answer | Ignored |
| `signup`, `payment`, `activation`, `fraud` | Sign-up outcomes | Only used by `rehearse` |

The most recent event that has not expired wins. When you cannot tell whether a bounce is permanent, record it as `soft_bounce`: a wrong `hard_bounce` would drop a real contact. An unknown `kind` makes the tool stop and name the row.

The list itself is a CSV with a header row (column `email`, or pass `--email-column`) or a JSONL file.

### 3. Dry run

```sh
salchimail-local clean --list list.csv --history history.csv --dry-run --out plan.csv
```

Nothing is sent. The summary says how many addresses were resolved on the machine and lists the addresses a real run would send: wave 1 is one address per domain; wave 2 goes only to the domains whose server tells mailboxes apart. `plan.csv` has one row per address with the column `api` set to `would_send`, `would_send_conditional` or `no`.

### 4. Ask the user

Show the counts from the summary: resolved locally, would be sent in wave 1, could be sent in wave 2. Then ask two things and wait for the answer:

1. May these addresses be sent to SalchiMail for a mailbox check?
2. What is the most mailbox credits to spend (`--budget`)? Each address sent costs at most 1 credit, and nothing when the result is `unknown`.

A large mailbox batch can take hours on lists concentrated on a few domains. Say so before starting.

### 5. Run

```sh
salchimail-local clean --list list.csv --history history.csv --budget 500 --out results.csv
```

- Exit code `0`: done. `3`: a batch is still running; run **exactly the same command** again later to collect it (nothing is charged twice). `1`: an error was printed; what was resolved locally is still in the output.
- Add `--lang es` for reasons and summary in Spanish.
- Without `--budget` the run is local only and sends nothing.

### 6. Report

Give the user the summary lines as printed: resolved on the machine, sent, credits charged, and how many addresses never left the machine. Then the file. Its columns:

| Column | Values |
| --- | --- |
| `row` | 1-based position in the list. Join back by this, not by the address |
| `action` | `send`, `do_not_send`, `review` (catch-all, disposable, or the server did not answer: the user decides), `not_checked` (no budget, or the batch is not finished) |
| `source` | `own_history`, `local_rules` (syntax, lists), `local_dns`, `api` (this address was probed), `api_domain` (not sent: the answer for another address of the same domain applies), `none` |
| `api` | `sent`, `no`, `pending`; in a dry run `would_send`, `would_send_conditional` |
| `reason_code` | `own_reply`, `own_delivered`, `own_hard_bounce`…, or a SalchiMail reason code such as `catch_all` |
| `reason` | The same in words, with the date of the evidence |

Be honest about the limits: "accepted without a bounce" does not prove the inbox was reached, opens and clicks can be automatic, and the expiry periods are starting values, not measured ones.

## Rehearse a sign-up policy

Use it before the user adds validation to a sign-up form, or to review the rules they already have.

1. **Find past sign-ups and their outcome.** Usually the users table: email, creation date and a sign of what happened next (paid, activated, subscription status, flagged as fraud). Ask the user which column means "good customer". 90 days of sign-ups is a sensible sample.
2. **Export `signups.csv`** with the columns `email` and `outcome`. Accepted outcomes: `paid`, `activated` (good); `fraud`, `spam`, `chargeback` (junk); empty (no outcome). A true/false column works too: `--outcome-column paid`. A `--history` file adds outcomes from events: `payment` and `activation` count as good, `fraud` and `hard_bounce` as junk.
3. **Run it. It is local: nothing is sent.**

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

4. **Show the table.** One row per rule: `reject_syntax`, `require_mx`, `reject_invalid`, `block_disposable`, `block_legacy`, `block_free` and `reject_invalid_block_disposable`, each with how many sign-ups it would have blocked, how many of those were good and how many were junk. `detail.csv` lists the rules that would block each sign-up.
5. **Read it with the user.** Give counts, not percentages, when the numbers are small. Repeat the three caveats the tool prints: addresses are checked as they are today, not on the sign-up date; sign-ups rejected by an earlier rule are missing from the data; and "no outcome" does not mean junk.
6. **Optional mailbox rules.** `--dry-run` shows which addresses would be sent; after the user agrees and sets a budget, `--budget N` adds the rows `mailbox_reject_invalid` and `mailbox_reject_invalid_risky`.
7. **Propose the policy and write the code.** Call `POST /verify` in `basic` mode from the server, reject what the rehearsal showed to be safe, and accept the sign-up whenever the call fails. The pattern is in https://docs.salchimail.com/signup-verification

## When something goes wrong

| Message | Do this |
| --- | --- |
| `no "email" column (found: …)` | Pass `--email-column` with one of the names listed |
| `the first row must be a header` | Add a header row to the CSV |
| `unknown kind … row N` | Fix that row of the history; the valid kinds are listed in the message |
| `set the SALCHIMAIL_API_KEY environment variable` | Ask the user to export their key, or run without `--budget` |
| `SalchiMail API answered 402 insufficient_credits` | The balance is too low: use the `salchimail` skill to check usage and offer a purchase link |
| `SalchiMail API answered 429 …` after retries | A daily limit was reached: run the same command again later |
| The run is slow before anything is sent, or every domain comes out as `domain_no_mail_host` | The machine cannot resolve public DNS names: add `--no-dns` |

## Reference

- Guides: https://docs.salchimail.com/local-first and https://docs.salchimail.com/signup-rehearsal
- All flags: `salchimail-local clean -h`, `salchimail-local rehearse -h`
- The tool contacts only the machine's DNS resolver (domain names) and `api.salchimail.com` (the addresses listed by `--dry-run`). It has no telemetry.
