# Inicio rápido

De cero a tu primera dirección verificada en menos de cinco minutos. Necesitas una cuenta de SalchiMail y una terminal.

## 1. Crea una clave de API

Entra en el panel, en [app.salchimail.com](https://app.salchimail.com), y crea una clave de API. La clave se muestra **una sola vez**: cópiala ahora.

- Las claves `sk_live_…` hacen verificaciones reales y consumen créditos.
- Las claves `sk_test_…` devuelven resultados simulados y nunca consumen créditos. Consulta [Entorno de pruebas](https://docs.salchimail.com/es/entorno-de-pruebas.md).

Guarda la clave en una variable de entorno. Es un secreto: úsala desde tu servidor, nunca desde un navegador ni una aplicación móvil.

```bash
export SALCHIMAIL_API_KEY="sk_live_tu_clave"
```

## 2. Verifica una dirección

Cambia `ana@example.com` por una dirección que conozcas y lanza la petición. Aquí `mode` es `mailbox`, así que se pregunta al servidor de correo si el buzón existe. No se envía ningún email.

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

La comprobación de buzón habla con el servidor de correo del destinatario y puede tardar hasta 30 segundos: dale a tu cliente HTTP un tiempo de espera superior.

## 3. Lee el resultado

La respuesta es un objeto de verificación:

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

Empieza por `verdict` y lee después `reason_code` para saber el porqué:

| `verdict` | Qué significa | Qué hacer |
| --- | --- | --- |
| `valid` | El servidor acepta a este destinatario y rechaza uno aleatorio | Envía |
| `invalid` | Sintaxis incorrecta, un dominio que no puede recibir correo o un «no existe ese destinatario» claro | No envíes |
| `risky` | Servidor que lo acepta todo, dominio desechable, buzón lleno o desactivado, y casos parecidos | Decide según `reason_code` |
| `unknown` | La comprobación no pudo terminar o no se hizo | **No lo trates como `invalid`**. Reintenta después de `retry_at` cuando venga informado |

`credits_charged` te dice cuánto ha costado la llamada. En modo `mailbox`, un resultado `unknown` es gratis. La lista completa está en [Veredictos y reason codes](https://docs.salchimail.com/es/veredictos.md).

## 4. Elige el modo para tu caso

- **Un formulario de registro**: usa `"mode": "basic"`. Comprueba sintaxis, listas de dominios y DNS en bastante menos de un segundo. Consulta [Verificación en el registro](https://docs.salchimail.com/es/verificacion-en-registro.md).
- **Una lista**: envíala como lote en lugar de hacer una petición por dirección. Consulta [Limpieza de listas por lotes](https://docs.salchimail.com/es/lotes.md).

## Siguientes pasos

- [Autenticación](https://docs.salchimail.com/es/autenticacion.md): tipos de clave, rotación y qué significa un `401`.
- [Idempotencia](https://docs.salchimail.com/es/idempotencia.md): reintenta un `POST` sin riesgo.
- [Límites y errores](https://docs.salchimail.com/es/limites-y-errores.md): límites de peticiones y todos los códigos de error.
- [Referencia de la API](https://docs.salchimail.com/reference.md): todos los endpoints, campos y ejemplos.
