Crea e gestisci la tua chiave API

Published: 16 luglio 2026 · Last updated: 21 luglio 2026 · By Marcus Biel

La pagina Chiave API consente a un sistema esterno di accedere autenticato agli endpoint API Maildroppa supportati nel tuo account.

Puoi creare una chiave API, copiarne il valore segreto completo, reimpostarla in sicurezza ruotandola oppure eliminarla quando non è più necessaria. La stessa chiave dell'account può essere utilizzata dalle integrazioni lato server e dai trigger di richieste API nelle Automazioni Maildroppa.

Una chiave API rappresenta il tuo account Maildroppa. Trattala come una password: chiunque ottenga la chiave può chiamare gli endpoint API disponibili per quella chiave finché non la ruoti o la elimini.

A cosa serve la chiave API

Usa la chiave API quando un software esterno a Maildroppa deve interagire con Maildroppa senza un accesso utente interattivo.

Gli esempi tipici includono:

• Sincronizzare gli iscritti con un CRM, un negozio, un sistema di gestione degli iscritti o un database interno.
• Creare o aggiornare iscritti da un'applicazione lato server.
• Leggere o gestire tag, campi, valori dei campi e segmenti tramite gli endpoint supportati.
• Inviare eventi personalizzati a un trigger di richiesta API in un'Automazione.
• Inviare messaggi email transazionali tramite l'API.
• Gestire le sottoscrizioni ai webhook basati su API.

La chiave API è destinata alla comunicazione server-to-server. Non è destinata al codice eseguito nel browser di un visitatore, su un sito web pubblico, in un'applicazione mobile o in un modulo di iscrizione incorporato.

La pagina è attualmente contrassegnata come “beta”. Usa la documentazione OpenAPI collegata come fonte per gli endpoint, i corpi delle richieste, i parametri e gli schemi delle risposte attualmente supportati dall'API.

Apertura della pagina Chiave API

Apri “Impostazioni”, espandi “Sviluppatori” e seleziona “Chiave API”.

Puoi anche aprire direttamente la pagina all'indirizzo:

https://app.maildroppa.com/settings/developers/api-key

La pagina contiene:

• Un pannello della chiave API con un badge beta.
• Un link “Visualizza documentazione OpenAPI”.
• Uno stato vuoto e il pulsante “Crea chiave API” quando non esiste alcuna chiave.
• Una rappresentazione mascherata della chiave corrente quando ne esiste una.
• Un pulsante “Copia” che copia la chiave completa.
• Le azioni “Ruota chiave API” ed “Elimina chiave API” per sostituire o rimuovere la chiave corrente.

Maildroppa consente una sola chiave API per account. La pagina non crea chiavi separate per singole applicazioni, ambienti o membri del team.

Creazione di una chiave API

Quando nella pagina compare “Nessuna chiave API”, fai clic su “Crea chiave API”.

Maildroppa crea immediatamente la chiave. Per questa prima creazione non viene mostrata alcuna finestra di conferma. Mentre la richiesta è in corso, il pulsante cambia in “Creazione della chiave API in corso” e la pagina disabilita temporaneamente le altre azioni sulla chiave.

Dopo la creazione della chiave:

• Lo stato vuoto scompare.
• Viene mostrata una chiave mascherata.
• Diventano disponibili le azioni “Copia”, “Ruota chiave API” ed “Elimina chiave API”.
• Maildroppa mostra un messaggio di successo “Chiave API aggiornata”.

Se per l'account esiste già un'altra chiave, Maildroppa non ne crea una seconda. Usa la chiave esistente oppure ruotala.

Comprendere la chiave mascherata

La pagina non mostra il segreto completo come testo normale. Visualizza i primi cinque caratteri seguiti da cinque asterischi, ad esempio:

a1b2c*****

Si tratta solo di una mascheratura visiva. Gli asterischi non rappresentano la lunghezza reale della chiave e il valore mascherato non può essere utilizzato per una richiesta API.

Fai clic su “Copia” per copiare negli appunti la chiave corrente completa. Dopo una copia riuscita, il pulsante cambia brevemente in “Copiata!”.

