# Local-first verification

The best proof that a mailbox exists is that its owner wrote to you last month, or that your last email to it did not bounce. That proof is in your systems, not in ours. `salchimail-local` is a small program that runs **on your machine**, uses what you already know, and asks the API only about the addresses where a mailbox check can tell you something new.

It never sends email, and your history is never uploaded.

The examples on this page are the tool's real output on **synthetic test data**: invented people on `.example` domains, with a simulated DNS and a simulated API. They show how it works, not how much it will resolve on your list. That depends on how much recent history you have.

## What leaves your machine

| Data | Where it goes |
| --- | --- |
| Your history file (deliveries, bounces, replies, sign-up outcomes) | Nowhere. It is read on your machine |
| Addresses resolved by your history, by syntax or by the disposable-domain list | Nowhere |
| Domain names of the addresses that are left | Your own DNS resolver, to see whether the domain can receive mail |
| Addresses that only a mailbox check can resolve | The SalchiMail API, and only when you set a budget. `--dry-run` lists them first |

The tool has no telemetry and contacts nothing else. For the addresses it does send, SalchiMail acts as your processor, exactly as with any other API call.

## Install

One file, no runtime and no dependencies. Download the one for your system:

| System | File |
| --- | --- |
| Linux x86-64 | [`salchimail-local-linux-amd64`](https://docs.salchimail.com/tools/salchimail-local-linux-amd64) |
| Linux ARM64 | [`salchimail-local-linux-arm64`](https://docs.salchimail.com/tools/salchimail-local-linux-arm64) |
| macOS Apple silicon | [`salchimail-local-darwin-arm64`](https://docs.salchimail.com/tools/salchimail-local-darwin-arm64) |
| macOS Intel | [`salchimail-local-darwin-amd64`](https://docs.salchimail.com/tools/salchimail-local-darwin-amd64) |
| Windows x86-64 | [`salchimail-local-windows-amd64.exe`](https://docs.salchimail.com/tools/salchimail-local-windows-amd64.exe) |
| Windows ARM64 | [`salchimail-local-windows-arm64.exe`](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
```

Check the download against [`SHA256SUMS`](https://docs.salchimail.com/tools/SHA256SUMS). The binaries are not code-signed yet: a browser download on macOS or Windows shows a warning, a `curl` download does not.

## Prepare two files

**The list**: a CSV with a header row and an `email` column (or name the column with `--email-column`), or a JSONL file with one object or one address per line. Other columns are ignored.

**Your history** (optional): one row per thing you observed, in three columns.

```csv
email,kind,at
ana@discrimina.example,reply,2026-10-20T09:00:00Z
bruno@discrimina.example,hard_bounce,2026-08-01
gema@bloquea.example,delivered,2026-10-30
```

`at` is a date or an RFC 3339 timestamp. `kind` is one of:

| `kind` | When to use it | What it decides |
| --- | --- | --- |
| `reply` | The person wrote to you | `send`, for 180 days |
| `click` | A link in your email was clicked | `send`, for 180 days |
| `open` | Your email was opened | `send`, for 90 days |
| `delivered` | The server accepted your email and no bounce came back | `send`, for 90 days |
| `hard_bounce` | Permanent failure about the recipient ("user unknown", `5.1.1`) | `do_not_send`, for 365 days |
| `soft_bounce` | Temporary failure (mailbox full, `4.x.x`) | Nothing, and it cancels older good news |
| `policy_bounce` | Rejected because of the sender or the content (`5.7.x`) | Ignored: it says nothing about the mailbox |
| `auto_reply` | Out-of-office or another automatic answer | Ignored |
| `signup`, `payment`, `activation`, `fraud` | Sign-up outcomes | Used only by the [sign-up policy rehearsal](https://docs.salchimail.com/signup-rehearsal.md) |

The most recent event that has not expired wins. Your email service's activity export, your bounce list and the date of the last inbound message in your CRM are the usual sources. An [AI agent](#agents) can do this conversion for you.

## Preview what would be sent

```sh
salchimail-local clean --list list.csv --history history.csv --dry-run --budget 10
```

A dry run makes no request to the API and needs no key. It prints the plan:

```text
salchimail-local clean: 20 rows, 19 unique addresses
Resolved on this machine: 12
  with your own history: 7
  with syntax and domain lists: 2
  with DNS: 3
DRY RUN: nothing was sent. A real run would send these addresses, and only these, to POST https://api.salchimail.com/v1/batches in mailbox mode:
  Wave 1, one address per domain (3):
    carla@discrimina.example
    fede@aceptatodo.example
    hugo@bloquea.example
  Wave 2, each one only if wave 1 shows that its server tells mailboxes apart (up to 4):
    nora@discrimina.example
    pablo@discrimina.example
    rosa@aceptatodo.example
    ines@bloquea.example
  Budget: at most 10 mailbox credits; addresses beyond it are not sent.
  Your history and every other address stay on this machine.
Not checked: 7
Decisions: send 5, do_not_send 6, review 1, not_checked 7
```

The addresses go in two waves. **Wave 1** sends one address per domain. If the server answers that it accepts any recipient (`catch_all`), or does not let us check, the other addresses of that domain are not sent: the answer would be the same. **Wave 2** sends the rest only for the domains whose server tells mailboxes apart.

## Run it

```sh
export SALCHIMAIL_API_KEY=sk_live_…
salchimail-local clean --list list.csv --history history.csv --budget 10 --out results.csv
```

`--budget` is the most mailbox credits the run may spend. Without it the run stays local and sends nothing. The summary on the same data:

```text
salchimail-local clean: 20 rows, 19 unique addresses
Resolved on this machine: 12
  with your own history: 7
  with syntax and domain lists: 2
  with DNS: 3
Sent to the SalchiMail API: 5 (mailbox credits charged: 4)
Resolved without being sent, from the answer for another address of the domain: 2
Never left this machine: 14 of 19 addresses, and every row of your history.
Not checked: 0
Decisions: send 7, do_not_send 7, review 5, not_checked 0
Test-mode key: the API results are simulated.
```

And `results.csv`, with one row per row of your list:

```csv
row,email,action,source,api,reason_code,reason
1,ana@discrimina.example,send,own_history,no,own_reply,Replied to you on 2026-10-20
2,bruno@discrimina.example,do_not_send,own_history,no,own_hard_bounce,Your own email hard-bounced on 2026-08-01
3,carla@discrimina.example,send,api,sent,mailbox_exists,The mail server accepts this recipient and rejects a random one.
4,dario@aceptatodo.example,send,own_history,no,own_reply,Replied to you on 2026-09-15
5,elena@aceptatodo.example,do_not_send,own_history,no,own_hard_bounce,Your own email hard-bounced on 2026-10-01
6,fede@aceptatodo.example,review,api,sent,catch_all,The mail server also accepts a random recipient.
7,gema@bloquea.example,send,own_history,no,own_delivered,Accepted without a bounce on 2026-10-30 (does not prove it reached the inbox)
8,hugo@bloquea.example,review,api,sent,probe_blocked,The mail server refuses our probe.
9,ines@bloquea.example,review,api_domain,no,probe_blocked,"Not sent: the server did not let another address of this domain be checked (probe_blocked), so this one would not be resolved either"
10,juan@muerto.example,do_not_send,local_dns,no,domain_no_mail_host,The domain has no MX and no address record: it cannot receive mail
11,kira@muerto.example,do_not_send,local_dns,no,domain_no_mail_host,The domain has no MX and no address record: it cannot receive mail
12,luis@discrimina.example,send,own_history,no,own_reply,Replied to you on 2026-09-01
13,nora@discrimina.example,do_not_send,api,sent,mailbox_not_found,The mail server says the recipient does not exist.
14,pablo@discrimina.example,send,api,sent,mailbox_exists,The mail server accepts this recipient and rejects a random one.
15,quique@aceptatodo.example,send,own_history,no,own_click,Clicked a link in your email on 2026-10-01 (clicks can be automatic)
16,rosa@aceptatodo.example,review,api_domain,no,catch_all,"Not sent: the server accepts any recipient (seen with another address of this domain), so checking this mailbox would add nothing"
17,marta@mailinator.com,review,local_rules,no,disposable_domain,Disposable email domain
18,not-an-email,do_not_send,local_rules,no,syntax_invalid,Not a valid email address
19,carla@discrimina.example,send,api,sent,mailbox_exists,The mail server accepts this recipient and rejects a random one.
20,olga@nulo.example,do_not_send,local_dns,no,domain_null_mx,The domain declares that it accepts no mail (null MX)
```

| Column | Meaning |
| --- | --- |
| `row` | Position in your list, starting at 1. Join back by this column: a cell that a spreadsheet would run as a formula gets a leading apostrophe |
| `action` | `send`, `do_not_send`, `review` or `not_checked` |
| `source` | Where the decision comes from: `own_history`, `local_rules` (syntax and domain lists), `local_dns`, `api` (this address was checked), `api_domain` (not sent: the answer for another address of its domain applies) or `none` |
| `api` | `sent`, `no` or `pending`; in a dry run, `would_send` or `would_send_conditional` |
| `reason_code` | `own_reply`, `own_click`, `own_open`, `own_delivered`, `own_hard_bounce`, or a [reason code](https://docs.salchimail.com/verdicts.md) of the API |
| `reason` | The same in words, in English or with `--lang es` in Spanish |

How API verdicts become actions:

| Verdict | Action |
| --- | --- |
| `valid` | `send` |
| `invalid` | `do_not_send` |
| `risky`, `unknown` | `review`. Never delete these as if they were invalid |

`not_checked` means that only a mailbox check could resolve the address and none was done: no budget, budget used up, or a batch still running.

## How it decides

In this order, stopping at the first step that resolves the address:

1. **Syntax.** The same rules as the API: `syntax_invalid` → `do_not_send`.
2. **Your history.** The latest event that has not expired.
3. **Domain lists.** The disposable-domain list the API uses, built into the tool: `disposable_domain` → `review`.
4. **DNS.** A domain with a null MX, or with no MX and no address record, cannot receive mail: `do_not_send`. A lookup that fails is never taken as a dead domain.
5. **Mailbox check through the API**, in two waves and within the budget.

The rules are fixed and the same for everyone. No language model takes part in the decision.

## Budget, limits and resuming

With a budget, the tool calls the API with your key: `GET /account` for your plan's limits, `GET /usage` for your balance, `POST /batches` in `mailbox` mode, `GET /batches/{batch_id}` every 15 seconds and `GET /batches/{batch_id}/results`. They are the calls of [Clean a list in batches](https://docs.salchimail.com/batches.md).

- **Budget.** An address sent costs at most 1 mailbox credit and nothing when the verdict is `unknown` ([Credits and billing](https://docs.salchimail.com/credits.md)). The tool never sends more addresses than credits are left in the budget, and it lowers the budget to your balance. This is the balance it reads, in `credits.mailbox.remaining`:

```json
{
  "object": "usage",
  "livemode": true,
  "credits": {
    "basic": {
      "remaining": 18760,
      "reserved": 0,
      "granted": 20000,
      "resets_at": "2026-12-01T00:00:00Z"
    },
    "mailbox": {
      "remaining": 2311,
      "reserved": 1,
      "next_expiry": null
    }
  },
  "period": {
    "start": "2026-11-01T00:00:00Z",
    "end": "2026-12-01T00:00:00Z"
  },
  "usage": {
    "basic": {
      "verifications": 1302,
      "credits_charged": 1240
    },
    "mailbox": {
      "verifications": 214,
      "credits_charged": 188
    }
  },
  "feature_quotas": {
    "resets_at": "2026-12-01T00:00:00Z",
    "ci_runs": {
      "limit": 100,
      "used": 7,
      "reserved": 1,
      "remaining": 92
    },
    "sending_audits": {
      "limit": 30,
      "used": 2,
      "reserved": 0,
      "remaining": 28
    },
    "placement_tests": {
      "limit": 3,
      "used": 1,
      "reserved": 0,
      "remaining": 2
    },
    "active_monitors": {
      "limit": 1,
      "active": 0
    }
  }
}
```

- **Plan limits.** Batches are cut to your plan's `max_batch_size` and run one after another. A `429` with `Retry-After` is waited for and retried.
- **Idempotency.** Each batch is created with an [`Idempotency-Key`](https://docs.salchimail.com/idempotency.md) derived from its content. Running the same command again replays the same batch instead of paying twice.
- **Resuming.** Mailbox batches can take hours on lists concentrated on a few domains. The tool waits 30 minutes (`--wait`), then stops with exit code `3`. Run **the same command** again to collect the results. The file `.salchimail-local-state.json` remembers the batch; it holds batch ids, hashes of their contents and the run's credit allowance, never addresses in clear, and is removed when the run completes. A resumed run keeps the allowance it started with, so it collects the batch it already paid for.
- **Errors.** A `401`, a `402` or a daily limit stops the run with the API's [error code](https://docs.salchimail.com/limits-and-errors.md). What was resolved on your machine is still written.

Each result the tool reads from a batch is a row like these; `credits_charged` is what it adds up as "credits charged":

```json
{
  "object": "list",
  "data": [
    {
      "row": 1,
      "input": "Ana@Example.com",
      "duplicate": false,
      "id": "ver_8c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f",
      "object": "verification",
      "livemode": true,
      "email": "ana@example.com",
      "mode": "mailbox",
      "verdict": "valid",
      "reason_code": "mailbox_exists",
      "reason": "The mail server accepts this recipient and rejects a random one.",
      "flags": {
        "disposable": false,
        "free": false,
        "catch_all": false
      },
      "checks": [
        {
          "name": "syntax",
          "status": "ok"
        },
        {
          "name": "dns",
          "status": "mx"
        },
        {
          "name": "smtp",
          "status": "accepted"
        },
        {
          "name": "catch_all",
          "status": "missing"
        }
      ],
      "mx": [
        {
          "host": "mx1.example.com",
          "preference": 10
        }
      ],
      "smtp": {
        "mx": "mx1.example.com",
        "code": 250,
        "enhanced_code": null,
        "tls": true
      },
      "cached": false,
      "credits_charged": 1,
      "checked_at": "2026-11-17T09:50:04Z",
      "retry_at": null
    },
    {
      "row": 3,
      "input": "not-an-email",
      "duplicate": false,
      "id": "ver_1b2c3d4e5f60718293a4b5c6d7e8f9a0",
      "object": "verification",
      "livemode": true,
      "email": "not-an-email",
      "mode": "mailbox",
      "verdict": "invalid",
      "reason_code": "syntax_invalid",
      "reason": "The address is not a valid email.",
      "flags": {
        "disposable": false,
        "free": false,
        "catch_all": null
      },
      "checks": [
        {
          "name": "syntax",
          "status": "invalid"
        }
      ],
      "mx": [],
      "smtp": null,
      "cached": false,
      "credits_charged": 1,
      "checked_at": "2026-11-17T09:50:02Z",
      "retry_at": null
    }
  ],
  "has_more": true,
  "next_cursor": "eyJyb3ciOjN9"
}
```

## What it cannot tell you

- **The expiry periods are starting values.** 90, 180 and 365 days have not been calibrated against real outcomes.
- **"Accepted without a bounce" is not "reached the inbox".** And opens or clicks can come from security filters or mail privacy features, not from a person.
- **One address speaks for its domain.** If the first address of a domain gets a passing `unknown`, the others stay unchecked until you run it again.
- **Local DNS cannot tell "the domain does not exist" from "it has no records".** Both are reported as `domain_no_mail_host`.
- **No alias handling.** `ana+news@…` and `ana@…` are different addresses for the tool.
- **A list with no history gains little.** Bought or very old lists have none, and then the tool only saves you the dead and disposable domains.

## Use it from an AI agent

The slow part is turning your exports into `history.csv`: every email service names its columns differently. An agent does that well. The skill [`salchimail-local`](https://docs.salchimail.com/skills/salchimail-local/SKILL.md) teaches it where to look, how to map the events, to run `--dry-run` first and to ask you for a budget before anything is sent. See [Use from AI agents](https://docs.salchimail.com/ai-agents.md).
