Mail-Hosting API

Eine schlanke HTTPS/JSON-Schnittstelle zur automatisierten Verwaltung von Postfächern unter Ihrer Domain. Sie deckt den vollständigen Lebenszyklus einer Mailbox ab — Anlegen, Konfigurieren, Sperren und Löschen — samt Weiterleitungen, Speicherabfrage sowie White- und Blacklists pro Postfach.

Alle Aufrufe erfolgen über HTTPS gegen die Basis-URL. Anfragen und Antworten sind application/json. Sämtliche Daten verbleiben auf Schweizer Infrastruktur (Swiss Hosting).

Basis-URL	`https://myaid.firestorm.ch/v1`
Format	JSON (Request & Response), UTF-8
Auth	Bearer-Token im `Authorization`-Header
Rate-Limit	300 Anfragen/Minute pro API-Key

Authentifizierung

Jeder Aufruf trägt Ihren persönlichen API-Key im Authorization-Header. Der Key ist Ihrem Reseller-Account zugeordnet und auf Ihre Domain(s) beschränkt.

Authorization: Bearer IHR_API_KEY
Content-Type: application/json

Ein fehlender oder ungültiger Key wird mit 401 unauthorized beantwortet. Ein Zugriff auf eine nicht freigegebene Domain mit 403 domain_forbidden.

Behandeln Sie den API-Key wie ein Passwort. Er erlaubt die vollständige Verwaltung Ihrer Postfächer. Bei Verdacht auf Kompromittierung kontaktieren Sie uns zur sofortigen Rotation.

Pakete & Speicher

Der Speicher ist nicht frei setzbar, sondern an das gebuchte Paket gekoppelt. Der Paketwechsel (PATCH .../plan) passt das Speicherlimit sofort an.

Paket	Speicher	API-Wert
Mailbox S	1 GB	`"plan": "S"`
Mailbox L	5 GB	`"plan": "L"`

Konventionen

Mailbox-ID

Jede Mailbox erhält beim Anlegen eine stabile, undurchsichtige ID (z. B. mbx_000000123). Verwenden Sie diese ID für alle weiteren Operationen. IDs werden nie wiederverwendet.

Adresse bereits vergeben

Ein Create-Aufruf auf eine bereits existierende Adresse liefert 409 mailbox_exists und verändert das bestehende Postfach nicht.

Passwort-Richtlinie

Passwörter müssen der Server-Richtlinie genügen (sehr stark). Zu schwache Passwörter werden mit 400 weak_password abgewiesen.

Löschen mit Schonfrist

Beim Löschen kann eine Schonfrist (grace_days) gesetzt werden: Die Mailbox wird zuerst gesperrt und erst nach Ablauf physisch entfernt — das fängt versehentliche Löschungen ab.

Existenzprüfung / Vollabgleich

Zur Prüfung einer bekannten Adresse genügt der GET /mailboxes/{id}-Aufruf (200 vorhanden, 404 nicht vorhanden). Für den vollständigen Bestand steht GET /mailboxes mit Paginierung und Filtern zur Verfügung (Disaster-Recovery, Erst-Migration, Abgleich).

Postfach anlegen

POST/mailboxesLegt ein neues Postfach an

Body: address, plan (S|L) und ein initiales password.

# Request
POST /v1/mailboxes
{
  "address": "kunde@myaid.ch",
  "plan":    "S",
  "password":"initiales-passwort"
}

# 201 Created
{
  "id":      "mbx_000000123",
  "address": "kunde@myaid.ch",
  "plan":    "S",
  "status":  "active"
}

Fehler: 400 invalid_input, 400 weak_password, 400 domain_not_hosted, 403 domain_forbidden, 409 mailbox_exists.

Postfächer auflisten

GET/mailboxesAlle Postfächer des Kontos, paginiert

Liefert die Postfächer Ihres Reseller-Kontos (auf Ihre Domain(s) beschränkt), stabil nach Anlagereihenfolge sortiert. Über limit/offset paginiert; optional gefiltert nach status und plan.

