# Testa il provider email

`POST /v1/email-provider:test` · autorizzazione `email-provider:write` · tutti i piani

Verifica la connessione salvata senza inviare alcun messaggio:

- `customer_smtp`: si connette al tuo server, imposta TLS, autentica ed esce.
- `customer_api`: chiama un endpoint in sola lettura del tuo provider con la chiave salvata.

La risposta è `200 OK` anche quando il controllo fallisce: `result` è `ok` oppure un codice di errore fisso. Il testo di risposta del server non viene mai restituito. Il risultato viene salvato in `last_test_at` e `last_test_result` di [get](get.md); l'`ETag` non cambia. Ogni test scrive un record di audit (`email_provider.tested`).

Un ambiente può eseguire 10 test all'ora. Il body è facoltativo; se lo invii, deve essere un oggetto JSON vuoto.

## Risposta

| Campo | Tipo | Descrizione |
|---|---|---|
| `result` | string | `ok` oppure un codice di errore (sotto). |
| `tested_at` | string | Momento del test. |
| `version` | integer | La versione della configurazione che è stata testata. |

```json
{
  "result": "smtp_auth_failed",
  "tested_at": "2026-10-19T09:30:00Z",
  "version": 4
}
```

Risultati comuni:

| Risultato | Significato |
|---|---|
| `ok` | Connesso e autenticato. |
| `smtp_auth_failed` | Il server SMTP ha rifiutato il nome utente o la password. |
| `smtp_auth_unsupported` | Il server non offre alcun meccanismo AUTH supportato. |
| `smtp_tls_required` | Il server sulla porta 587 non offre STARTTLS. |
| `smtp_tls_invalid` | Il certificato del server non è valido per il nome host. |
| `smtp_temporary`, `smtp_rejected` | Il server ha risposto con un errore temporaneo o permanente. |
| `esp_auth_failed` | Il provider ha rifiutato la chiave. |
| `esp_access_denied` | Il provider ha rifiutato la chiave oppure la chiave non ha accesso in lettura all'endpoint controllato (per esempio `ses:GetAccount`, o una chiave di invio di dominio Mailgun). L'invio potrebbe comunque funzionare. |
| `esp_rate_limited`, `esp_temporary`, `esp_rejected` | Il provider ha applicato un limite di frequenza, non è disponibile temporaneamente oppure ha rifiutato la richiesta. |
| `egress_dns_failed`, `egress_dns_private`, `egress_ssrf_blocked`, `egress_connect_failed`, `egress_timeout`, `egress_tls_invalid` | L'host non si risolve, si risolve in un indirizzo privato, è bloccato, non è stato raggiunto in tempo oppure (provider API) ha presentato un certificato non valido. |
| `delivery_credentials_invalid` | La credenziale salvata non può essere usata; salvala di nuovo. |
| `delivery_mode_unavailable` | La consegna in uscita non è abilitata in questo deployment. |

## Errori

| HTTP | code | Quando |
|---|---|---|
| 400 | `unknown_field` | Il body non è un oggetto JSON vuoto. |
| 409 | `conflict` | La modalità non ha alcuna connessione da testare (`platform_default`, `customer_webhook`, `platform_managed_domain`; testa un endpoint webhook con [Testa un endpoint webhook](../webhook-endpoints/test.md); controlla un dominio mittente con [verify](../email-sender-domains/verify.md)), oppure la configurazione è cambiata durante il test. |
| 429 | `rate_limited` | È stato raggiunto il limite orario di test o il limite di frequenza dell'API; riprova dopo il periodo indicato in `Retry-After`. |
| 401 | `unauthenticated` | La credenziale manca, non è valida o è stata revocata. |
| 403 | `insufficient_permissions` | La credenziale non ha l'autorizzazione richiesta. |
| 503 | `service_unavailable` | Una dipendenza non è disponibile temporaneamente; riprova dopo il periodo indicato in `Retry-After`. |

## Esempio

```bash
curl -X POST https://api.eu.keenauth.com/v1/email-provider:test \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY"
```

CLI: `keenauth email-provider test`