La chiave resta mascherata quando torni alla pagina, ma “Copia” continua a copiare il valore corrente completo. Pertanto non è necessario ruotare una chiave valida solo perché non l'hai salvata durante la creazione.

Conservazione sicura della chiave

Sposta la chiave copiata direttamente nell'archivio dei segreti utilizzato dall'integrazione.

Tra le posizioni adatte vi sono:

• Un gestore di segreti gestito.
• La configurazione protetta dell'ambiente server.
• Un segreto di deployment crittografato.
• Un gestore di password utilizzato per il ripristino operativo.

Non conservare la chiave in:

• JavaScript lato browser o in un altro bundle frontend scaricabile.
• Un file di codice sorgente pubblico o privato sottoposto a commit in un repository.
• Un URL o un parametro di query.
• Documentazione pubblica, screenshot, messaggi di supporto o sistemi di gestione delle segnalazioni.
• Log applicativi condivisi, eventi analitici o report di errore.
• Un foglio di calcolo non crittografato o una normale chat del team.

Non aggiungere la chiave a un esempio curl che verrà copiato nella documentazione o nella cronologia della shell condivisa con altre persone. Preferisci una variabile d'ambiente come MAILDROPPA_API_KEY.

Utilizzo della chiave API

Invia la chiave completa nell'header della richiesta HTTP X-API-Key:

X-API-Key: your-complete-api-key

Non inviarla come token Bearer. Maildroppa si aspetta X-API-Key, non Authorization: Bearer ....

L'API di produzione e la relativa documentazione OpenAPI interattiva sono disponibili all'indirizzo:

https://api.maildroppa.com

Fai clic su “Visualizza documentazione OpenAPI” nella pagina Chiave API per aprire la documentazione in una nuova scheda del browser. Seleziona un endpoint per esaminarne metodo, percorso, parametri, corpo della richiesta, tipo di risposta e possibili codici di stato.

Esempio di richiesta

L'esempio seguente recupera la prima pagina degli iscritti. Legge la chiave da una variabile d'ambiente invece di inserire direttamente il segreto nel comando:

curl --request GET \
  --url 'https://api.maildroppa.com/subscribers?pageNumber=1' \
  --header 'Accept: application/json' \
  --header "X-API-Key: ${MAILDROPPA_API_KEY}"

Imposta la variabile nell'ambiente sicuro in cui viene eseguita l'integrazione. Il metodo, il percorso, i parametri di query e il corpo esatti dipendono dall'endpoint. Copia questi dettagli dalla documentazione OpenAPI invece di dedurli dalle azioni disponibili nell'applicazione Maildroppa.

Richieste con corpi JSON

Per una richiesta che invia JSON, includi anche:

Content-Type: application/json

Ad esempio, la struttura di base è:

curl --request POST \
  --url 'https://api.maildroppa.com/example-endpoint' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "X-API-Key: ${MAILDROPPA_API_KEY}" \
  --data '{"example":"value"}'

/example-endpoint e il relativo corpo sono segnaposto. Sostituiscili con un endpoint documentato e con lo schema documentato della relativa richiesta.

A cosa può accedere la chiave

La chiave funziona solo con gli endpoint che supportano l'autenticazione tramite chiave API. Una pagina o una richiesta utilizzata internamente dall'applicazione Maildroppa non fa automaticamente parte dell'API pubblica per i clienti.

La documentazione OpenAPI mostra l'API per i clienti supportata. Se un percorso non è documentato per l'uso con una chiave API, non presumere che la chiave possa accedervi.

La pagina Chiave API non offre ambiti di autorizzazione né caselle di controllo per i permessi per endpoint. Pertanto, la chiave corrente dell'account deve essere trattata come una credenziale di grande valore anche se un'integrazione utilizza un solo endpoint.

Limiti di frequenza

Il contratto OpenAPI attuale documenta questi limiti per le chiavi API:

• API clienti predefinita: 300 richieste al minuto e 2.000 richieste all'ora.
• API degli eventi a /events: 100 richieste al secondo con una capacità di burst di 500 richieste.