Parameter	Werte	Beschreibung
`limit`	1–200 (Std. 50)	Maximale Anzahl je Seite
`offset`	≥ 0 (Std. 0)	Anzahl übersprungener Einträge
`status`	`active` · `suspended` · `pending_delete`	optionaler Statusfilter
`plan`	`S` · `L`	optionaler Paketfilter

# Request
GET /v1/mailboxes?limit=50&offset=0&plan=S

# 200 OK
{
  "total":  128,
  "limit":  50,
  "offset": 0,
  "count":  50,
  "mailboxes": [
    { "id": "mbx_000000123",
      "address": "kunde@myaid.ch",
      "plan": "S", "status": "active" },
    …
  ]
}

total = Gesamtzahl passender Postfächer (für die Paginierung). Weiterblättern, solange offset + count < total.

Status abfragen

GET/mailboxes/{id}Status & Existenzprüfung

# 200 OK  (404, falls unbekannt)
{
  "id":     "mbx_000000123",
  "address":"kunde@myaid.ch",
  "plan":   "S",
  "status": "active"
}

Mögliche status-Werte: active, suspended, pending_delete.

Paket wechseln

PATCH/mailboxes/{id}/planWechsel S ⇄ L

# Request
PATCH /v1/mailboxes/mbx_000000123/plan
{ "plan": "L" }

# 200 OK
{ "id": "mbx_000000123",
  "plan": "L",
  "status": "active" }

Das Speicherlimit wird sofort angepasst (S = 1 GB, L = 5 GB).

Passwort setzen

PUT/mailboxes/{id}/passwordSetzt ein neues Passwort

# Request
PUT /v1/mailboxes/mbx_000000123/password
{ "password": "neues-passwort" }

# 200 OK
{ "id": "mbx_000000123",
  "status": "active" }

Zu schwache Passwörter: 400 weak_password.

Weiterleitung setzen / entfernen

PUT/mailboxes/{id}/forwardWeiterleitung verwalten

Setzen mit target; keep_copy bestimmt, ob zusätzlich eine Kopie im Postfach verbleibt. Zum Entfernen target auf null setzen.

# Setzen — 200 OK
PUT /v1/mailboxes/mbx_000000123/forward
{ "target": "ablage@myaid.ch",
  "keep_copy": true }

# Entfernen — 200 OK
PUT /v1/mailboxes/mbx_000000123/forward
{ "target": null }

Speichernutzung abfragen

GET/mailboxes/{id}/usageBelegter Speicher

# 200 OK
{ "id": "mbx_000000123",
  "plan": "S",
  "quota_mb": 1024,
  "used_mb": 418 }

Sperren & Entsperren

POST/mailboxes/{id}/suspendMailbox sperren

# 200 OK
{ "id": "mbx_000000123", "status": "suspended", ... }

Eine gesperrte Mailbox nimmt keine Mails mehr an; die Daten bleiben erhalten.

POST/mailboxes/{id}/resumeSperrung aufheben

# 200 OK
{ "id": "mbx_000000123", "status": "active", ... }

Postfach löschen

DELETE/mailboxes/{id}Mit optionaler Schonfrist

Ohne grace_days (oder =0) wird sofort gelöscht (200). Mit grace_days > 0 wird die Mailbox gesperrt und erst nach Ablauf entfernt (202).

# Sofort — 200 OK
DELETE /v1/mailboxes/mbx_000000123
{ "id": "mbx_000000123",
  "status": "deleted" }

# Schonfrist — 202 Accepted
DELETE /v1/mailboxes/mbx_000000123?grace_days=7
{ "id": "mbx_000000123",
  "status": "pending_delete",
  "delete_after": "2026-07-24T…" }

Eine in Schonfrist befindliche Mailbox kann mit resume reaktiviert werden, solange sie noch nicht physisch entfernt wurde.

Whitelist (pro Postfach)

Persönliche Absenderliste je Mailbox. Ein Absender auf der Whitelist wird immer zugestellt. Einträge sind einzelne Adressen (Wildcard *@domain.tld möglich).

GET/mailboxes/{id}/whitelist

