Mail API

Mail API

Mit der Mail API legst du Postfächer deines Hostings automatisch an, änderst sie, deaktivierst und löschst sie. Aliase und Weiterleitungen verwaltest du ebenfalls darüber. Sie funktioniert auf allen unseren Hosting-Servern (Linux und Windows) und ist kostenlos.

Schritt 1: API-Zugang aktivieren

Melde dich auf admin.firestorm.ch mit deiner FireStorm-ID an und aktiviere unter Konto => Kundenprofil den API Zugang.

Schritt 2: Key mit Bereich «Mail» erstellen

Klicke im gleichen Formular auf API Keys verwalten. Gib eine Bezeichnung ein, wähle den Bereich Mail (Postfächer) und die Hostings, deren Postfächer der Key verwalten darf. Optional schränkst du den Key auf einzelne Domains des Hostings ein. Wir empfehlen, auch die IP-Adressen deines Servers einzutragen: Dann funktioniert der Key nur von dort aus.

Der Key wird nur einmal angezeigt. Bewahre ihn sicher auf. Wir schicken dir bei jedem neuen Key mit Mail-Zugriff eine Bestätigung per E-Mail. Hast du den Key nicht selbst erstellt, widerrufe ihn sofort im gleichen Fenster.

Der Haupt-API-Key der DNS API gilt für die Mail API bewusst nicht. So öffnet ein verlorener DNS-Key nie deine Postfächer.

Schritt 3: API verwenden

Schicke den Key im Header X-API-Key mit. Daten sendest du als JSON.

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

API Endpunkte

Basis-URL: https://api.firestorm.ch/mail/v1

Die vollständige technische Beschreibung als OpenAPI-Datei: firestorm-mail-api.yaml

Beispiele

Postfach anlegen

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

Passwort und Speicherplatz ändern

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

Weiterleitung setzen oder ausschalten

Die Liste ersetzt alle bisherigen Ziele. Mit "enabled":false und leerer Liste schaltest du die Weiterleitung aus.

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

Alias hinzufügen und entfernen

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

curl -X DELETE -H "X-API-Key: DEIN_API_KEY" \
  https://api.firestorm.ch/mail/v1/mailboxes/anna@beispiel.ch/aliases/verkauf

Deaktivieren und wieder aktivieren

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

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

Löschen

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

Gut zu wissen

• Passwörter: 10 bis 30 Zeichen, mindestens drei von Kleinbuchstaben, Grossbuchstaben, Ziffern und Sonderzeichen, nicht den Postfachnamen enthalten. Die API gibt Passwörter nie zurück.
• Deaktivieren sperrt die Anmeldung (IMAP, POP3, SMTP, Webmail). Der Inhalt bleibt erhalten, neue E-Mails kommen weiterhin an, Aliase und Weiterleitungen bleiben aktiv. Zum Aktivieren gibst du ein neues Passwort an.
• Löschen entfernt das Postfach samt allen E-Mails endgültig. Darum musst du die Adresse mit confirm bestätigen.
• Grenzen deines Hostings (Anzahl Postfächer, Speicherplatz) gelten auch für die API. Ist das Limit erreicht, kommt der Fehler limit_reached.
• Maildienst: Zeigt /domains bei einer Domain "mail_service": false, ist der Maildienst dieser Domain in der Hosting-Verwaltung ausgeschaltet. Postfächer funktionieren dann nicht.
• Windows-Hosting: Passwortänderungen wirken nach höchstens 2 Minuten.
• Limits: 120 Anfragen pro Minute und Key, 100 neue Postfächer und 500 Änderungen pro Tag und Konto. Nach 25 fehlgeschlagenen Anmeldungen wird die IP-Adresse für 6 Stunden gesperrt.
• Fehler kommen als JSON: {"status":"error","error":"weak_password","message":"…"}. Werte in deinem Programm den Code im Feld error aus, der Text in message ist für Menschen gedacht.