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:

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

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

curl
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

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

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

View this page as Markdown