Questi limiti vengono applicati all'account Maildroppa, non singolarmente a ogni script che condivide la chiave. Pertanto, più integrazioni possono consumare la stessa disponibilità.

Quando Maildroppa restituisce 429 Too Many Requests, interrompi l'invio di nuove richieste e rispetta l'header di risposta Retry-After quando presente. Usa una coda e un backoff controllato invece di avviare molti tentativi paralleli.

Le policy sui limiti di frequenza possono evolversi mentre l'API è in beta. Consulta le informazioni nella parte superiore della documentazione OpenAPI prima di progettare integrazioni ad alto volume.

Utilizzo della chiave per le richieste API delle Automazioni

Un'Automazione può avviarsi quando il tuo sistema invia un evento personalizzato all'Events API di Maildroppa.

Quando configuri un trigger di “richiesta API”, Maildroppa utilizza la stessa chiave API dell'account gestita in questa pagina. La configurazione del trigger può creare la chiave quando non ne esiste alcuna e può copiare una richiesta curl preparata contenente la chiave completa.

Questo comporta due conseguenze importanti:

• La rotazione o l'eliminazione della chiave dell'account influisce anche sui sistemi che inviano eventi personalizzati alle Automazioni.
• Un esempio di richiesta di un'Automazione copiato contiene il segreto negli appunti, anche se la chiave è mascherata sullo schermo.

Prima di ruotare o eliminare la chiave, includi nell'inventario delle integrazioni ogni trigger di richiesta API e ogni mittente esterno di eventi.

Reimpostazione o sostituzione della chiave API

Usa “Ruota chiave API” quando devi reimpostare o sostituire la credenziale corrente. Maildroppa crea una nuova chiave e invalida quella precedente nell'ambito della stessa azione.

Usa la rotazione quando:

• La chiave potrebbe essere stata esposta.
• Una persona o un fornitore che conosceva la chiave non necessita più dell'accesso.
• La tua policy di sicurezza richiede la sostituzione periodica delle credenziali.
• Vuoi sostituire una chiave conservata in una posizione vecchia o non sicura.

Fai clic su “Ruota chiave API” sotto la chiave mascherata. Maildroppa apre una finestra di avviso che spiega che la chiave esistente non sarà più utilizzabile.

Fai clic su “Ruota chiave API” nella finestra per continuare oppure su “Annulla” per mantenere la chiave corrente.

La rotazione non prevede un periodo di tolleranza

Dopo aver confermato la rotazione, la vecchia chiave smette immediatamente di funzionare. Maildroppa non mantiene valide contemporaneamente la vecchia e la nuova chiave.

Poiché l'account ha una sola chiave, la rotazione influisce su ogni server, processo pianificato, integrazione, script e mittente di eventi delle Automazioni che la utilizza.

Usa questa sequenza per una rotazione pianificata:

1. Elenca tutte le integrazioni che utilizzano la chiave corrente.
2. Prepara l'accesso alla configurazione dei segreti e al processo di deployment di ogni integrazione.
3. Scegli una breve finestra di manutenzione se è importante mantenere ininterrotto l'accesso all'API.
4. Fai clic su “Ruota chiave API”, quindi conferma l'avviso facendo clic su “Ruota chiave API” nella finestra.
5. Fai clic su “Copia” per copiare la nuova chiave completa.
6. Sostituisci immediatamente il segreto in ogni integrazione.
7. Riavvia o ridistribuisci i servizi che caricano i segreti solo all'avvio.
8. Invia una richiesta documentata innocua per verificare ogni integrazione.
9. Controlla la presenza di risposte 401 Unauthorized provenienti da un servizio dimenticato che utilizza ancora la vecchia chiave.

Se ritieni che la chiave corrente sia stata compromessa, ruotala immediatamente e accetta la breve interruzione necessaria per aggiornare i sistemi legittimi.

Eliminazione della chiave API

Elimina la chiave quando l'account non deve più accettare richieste autenticate tramite chiave API.