# 200 OK
{ "id": "mbx_000000123", "whitelist": ["chef@kunde.ch"] }

POST/mailboxes/{id}/whitelist

# Request
{ "sender": "chef@kunde.ch" }

# 201 Created
{ "id": "mbx_000000123",
  "sender": "chef@kunde.ch" }

DELETE/mailboxes/{id}/whitelist/{addr}

# 200 OK
DELETE /v1/mailboxes/mbx_000000123/whitelist/chef@kunde.ch
{ "id": "mbx_000000123", "removed": "chef@kunde.ch" }

Blacklist (pro Postfach)

Persönliche Sperrliste je Mailbox. Ein Absender auf der Blacklist wird immer abgewiesen. Aufbau analog zur Whitelist.

GET/mailboxes/{id}/blacklist

# 200 OK
{ "id": "mbx_000000123", "blacklist": ["spam@absender.tld"] }

POST/mailboxes/{id}/blacklist

# Request
{ "sender": "spam@absender.tld" }

# 201 Created
{ "id": "mbx_000000123",
  "sender": "spam@absender.tld" }

DELETE/mailboxes/{id}/blacklist/{addr}

# 200 OK
DELETE /v1/mailboxes/mbx_000000123/blacklist/spam@absender.tld
{ "id": "mbx_000000123", "removed": "spam@absender.tld" }

Alle Endpunkte

Methode	Endpunkt	Zweck
POST	`/mailboxes`	Mailbox anlegen
GET	`/mailboxes`	Postfächer auflisten (Paginierung + Filter)
GET	`/mailboxes/{id}`	Status / Existenzprüfung (200/404)
DELETE	`/mailboxes/{id}`	Löschen (optional `?grace_days=N`)
POST	`/mailboxes/{id}/suspend`	Sperren
POST	`/mailboxes/{id}/resume`	Sperrung aufheben
PATCH	`/mailboxes/{id}/plan`	Paket wechseln (S ⇄ L)
PUT	`/mailboxes/{id}/password`	Passwort setzen
PUT	`/mailboxes/{id}/forward`	Weiterleitung setzen/entfernen
GET	`/mailboxes/{id}/usage`	Belegter Speicher
GET	`/mailboxes/{id}/whitelist`	Whitelist lesen
POST	`/mailboxes/{id}/whitelist`	Absender zur Whitelist
DELETE	`/mailboxes/{id}/whitelist/{addr}`	Whitelist-Eintrag entfernen
GET	`/mailboxes/{id}/blacklist`	Blacklist lesen
POST	`/mailboxes/{id}/blacklist`	Absender zur Blacklist
DELETE	`/mailboxes/{id}/blacklist/{addr}`	Blacklist-Eintrag entfernen

Fehlerbehandlung

Fehler werden über Standard-HTTP-Statuscodes signalisiert. Der Antwort-Body enthält zusätzlich einen maschinenlesbaren Fehlercode und eine Klartext-Meldung.

# 409 Conflict
{ "error": "mailbox_exists",
  "message": "Adresse ist bereits vergeben." }

HTTP	error	Bedeutung
400	`invalid_input`	Ungültige Eingabe (Adresse, Plan, JSON …)
400	`weak_password`	Passwort erfüllt die Server-Richtlinie nicht
400	`domain_not_hosted`	Domain auf dem Server nicht eingerichtet
401	`unauthorized`	API-Key fehlt oder ist ungültig
403	`domain_forbidden`	Domain nicht für diesen Key freigegeben
404	`mailbox_not_found`	Mailbox unbekannt
409	`mailbox_exists`	Adresse ist bereits vergeben
429	`rate_limited`	Zu viele Anfragen (Limit 300/min)

Health-Check

GET/healthOhne Authentifizierung

# 200 OK
{ "status": "ok" }

Für Monitoring/Uptime-Checks. Erfordert keinen API-Key.

Beispiel: cURL

# Postfach anlegen
curl -X POST https://myaid.firestorm.ch/v1/mailboxes \
  -H "Authorization: Bearer IHR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"address":"kunde@myaid.ch","plan":"S","password":"…"}'