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 |
| Linux ARM64 | salchimail-local-linux-arm64 |
| macOS Apple silicon | salchimail-local-darwin-arm64 |
| macOS Intel | salchimail-local-darwin-amd64 |
| Windows x86-64 | salchimail-local-windows-amd64.exe |
| Windows ARM64 | salchimail-local-windows-arm64.exe |
curl -fsSLo salchimail-local https://docs.salchimail.com/tools/salchimail-local-linux-amd64
chmod +x salchimail-local
./salchimail-local versionCheck the download against 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.
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-30at 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 |
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 can do this conversion for you.
Preview what would be sent
salchimail-local clean --list list.csv --history history.csv --dry-run --budget 10A dry run makes no request to the API and needs no key. It prints the plan:
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 7The 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
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:
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:
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 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:
- Syntax. The same rules as the API:
syntax_invalid→do_not_send. - Your history. The latest event that has not expired.
- Domain lists. The disposable-domain list the API uses, built into the tool:
disposable_domain→review. - 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. - 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.
- Budget. An address sent costs at most 1 mailbox credit and nothing when the verdict is
unknown(Credits and billing). 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, incredits.mailbox.remaining:
{
"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_sizeand run one after another. A429withRetry-Afteris waited for and retried. - Idempotency. Each batch is created with an
Idempotency-Keyderived 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 code3. Run the same command again to collect the results. The file.salchimail-local-state.jsonremembers 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, a402or a daily limit stops the run with the API's error code. 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":
{
"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@…andana@…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 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.