Fai clic su “Elimina chiave API” sotto la chiave mascherata. Maildroppa apre una finestra di avviso che spiega che la chiave verrà rimossa definitivamente dall'account.

Fai clic su “Elimina chiave API” nella finestra per eliminarla oppure su “Annulla” per conservarla.

Dopo l'eliminazione:

• La chiave corrente smette immediatamente di funzionare.
• La pagina torna allo stato “Nessuna chiave API”.
• Le integrazioni server che utilizzano la chiave eliminata non possono più autenticarsi.
• I mittenti di richieste API delle Automazioni che utilizzano quella chiave non possono più recapitare eventi.

L'eliminazione di una chiave non elimina iscritti, campagne, tag, campi, segmenti, Automazioni o altri dati dell'account. Rimuove la credenziale utilizzata per accedere agli endpoint API supportati.

Puoi fare clic su “Crea chiave API” in un secondo momento per creare una nuova credenziale. Il valore eliminato non viene ripristinato. Ogni integrazione deve essere aggiornata prima di poter utilizzare la nuova chiave.

Reimpostazione o eliminazione: quale scegliere?

Scegli “Ruota chiave API” quando l'accesso API deve continuare con una nuova credenziale.

Scegli l'eliminazione quando l'accesso API deve interrompersi completamente, almeno per il momento.

Entrambe le azioni invalidano immediatamente la chiave corrente. La rotazione crea la sostituzione nell'ambito della stessa azione; l'eliminazione lascia l'account senza chiavi.

Raccomandazioni di sicurezza

Mantieni le chiamate API sul tuo server

Un browser o un'app mobile non possono mantenere in modo affidabile un segreto incorporato. Un utente può analizzare l'applicazione, gli header delle richieste, le mappe sorgente o il traffico di rete ed estrarre la chiave.

Se un sito web o un'app deve attivare un'azione, invia prima la richiesta al tuo backend autenticato. Lascia che il backend convalidi l'utente e chiami Maildroppa utilizzando la chiave conservata sul server.

Riduci al minimo l'esposizione

Concedi la chiave solo ai sistemi che ne hanno bisogno. Non distribuirla a ogni sviluppatore e non incollarla in più file di configurazione locali.

Poiché la pagina gestisce attualmente una sola chiave a livello di account anziché più chiavi con nome o ambiti, utilizza un servizio di integrazione interno o un proxy se più applicazioni necessitano di un isolamento più forte tra loro.

Oscura gli header delle richieste

Configura client HTTP, proxy inversi, strumenti di osservabilità e sistemi di segnalazione degli errori per oscurare X-API-Key. Una richiesta può funzionare correttamente e al tempo stesso divulgare la credenziale tramite il logging di debug.

Mantieni separati gli ambienti

Non riutilizzare una chiave di produzione nello sviluppo locale, in codice di esempio, screenshot o fixture di test. Conserva i segreti specifici dell'ambiente in archivi di segreti specifici dell'ambiente.

Il link “Visualizza documentazione OpenAPI” indirizza automaticamente gli utenti di produzione alla documentazione dell'API di produzione. Verifica sempre il nome host prima di inviare una chiave reale.

Ruota la chiave dopo ogni sospetta esposizione

Eliminare un messaggio, un commit del repository, una riga di log o uno screenshot non dimostra che nessuno abbia copiato la chiave. Se il valore completo è stato esposto, ruotalo.

Gestione degli errori API

Usa lo stato HTTP e il corpo della risposta documentato per decidere cosa deve fare l'integrazione.

I casi comuni includono:

• 400 Bad Request — Il percorso, il parametro o il corpo JSON non soddisfa il contratto dell'endpoint. Confronta la richiesta con lo schema OpenAPI.
• 401 Unauthorized — L'header X-API-Key è assente, vuoto, non valido, eliminato o contiene un valore precedente dopo la rotazione.
• 403 Forbidden — La chiave autenticata non è autorizzata a utilizzare quell'operazione.
• 404 Not Found — Il percorso o la risorsa indicata non esiste in questo account.
• 429 Too Many Requests — L'integrazione ha raggiunto un limite di frequenza dell'API. Metti in pausa le richieste e rispetta l'header Retry-After quando presente.
• 5xx — Maildroppa non ha potuto completare la richiesta. Ripeti le operazioni sicure con un backoff esponenziale limitato e con logging che escluda la chiave API.

