# Chiavi API

> Crea chiavi API con accesso completo e di solo invio, limitale a un dominio, usale per SMTP e ruotale senza interruzioni.

Le chiavi API autenticano le tue richieste all’API REST, le connessioni SMTP e le sessioni con chiave API sul server MCP. Questa pagina spiega i due permessi delle chiavi, come creare e gestire le chiavi e come conservarle e ruotarle in modo sicuro.

## Come funzionano le chiavi API

- Ogni chiave appartiene a un workspace. Tutto ciò che fai con la chiave avviene in quel workspace.
- Le nuove chiavi iniziano con `secret_` seguito da 32 lettere e cifre, ad esempio `secret_••••••••`. Le chiavi create prima dell’introduzione del prefisso continuano a funzionare.
- Emailit mostra la chiave completa una sola volta, quando la crei o la rigeneri. Copiala in quel momento: non potrai più visualizzarla.
- Invii la chiave come token Bearer: `Authorization: Bearer secret_…`. Per SMTP, la chiave è la password.

## Permessi

Ogni chiave ha uno di due permessi. Scegli il permesso quando crei la chiave.

| | Full Access (`full`) | Sending Only (`sending`) |
| --- | --- | --- |
| Inviare email (`POST /emails`) | Sì | Sì |
| Riprogrammare, annullare, ritentare e inoltrare un’email | Sì | Sì |
| SMTP relay | Sì | Sì |
| Leggere le email (elenco, recupero, MIME grezzo, corpo, metadati, allegati) | Sì | No |
| Domini, template, contatti, liste, soppressioni, webhook, eventi, campagne, automazioni, verifica e chiavi API | Sì | No |
| Strumenti MCP | Tutti gli strumenti | `send-email`, `update-email`, `cancel-email`, `retry-email`, `forward-email` e `get-current-workspace` |
| Può essere limitata a un dominio di invio | No | Sì |

Una chiave di solo invio che chiama qualsiasi altro endpoint riceve `403` con un messaggio come `Permission denied: read`. Usa le chiavi con accesso completo per i processi di back office che gestiscono le risorse, e le chiavi di solo invio per tutto ciò che deve solo inviare.

### Limita una chiave a un dominio

Quando crei una chiave di solo invio puoi scegliere un dominio di invio verificato. La chiave potrà quindi inviare solo da indirizzi di quel dominio:

- Via API, l’invio da un altro dominio restituisce `403` con `"error": "Domain not authorized"`.
- Via SMTP, il messaggio viene rifiutato dopo `DATA` con `530 API key is restricted to sending domain: …`.

Le chiavi limitate sono adatte come credenziali per singola app o per singolo cliente, e per le chiavi che devi consegnare a software di terzi, come il plugin di un CMS.

## Prima di iniziare

- Per creare, modificare, rigenerare o eliminare le chiavi ti serve il ruolo **Admin** nel workspace. I membri con ruolo Member vedono l’elenco delle chiavi ma non possono modificarlo. Vedi [Membri e ruoli](/it/docs/workspaces/members-and-roles/).
- Per inviare con una chiave, ti serve almeno un [dominio di invio verificato](/it/docs/domains/add-a-domain/).

## Crea una chiave API

**Pannello**

  1. **Apri le chiavi API.** Vai a **Email API → API Keys** e seleziona **Add API key**.

  2. **Dai un nome alla chiave.** Compila il campo **Name** con un nome che dica dove viene usata la chiave, ad esempio `production-web` o `wordpress-blog`. I nomi devono essere univoci nel workspace.

  3. **Scegli un permesso.** In **Scope**, scegli **Full Access** o **Sending Only**.

  4. **Limita il dominio (facoltativo).** Per una chiave di solo invio, scegli un dominio di invio in **Domain**, oppure lascia il campo vuoto per consentire tutti i domini verificati.

  5. **Crea e copia la chiave.** Seleziona **Create**. Copia la chiave dalla finestra e salvala nel tuo gestore di secret prima di chiuderla. Emailit mostra la chiave una sola volta.

**API**

  Chiama [Crea una chiave API](/it/docs/api-reference/api-keys/create/) con una chiave con accesso completo. Il valore predefinito di `scope` è `full`; `sending_domain_id` vale solo per le chiavi di solo invio.

```bash
curl https://api.emailit.com/v2/api-keys \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-web",
    "scope": "sending",
    "sending_domain_id": "dom_3xQ7mLp2RkT9vB4nHs8YcWd1Ze6"
  }'
```

  La risposta `201` è l’unica che include `key`:

```json
{
  "object": "api_key",
  "id": "key_4F2kN8sQwE1rT6yU3iO9pA7sD5f",
  "name": "production-web",
  "scope": "sending",
  "sending_domain_id": "dom_3xQ7mLp2RkT9vB4nHs8YcWd1Ze6",
  "last_used_at": null,
  "created_at": "2026-10-01T09:30:00.000Z",
  "updated_at": "2026-10-01T09:30:00.000Z",
  "key": "secret_••••••••••••••••••••••••••••••••"
}
```

  Un nome già in uso restituisce `409`.

## Usa la chiave

Passa la chiave nell’header `Authorization` di ogni richiesta API:

```bash
curl https://api.emailit.com/v2/emails \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <hello@acme.com>",
    "to": "ada@example.com",
    "subject": "Your order has shipped",
    "text": "Your order #1042 is on its way."
  }'
```

