Chiavi API

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.

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.
• Per inviare con una chiave, ti serve almeno un dominio di invio verificato.

Crea una chiave API

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"
  }'

{
  "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_••••••••••••••••••••••••••••••••"
}

Usa la chiave

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

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:

Per tutte le opzioni, vedi Impostazioni SMTP.

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.

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.
• 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

Vedi anche