Non ripetere automaticamente ogni errore. Correggi le risposte 400, 401, 403 e la maggior parte delle risposte 404 prima di inviare nuovamente la stessa richiesta.

Per le richieste che modificano dati, verifica il comportamento di retry e di idempotenza dell'endpoint prima di ripetere automaticamente una richiesta. Un errore di connessione non dimostra sempre che Maildroppa non abbia apportato alcuna modifica.

Risoluzione dei problemi

“Crea chiave API” è ancora visibile

Attualmente non esiste alcuna chiave nell'account. Fai clic una volta sul pulsante e attendi il completamento della richiesta.

Se la creazione non riesce, ricarica la pagina prima di riprovare. Un'altra pagina o configurazione di un'Automazione potrebbe aver già creato la chiave dell'account.

La chiave nella pagina sembra troppo corta

La pagina mostra intenzionalmente solo i primi cinque caratteri e *****. Fai clic su “Copia” per copiare il valore completo. Non inviare il testo mascherato in una richiesta.

“Copia” non cambia in “Copiata!”

Il browser potrebbe aver bloccato l'accesso agli appunti. Mantieni la pagina nella scheda attiva, consenti l'accesso agli appunti se richiesto e fai nuovamente clic su “Copia”.

Non cercare di ricostruire la chiave dal testo mascherato.

Una richiesta restituisce 401 Unauthorized

Verifica che:

• Il nome dell'header sia esattamente X-API-Key.
• L'header contenga il valore completo, senza gli asterischi visibili.
• L'integrazione non stia inviando invece Authorization: Bearer.
• Al segreto non siano stati aggiunti spazi bianchi, virgolette o un ritorno a capo.
• Nessuno abbia ruotato o eliminato la chiave dell'account.
• Un servizio sia stato riavviato se legge le variabili d'ambiente solo all'avvio.
• La richiesta sia inviata all'ambiente API Maildroppa corretto.

Un'integrazione funziona, ma un'altra ha smesso di funzionare dopo la rotazione

La seconda integrazione probabilmente utilizza ancora la vecchia chiave. Non esiste un periodo di sovrapposizione. Aggiorna il suo segreto e riavvia ogni processo che memorizza nella cache la configurazione.

La pagina OpenAPI funziona, ma un endpoint restituisce 403

Non tutti gli endpoint dell'applicazione supportano l'autenticazione tramite chiave API. Usa un'operazione documentata per l'API clienti e verifica i requisiti di autenticazione nella pagina OpenAPI.

Le richieste restituiscono 429 Too Many Requests

Riduci i picchi di richieste, accoda il lavoro e riprova dopo il ritardo restituito dall'API. Evita raffiche di tentativi paralleli. Se più applicazioni condividono la stessa chiave dell'account, coordina il volume delle richieste perché condividono i limiti API dell'account.

Checklist di configurazione consigliata

Prima di utilizzare regolarmente un'integrazione, verifica che:

• La chiave sia conservata esclusivamente nella configurazione dei segreti lato server.
• Le richieste utilizzino l'header X-API-Key.
• L'integrazione utilizzi https://api.maildroppa.com in produzione.
• Ogni metodo, percorso, parametro e corpo JSON segua la documentazione OpenAPI.
• I log e i report di errore oscurino la chiave.
• Siano configurati timeout e tentativi limitati.
• Siano monitorati gli errori 401, 403, 429 e gli errori del server.
• Sia registrato il responsabile dell'integrazione.
• Ogni sistema che condivide la chiave dell'account sia incluso nel piano di rotazione.
• Una chiave compromessa possa essere ruotata rapidamente.

La pagina Chiave API è volutamente essenziale, ma le sue azioni influiscono su ogni integrazione API collegata all'account. Crea la chiave solo quando serve, conservala su server attendibili e pianifica la rotazione come una modifica della credenziale a livello di account.