# Verificación local primero

La mejor prueba de que un buzón existe es que su dueño te escribió el mes pasado, o que tu último correo no rebotó. Esa prueba está en tus sistemas, no en los nuestros. `salchimail-local` es un programa pequeño que se ejecuta **en tu máquina**, usa lo que ya sabes y solo pregunta a la API por las direcciones en las que comprobar el buzón puede decirte algo nuevo.

Nunca envía correo, y tu historial nunca se sube a ningún sitio.

Los ejemplos de esta página son la salida real de la herramienta sobre **datos de prueba sintéticos**: personas inventadas en dominios `.example`, con un DNS y una API simulados. Enseñan cómo funciona, no cuánto resolverá en tu lista. Eso depende de cuánto historial reciente tengas.

## Qué sale de tu máquina

| Dato | A dónde va |
| --- | --- |
| Tu fichero de historial (entregas, rebotes, respuestas, desenlace de las altas) | A ningún sitio. Se lee en tu máquina |
| Direcciones resueltas con tu historial, con la sintaxis o con la lista de dominios desechables | A ningún sitio |
| Nombres de dominio de las direcciones que quedan | A tu propio resolutor DNS, para ver si el dominio puede recibir correo |
| Direcciones que solo una comprobación de buzón puede resolver | A la API de SalchiMail, y solo si fijas un presupuesto. `--dry-run` las lista antes |

La herramienta no tiene telemetría y no contacta con nada más. Para las direcciones que sí envía, SalchiMail actúa como tu encargado del tratamiento, igual que en cualquier otra llamada a la API.

## Instalación

Un fichero, sin intérprete y sin dependencias. Descarga el de tu sistema:

