API E-mail

09.11.2026
Skip to main content
< Zurück
Du bist hier:
Drucken

API E-mail

API E-mail

Con l’API E-mail crei, modifichi, disattivi ed elimini automaticamente le caselle e-mail del tuo hosting. Gestisci anche alias e inoltri. Funziona su tutti i nostri server di hosting (Linux e Windows) ed è gratuita.

 

Passo 1: Attivare l’accesso API

Accedi a admin.firestorm.ch con il tuo ID FireStorm e attiva Accesso API sotto Account => Profilo cliente.

Passo 2: Creare una chiave con l’ambito «E-mail»

Nello stesso modulo clicca su Gestisci chiavi API. Inserisci una descrizione, scegli l’ambito E-mail (caselle) e gli hosting di cui la chiave può gestire le caselle. Facoltativamente puoi limitare la chiave a singoli domini dell’hosting. Ti consigliamo di inserire anche gli indirizzi IP del tuo server: così la chiave funziona solo da lì.

La chiave viene mostrata una sola volta. Conservala in un luogo sicuro. Per ogni nuova chiave con accesso alle e-mail ti inviamo una conferma per e-mail. Se non hai creato tu la chiave, revocala subito nella stessa finestra.

La chiave API principale dell’API DNS volutamente non vale per l’API E-mail. Così una chiave DNS persa non apre mai le tue caselle e-mail.

Passo 3: Utilizzare l’API

Invia la chiave nell’header X-API-Key. I dati si inviano in formato JSON.

curl -H "X-API-Key: LA_TUA_CHIAVE_API" https://api.firestorm.ch/mail/v1/domains

 

Endpoint API

URL di base: https://api.firestorm.ch/mail/v1

Metodo Endpoint Descrizione
GET /domains Domini che la chiave può gestire
GET /domains/{dominio}/mailboxes Tutti gli indirizzi di un dominio
POST /mailboxes Creare una casella
GET /mailboxes/{indirizzo} Mostrare un indirizzo
PATCH /mailboxes/{indirizzo} Modificare password, spazio, inoltro o descrizione
POST /mailboxes/{indirizzo}/disable Disattivare (accesso bloccato, contenuto conservato)
POST /mailboxes/{indirizzo}/enable Riattivare con una nuova password
POST /mailboxes/{indirizzo}/aliases Aggiungere un alias
DELETE /mailboxes/{indirizzo}/aliases/{alias} Rimuovere un alias
DELETE /mailboxes/{indirizzo}?confirm={indirizzo} Eliminare definitivamente la casella e il suo contenuto

Descrizione tecnica completa come file OpenAPI: firestorm-mail-api.yaml

 

Esempi

Creare una casella

curl -X POST -H "X-API-Key: LA_TUA_CHIAVE_API" -H "Content-Type: application/json" \
  -d '{"address":"anna@esempio.ch","password":"Sicura-Pw-2026!","quota_mb":2048,"aliases":["anna.rossi"]}' \
  https://api.firestorm.ch/mail/v1/mailboxes

Modificare password e spazio

curl -X PATCH -H "X-API-Key: LA_TUA_CHIAVE_API" -H "Content-Type: application/json" \
  -d '{"password":"Nuova-Pw-2026!","quota_mb":4096}' \
  https://api.firestorm.ch/mail/v1/mailboxes/anna@esempio.ch

Impostare o disattivare un inoltro

L’elenco sostituisce tutte le destinazioni precedenti. Con "enabled":false e un elenco vuoto disattivi l’inoltro.

curl -X PATCH -H "X-API-Key: LA_TUA_CHIAVE_API" -H "Content-Type: application/json" \
  -d '{"forwarding":{"enabled":true,"addresses":["anna.privata@example.org"]}}' \
  https://api.firestorm.ch/mail/v1/mailboxes/anna@esempio.ch

Aggiungere e rimuovere un alias

curl -X POST -H "X-API-Key: LA_TUA_CHIAVE_API" -H "Content-Type: application/json" \
  -d '{"alias":"vendite"}' https://api.firestorm.ch/mail/v1/mailboxes/anna@esempio.ch/aliases

curl -X DELETE -H "X-API-Key: LA_TUA_CHIAVE_API" \
  https://api.firestorm.ch/mail/v1/mailboxes/anna@esempio.ch/aliases/vendite

Disattivare e riattivare

curl -X POST -H "X-API-Key: LA_TUA_CHIAVE_API" \
  https://api.firestorm.ch/mail/v1/mailboxes/anna@esempio.ch/disable

curl -X POST -H "X-API-Key: LA_TUA_CHIAVE_API" -H "Content-Type: application/json" \
  -d '{"password":"Ancora-Pw-2026!"}' \
  https://api.firestorm.ch/mail/v1/mailboxes/anna@esempio.ch/enable

Eliminare

curl -X DELETE -H "X-API-Key: LA_TUA_CHIAVE_API" \
  "https://api.firestorm.ch/mail/v1/mailboxes/anna@esempio.ch?confirm=anna@esempio.ch"

 

Buono a sapersi

  • Password: da 10 a 30 caratteri, almeno tre tra minuscole, maiuscole, cifre e caratteri speciali, senza il nome della casella. L’API non restituisce mai le password.
  • Disattivare blocca l’accesso (IMAP, POP3, SMTP, webmail). Il contenuto resta, le nuove e-mail continuano ad arrivare, alias e inoltri restano attivi. Per riattivare indichi una nuova password.
  • Eliminare rimuove definitivamente la casella con tutte le e-mail. Per questo devi confermare l’indirizzo con confirm.
  • I limiti del tuo hosting (numero di caselle, spazio) valgono anche per l’API. Se un limite è raggiunto, ricevi l’errore limit_reached.
  • Servizio e-mail: se /domains mostra "mail_service": false per un dominio, il servizio e-mail di quel dominio è disattivato nella gestione dell’hosting. Le caselle allora non funzionano.
  • Hosting Windows: le modifiche della password hanno effetto entro 2 minuti.
  • Limiti: 120 richieste al minuto per chiave, 100 nuove caselle e 500 modifiche al giorno per account. Dopo 25 accessi falliti l’indirizzo IP viene bloccato per 6 ore.
  • Gli errori arrivano in formato JSON: {"status":"error","error":"weak_password","message":"…"}. Nel tuo programma valuta il codice nel campo error; il testo message è pensato per le persone (in tedesco).
Related Post