Per inviare via SMTP, usa la chiave come password:

| Impostazione | Valore |
| --- | --- |
| Host | `smtp.emailit.com` |
| Porta | `587` (STARTTLS, consigliata), `465` (TLS), `2525` o `2587` (STARTTLS) |
| Nome utente | `emailit` |
| Password | La tua chiave API |

Per tutte le opzioni, vedi [Impostazioni SMTP](/it/docs/smtp/settings/).

## Gestisci le chiavi

Apri una chiave da **Email API → API Keys** per vederne il permesso, il dominio, la data **Created** e l’orario **Last used**, oltre alle impostazioni SMTP da usare con la chiave.

| Azione | Cosa succede | API |
| --- | --- | --- |
| **Edit** | Rinomina la chiave. Viene salvato solo il nome; per cambiare il permesso o la limitazione al dominio, crea una nuova chiave e ruota su quella. | [Aggiorna una chiave API](/it/docs/api-reference/api-keys/update/) |
| **Regenerate** | Genera un nuovo secret per la stessa chiave e lo mostra una sola volta. Il vecchio secret smette subito di funzionare. La chiave mantiene ID, nome, permesso e dominio, e **Last used** viene azzerato. | [Rigenera una chiave API](/it/docs/api-reference/api-keys/regenerate/) |
| **Delete** | La chiave smette subito di funzionare e scompare dall’elenco. Questa operazione non si può annullare. | [Elimina una chiave API](/it/docs/api-reference/api-keys/delete/) |

**Last used** si aggiorna ogni volta che la chiave autentica una richiesta API o un accesso SMTP. Una chiave mai usata mostra **Never**. Nell’API, gli endpoint che accettano l’ID di una chiave accettano anche il suo nome.

## Conserva le chiavi in modo sicuro

- **Tieni le chiavi sul server.** Non inserire mai una chiave nel JavaScript del browser, in un’app mobile, in un repository pubblico o in un ticket di assistenza. Chiunque abbia la chiave può inviare email a tuo nome e consumare i tuoi crediti.
- **Usa variabili d’ambiente o un gestore di secret.** Carica la chiave in fase di esecuzione, ad esempio da `EMAILIT_API_KEY`. Aggiungi i file `.env` a `.gitignore`.
- **Dai a ogni app e a ogni ambiente la propria chiave.** Chiavi separate per produzione, staging e ogni strumento di terzi permettono di vedere facilmente chi ha inviato cosa e di revocarne una senza toccare le altre.
- **Usa il permesso più ristretto.** Se un’app invia solo email, dalle una chiave di solo invio, limitata al suo dominio quando possibile.
- **Tieni d’occhio l’utilizzo.** **Email API → Logs** elenca le richieste API e SMTP per chiave, e puoi filtrare **Email API → Emails** per chiave API. Vedi [Log delle richieste](/it/docs/logs/request-logs/).
- **Agisci subito in caso di fuga.** Se una chiave viene esposta, rigenerala o eliminala immediatamente, poi controlla i log per individuare invii inattesi.

## Ruota una chiave senza interruzioni

Rigenerare una chiave disattiva subito il vecchio secret, quindi fallo solo quando una chiave è compromessa. Per una rotazione pianificata, usa la vecchia e la nuova chiave in parallelo:

1. **Crea una nuova chiave.** Aggiungi una chiave con lo stesso permesso e la stessa limitazione al dominio di quella che sostituisci. Dalle un nome che indichi la data, come `production-web-2026-10`.

2. **Distribuisci la nuova chiave.** Aggiorna il secret nel gestore di secret o nell’ambiente e distribuiscilo a ogni server, worker e job programmato che usa la vecchia chiave.

3. **Conferma il passaggio.** Apri la nuova chiave e controlla che **Last used** sia recente. In **Email API → Logs**, filtra per la vecchia chiave e controlla che le richieste siano cessate.

4. **Elimina la vecchia chiave.** Quando l’orario **Last used** della vecchia chiave non cambia più, eliminala.

## Risoluzione dei problemi

| Sintomo | Causa | Soluzione |
| --- | --- | --- |
| `401` `Invalid API key` | La chiave è stata eliminata, rigenerata o digitata male. | Copia la chiave attuale nella configurazione, compreso il prefisso `secret_`. |
| `403` `Permission denied: read` o `Permission denied: full` | Una chiave di solo invio ha chiamato un endpoint fuori dal suo permesso. | Usa una chiave con accesso completo per quella chiamata. |
| `403` `Domain not authorized` | La chiave è limitata a un dominio diverso da quello dell’indirizzo `from`. | Invia dal dominio della chiave o usa un’altra chiave. |
| SMTP `535 Authentication failed` | La password non è una chiave API valida. | Usa la chiave API come password ed `emailit` come nome utente. |

## Vedi anche

  - [Autenticazione](/it/docs/api-reference/authentication/): Come vengono autenticate le richieste.
  - [API delle chiavi API](/it/docs/api-reference/api-keys/): Crea, elenca, aggiorna, rigenera ed elimina le chiavi.
  - [Impostazioni SMTP](/it/docs/smtp/settings/): Host, porte, TLS e credenziali.
  - [Sicurezza](/it/docs/security/): Come Emailit protegge il tuo account e i tuoi dati.

---
Fonte: https://emailit.com/it/docs/developers/api-keys/