# Documentación de SalchiMail

> SalchiMail es una API de verificación de emails que nunca envía correo: la comprobación de buzón se detiene en `RCPT TO`. Verifica una dirección por petición o limpia listas por lotes. Cada resultado trae un veredicto (`valid`, `invalid`, `risky`, `unknown`) y un `reason_code` estable.

- URL base: `https://api.salchimail.com/v1`. JSON sobre HTTPS.
- Autenticación: `Authorization: Bearer sk_live_…` (o `sk_test_…` en modo de pruebas). Las claves son secretos de servidor.
- Dos modos: `basic` (sintaxis, listas de dominios, DNS) y `mailbox` (añade el sondeo SMTP `RCPT TO`). Cada uno tiene su propio saldo de créditos.
- Nunca trates `unknown` como `invalid`.

## Guías

- [Inicio rápido · Verifica tu primer email en menos de 5 minutos](https://docs.salchimail.com/es/inicio-rapido.md): Crea una clave de API, verifica tu primera dirección de email con curl, JavaScript, Python, PHP o Go y aprende a leer el veredicto. En menos de cinco minutos.
- [Autenticación · Claves de API](https://docs.salchimail.com/es/autenticacion.md): Cómo funcionan las claves de API de SalchiMail: claves reales y de pruebas, cabecera Bearer, rotación y significado de cada error 401 y 403.
- [Entorno de pruebas · Claves sk_test_](https://docs.salchimail.com/es/entorno-de-pruebas.md): Usa claves sk_test_ para construir y probar tu integración con SalchiMail con veredictos predecibles, sin verificaciones reales y sin consumir créditos.
- [Verificar emails en el registro · Patrón recomendado y tiempos](https://docs.salchimail.com/es/verificacion-en-registro.md): Patrón recomendado para verificar emails en un formulario de registro con SalchiMail: qué modo usar, tiempos de espera y qué hacer con cada veredicto.
- [Limpiar una lista de emails por lotes · JSON y CSV](https://docs.salchimail.com/es/lotes.md): Verifica una lista entera de emails con la API de lotes de SalchiMail: sube JSON o CSV, sigue el progreso y descarga los resultados. Plazos y límites.
- [Veredictos y reason codes · Qué significa cada uno y qué hacer](https://docs.salchimail.com/es/veredictos.md): Los cuatro veredictos de SalchiMail (valid, invalid, risky, unknown) y todos los reason_code, con su significado, si se cobran y qué hacer con la dirección.
- [Webhooks · Eventos y verificación de firma](https://docs.salchimail.com/es/webhooks.md): Recibe eventos de SalchiMail como batch.completed y credits.low. Verifica la cabecera HMAC SalchiMail-Signature con ejemplos, reintentos y deduplicación.
- [Idempotencia · Reintenta peticiones POST sin riesgo](https://docs.salchimail.com/es/idempotencia.md): Usa la cabecera Idempotency-Key para reintentar peticiones POST a SalchiMail sin verificar ni cobrar dos veces. Duración de las claves y conflictos 409.
- [Créditos y facturación · Qué cuesta cada verificación](https://docs.salchimail.com/es/creditos.md): Cómo funcionan los créditos de SalchiMail: saldos basic y mailbox, qué se cobra y qué es gratis, reservas en lotes y qué pasa al llegar a cero.
- [Límites y errores · Límites de peticiones, códigos de error y reintentos](https://docs.salchimail.com/es/limites-y-errores.md): Límites de peticiones y de tamaño de la API de SalchiMail, formato único de error, todos los códigos de error y qué peticiones reintentar.
- [Usar SalchiMail desde agentes de IA · llms.txt, Markdown, OpenAPI y MCP](https://docs.salchimail.com/es/agentes-ia.md): Cómo usan la API de SalchiMail los agentes de IA: llms.txt, versión Markdown de cada página, contrato OpenAPI, servidor MCP y skill.

## Referencia de la API

- [Referencia de la API en Markdown (en inglés)](https://docs.salchimail.com/reference.md): Todas las operaciones, parámetros, esquemas y ejemplos del contrato.
- [OpenAPI 3.1 (JSON)](https://docs.salchimail.com/openapi.json)
- [OpenAPI 3.1 (YAML)](https://docs.salchimail.com/openapi.yaml)

## Opcional

- [Changelog · API de SalchiMail](https://docs.salchimail.com/es/changelog.md): Cambios de la API de SalchiMail y cómo se versiona. Qué puede cambiar sin aviso dentro de v1 y qué exigiría una versión nueva.
- [Todo en un solo fichero](https://docs.salchimail.com/es/llms-full.txt)
- [Documentation in English](https://docs.salchimail.com/llms.txt)
