# Documentación de la API de SalchiMail

Verifica direcciones de email sin enviarles ni un solo mensaje. Comprueba una dirección en una petición o limpia una lista entera en un lote.

**curl**

```bash
curl https://api.salchimail.com/v1/verify \
  -H "Authorization: Bearer $SALCHIMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "ana@example.com", "mode": "mailbox"}'
```

**JavaScript / TypeScript**

```js
const response = await fetch("https://api.salchimail.com/v1/verify", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SALCHIMAIL_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ email: "ana@example.com", mode: "mailbox" }),
});
const result = await response.json();

if (!response.ok) {
  throw new Error(`${result.error.code}: ${result.error.message}`);
}
console.log(result.verdict, result.reason_code);
```

**Python**

```python
import json
import os
import urllib.error
import urllib.request

request = urllib.request.Request(
    "https://api.salchimail.com/v1/verify",
    data=json.dumps({"email": "ana@example.com", "mode": "mailbox"}).encode(),
    headers={
        "Authorization": f"Bearer {os.environ['SALCHIMAIL_API_KEY']}",
        "Content-Type": "application/json",
    },
)
try:
    with urllib.request.urlopen(request, timeout=40) as response:
        result = json.load(response)
except urllib.error.HTTPError as error:
    problem = json.load(error)["error"]
    raise SystemExit(f"{problem['code']}: {problem['message']}")

print(result["verdict"], result["reason_code"])
```

**PHP**

```php
<?php
$ch = curl_init("https://api.salchimail.com/v1/verify");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 40,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("SALCHIMAIL_API_KEY"),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode(["email" => "ana@example.com", "mode" => "mailbox"]),
]);
$body = curl_exec($ch);
if ($body === false) {
    fwrite(STDERR, "Request failed: " . curl_error($ch) . "\n");
    exit(1);
}
$result = json_decode($body, true);

if (curl_getinfo($ch, CURLINFO_HTTP_CODE) !== 200) {
    fwrite(STDERR, "{$result['error']['code']}: {$result['error']['message']}\n");
    exit(1);
}
echo "{$result['verdict']} {$result['reason_code']}\n";
```

**Go**

```go
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"log"
	"net/http"
	"os"
	"time"
)

type verification struct {
	Verdict    string `json:"verdict"`
	ReasonCode string `json:"reason_code"`
	Error      *struct {
		Code    string `json:"code"`
		Message string `json:"message"`
	} `json:"error"`
}

func main() {
	payload, _ := json.Marshal(map[string]string{"email": "ana@example.com", "mode": "mailbox"})
	req, _ := http.NewRequest("POST", "https://api.salchimail.com/v1/verify", bytes.NewReader(payload))
	req.Header.Set("Authorization", "Bearer "+os.Getenv("SALCHIMAIL_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	client := &http.Client{Timeout: 40 * time.Second}
	res, err := client.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer res.Body.Close()

	var result verification
	if err := json.NewDecoder(res.Body).Decode(&result); err != nil {
		log.Fatal(err)
	}
	if result.Error != nil {
		log.Fatalf("%s: %s", result.Error.Code, result.Error.Message)
	}
	fmt.Println(result.Verdict, result.ReasonCode)
}
```

Cada resultado trae un **veredicto** (`valid`, `invalid`, `risky` o `unknown`), un `reason_code` estable que explica el porqué y `credits_charged`, para que siempre sepas cuánto ha costado la llamada.

| Lo básico | |
| --- | --- |
| URL base | `https://api.salchimail.com/v1` |
| Autenticación | `Authorization: Bearer sk_live_…` ([detalles](https://docs.salchimail.com/es/autenticacion.md)) |
| Formato | JSON sobre HTTPS. Todos los errores tienen la misma forma ([detalles](https://docs.salchimail.com/es/limites-y-errores.md)) |
| Contrato | OpenAPI 3.1: [`openapi.yaml`](https://docs.salchimail.com/openapi.yaml) · [`openapi.json`](https://docs.salchimail.com/openapi.json) |

## Dos formas de verificar

| `mode` | Qué comprueba | Uso habitual |
| --- | --- | --- |
| `basic` | Sintaxis, listas de dominios desechables y de correo gratuito, registros DNS y MX | Formularios de registro: responde en bastante menos de un segundo |
| `mailbox` | Todo lo de `basic`, más un sondeo SMTP `RCPT TO` y un control de catch-all | Limpiar una lista antes de una campaña |

La comprobación de buzón se detiene en `RCPT TO` y nunca emite `DATA`: jamás se envía un mensaje a la dirección. Cada modo usa su propio [saldo de créditos](https://docs.salchimail.com/es/creditos.md).

## Guías

- [Inicio rápido](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](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](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.
- [Verificación en el registro](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.
- [Limpieza de listas por lotes](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](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](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](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](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](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.
- [Uso desde agentes de IA](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](https://docs.salchimail.com/reference.md): Referencia completa de la API v1 de SalchiMail, generada desde el contrato OpenAPI 3.1. Verificación, lotes, uso, cuenta y webhooks, con esquemas y ejemplos.
- [Changelog](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.

## Para agentes de IA

Cada página tiene una versión en Markdown (añade `.md` a su URL) y el sitio publica [`llms.txt`](https://docs.salchimail.com/es/llms.txt) y [`llms-full.txt`](https://docs.salchimail.com/es/llms-full.txt). Consulta [Uso desde agentes de IA](https://docs.salchimail.com/es/agentes-ia.md).