| Sistema | Fichero |
| --- | --- |
| 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 con Apple silicon | [`salchimail-local-darwin-arm64`](https://docs.salchimail.com/tools/salchimail-local-darwin-arm64) |
| macOS con 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
```

Comprueba la descarga con [`SHA256SUMS`](https://docs.salchimail.com/tools/SHA256SUMS). Los binarios todavía no llevan firma de código: al descargarlos con el navegador en macOS o Windows aparece un aviso; con `curl`, no.

## Prepara dos ficheros

**La lista**: un CSV con fila de cabecera y una columna `email` (o indica la columna con `--email-column`), o un fichero JSONL con un objeto o una dirección por línea. Las demás columnas se ignoran.

**Tu historial** (opcional): una fila por cada cosa que has observado, en tres columnas.

```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` es una fecha o una marca de tiempo RFC 3339. `kind` es uno de estos valores:

| `kind` | Cuándo usarlo | Qué decide |
| --- | --- | --- |
| `reply` | La persona te escribió | `send`, durante 180 días |
| `click` | Alguien hizo clic en un enlace de tu correo | `send`, durante 180 días |
| `open` | Tu correo se abrió | `send`, durante 90 días |
| `delivered` | El servidor aceptó tu correo y no volvió ningún rebote | `send`, durante 90 días |
| `hard_bounce` | Fallo permanente sobre el destinatario («user unknown», `5.1.1`) | `do_not_send`, durante 365 días |
| `soft_bounce` | Fallo temporal (buzón lleno, `4.x.x`) | Nada, y anula las buenas noticias anteriores |
| `policy_bounce` | Rechazo por el remitente o por el contenido (`5.7.x`) | Se ignora: no dice nada sobre el buzón |
| `auto_reply` | Fuera de la oficina u otra respuesta automática | Se ignora |
| `signup`, `payment`, `activation`, `fraud` | Desenlace de las altas | Solo los usa el [ensayo de política de registro](https://docs.salchimail.com/es/ensayo-politica-registro.md) |

Gana el evento más reciente que no haya caducado. Las fuentes habituales son la exportación de actividad de tu servicio de envío, tu lista de rebotes y la fecha del último mensaje recibido en tu CRM. Un [agente de IA](#agents) puede hacer esta conversión por ti.

## Mira antes qué se enviaría

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

Un ensayo con `--dry-run` no hace ninguna petición a la API y no necesita clave. Imprime el plan:

```text
salchimail-local clean: 20 filas, 19 direcciones únicas
Resueltas en esta máquina: 12
  con tu propio historial: 7
  con sintaxis y listas de dominios: 2
  con DNS: 3
ENSAYO (--dry-run): no se ha enviado nada. Una ejecución real enviaría estas direcciones, y solo estas, a POST https://api.salchimail.com/v1/batches en modo mailbox:
  Ola 1, una dirección por dominio (3):
    carla@discrimina.example
    fede@aceptatodo.example
    hugo@bloquea.example
  Ola 2, cada una solo si la ola 1 muestra que su servidor distingue buzones (hasta 4):
    nora@discrimina.example
    pablo@discrimina.example
    rosa@aceptatodo.example
    ines@bloquea.example
  Presupuesto: como máximo 10 créditos de buzón; las direcciones que lo superen no se envían.
  Tu historial y todas las demás direcciones se quedan en esta máquina.
Sin comprobar: 7
Decisiones: send 5, do_not_send 6, review 1, not_checked 7
```

Las direcciones salen en dos olas. La **ola 1** envía una dirección por dominio. Si el servidor responde que acepta cualquier destinatario (`catch_all`), o no deja comprobar, las demás direcciones de ese dominio no se envían: la respuesta sería la misma. La **ola 2** envía el resto solo en los dominios cuyo servidor distingue buzones.

## Ejecútalo

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

`--budget` es el máximo de créditos de buzón que puede gastar la ejecución. Sin él, todo se queda en local y no se envía nada. El resumen con los mismos datos:

```text
salchimail-local clean: 20 filas, 19 direcciones únicas
Resueltas en esta máquina: 12
  con tu propio historial: 7
  con sintaxis y listas de dominios: 2
  con DNS: 3
Enviadas a la API de SalchiMail: 5 (créditos de buzón cobrados: 4)
Resueltas sin enviarlas, con la respuesta a otra dirección del dominio: 2
Nunca salieron de esta máquina: 14 de 19 direcciones, y todas las filas de tu historial.
Sin comprobar: 0
Decisiones: send 7, do_not_send 7, review 5, not_checked 0
Clave de pruebas: los resultados de la API son simulados.
```

Y `results.csv`, con una fila por cada fila de tu lista (aquí con los motivos en inglés, el idioma por defecto):

```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)
```

| Columna | Significado |
| --- | --- |
| `row` | Posición en tu lista, empezando en 1. Cruza los resultados por esta columna: una celda que una hoja de cálculo ejecutaría como fórmula lleva un apóstrofo delante |
| `action` | `send`, `do_not_send`, `review` o `not_checked` |
| `source` | De dónde sale la decisión: `own_history`, `local_rules` (sintaxis y listas de dominios), `local_dns`, `api` (esta dirección se comprobó), `api_domain` (no se envió: vale la respuesta a otra dirección de su dominio) o `none` |
| `api` | `sent`, `no` o `pending`; en un ensayo, `would_send` o `would_send_conditional` |
| `reason_code` | `own_reply`, `own_click`, `own_open`, `own_delivered`, `own_hard_bounce`, o un [código de motivo](https://docs.salchimail.com/es/veredictos.md) de la API |
| `reason` | Lo mismo con palabras, en inglés o, con `--lang es`, en español |

Cómo se convierten en acciones los veredictos de la API:

| Veredicto | Acción |
| --- | --- |
| `valid` | `send` |
| `invalid` | `do_not_send` |
| `risky`, `unknown` | `review`. Nunca las borres como si fueran inválidas |

`not_checked` significa que solo una comprobación de buzón podía resolver la dirección y no se hizo: sin presupuesto, presupuesto agotado o un lote todavía en curso.

## Cómo decide

En este orden, y se detiene en el primer paso que resuelve la dirección:

1. **Sintaxis.** Las mismas reglas que la API: `syntax_invalid` → `do_not_send`.
2. **Tu historial.** El último evento que no haya caducado.
3. **Listas de dominios.** La lista de desechables que usa la API, incluida en la herramienta: `disposable_domain` → `review`.
4. **DNS.** Un dominio con MX nulo, o sin MX ni registro de dirección, no puede recibir correo: `do_not_send`. Una consulta que falla nunca se toma por un dominio muerto.
5. **Comprobación de buzón con la API**, en dos olas y dentro del presupuesto.

Las reglas son fijas e iguales para todos. Ningún modelo de lenguaje participa en la decisión.

## Presupuesto, límites y reanudación

Con presupuesto, la herramienta llama a la API con tu clave: `GET /account` para los límites de tu plan, `GET /usage` para tu saldo, `POST /batches` en modo `mailbox`, `GET /batches/{batch_id}` cada 15 segundos y `GET /batches/{batch_id}/results`. Son las llamadas de [Limpieza de listas por lotes](https://docs.salchimail.com/es/lotes.md).

- **Presupuesto.** Una dirección enviada cuesta como mucho 1 crédito de buzón, y nada si el veredicto es `unknown` ([Créditos y facturación](https://docs.salchimail.com/es/creditos.md)). La herramienta nunca envía más direcciones que créditos queden en el presupuesto, y rebaja el presupuesto a tu saldo. Este es el saldo que lee, en `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
    }
  }
}
```

- **Límites del plan.** Los lotes se cortan al `max_batch_size` de tu plan y se procesan uno tras otro. Ante un `429` con `Retry-After`, espera y reintenta.
- **Idempotencia.** Cada lote se crea con una [`Idempotency-Key`](https://docs.salchimail.com/es/idempotencia.md) derivada de su contenido. Repetir la misma orden reproduce el mismo lote en lugar de pagar dos veces.
- **Reanudación.** Los lotes de buzón pueden tardar horas en listas concentradas en pocos dominios. La herramienta espera 30 minutos (`--wait`) y luego se detiene con el código de salida `3`. Ejecuta **la misma orden** otra vez para recoger los resultados. El fichero `.salchimail-local-state.json` recuerda el lote; guarda identificadores de lote, hashes de su contenido y el presupuesto de la ejecución, nunca direcciones en claro, y se borra cuando la ejecución termina. Al reanudar se mantiene el presupuesto con el que empezó, así que recoge el lote que ya pagó.
- **Errores.** Un `401`, un `402` o un límite diario detienen la ejecución con el [código de error](https://docs.salchimail.com/es/limites-y-errores.md) de la API. Lo resuelto en tu máquina se escribe igualmente.

Cada resultado que la herramienta lee de un lote es una fila como estas; `credits_charged` es lo que suma como «créditos cobrados»:

```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"
}
```

## Lo que no puede decirte

- **Las caducidades son valores de partida.** 90, 180 y 365 días no se han calibrado con desenlaces reales.
- **«Aceptado sin rebote» no es «llegó a la bandeja».** Y las aperturas o los clics pueden venir de filtros de seguridad o de funciones de privacidad del correo, no de una persona.
- **Una dirección habla por su dominio.** Si la primera dirección de un dominio recibe un `unknown` pasajero, las demás quedan sin comprobar hasta la siguiente ejecución.
- **El DNS local no distingue «el dominio no existe» de «no tiene registros».** Ambos casos salen como `domain_no_mail_host`.
- **No trata los alias.** `ana+news@…` y `ana@…` son direcciones distintas para la herramienta.
- **Una lista sin historial gana poco.** Las listas compradas o muy antiguas no lo tienen, y entonces la herramienta solo te ahorra los dominios muertos y los desechables.

## Úsalo desde un agente de IA

La parte lenta es convertir tus exportaciones en `history.csv`: cada servicio de envío llama a sus columnas de una manera. Un agente lo hace bien. La skill [`salchimail-local`](https://docs.salchimail.com/skills/salchimail-local/SKILL.md) (en inglés) le enseña dónde buscar, cómo traducir los eventos, a ejecutar primero `--dry-run` y a pedirte un presupuesto antes de enviar nada. Consulta [Uso desde agentes de IA](https://docs.salchimail.com/es/agentes-ia.md).
