sharpmail-cli Reference: Commands, Schema Cache, jq Queries & GitOps IaC

# Linux / macOS / GitLab CI / GitHub Actions:
export SHARPMAIL_URL="https://mail.firma.de"
export SHARPMAIL_API_KEY="smk_01968f2a_..."   # Alias: SHARPMAIL_TOKEN

# PowerShell (Windows Server / Admin-Workstation):
$env:SHARPMAIL_URL = "https://mail.firma.de"
$env:SHARPMAIL_API_KEY = "smk_01968f2a_..."

# Docker-Host ohne lokalen Wrapper (direkt im Container):
docker exec -i sharpmailserver sharpmail-cli describe

# Interaktive Erst-Anmeldung vor dem ersten API-Key (fragt Passwort verdeckt ab, nur ohne 2FA):
sharpmail-cli --url https://localhost --insecure -u admin@firma.de create ApiKey \
  --set label="Ansible Prod" --set role=ServerAdmin --set allowedCidrs=10.0.0.0/8 --set expiresInDays=90

# Hilfe zu jedem Unterbefehl direkt im Terminal + definierte Exit-Codes für Skripte:
sharpmail-cli --help
sharpmail-cli help create
# Exit-Codes: 0 = Erfolg · 1 = HTTP-/Auth-/Server-Fehler · 2 = Ungültige CLI-Parameter / JSON

# Alle 12 verfügbaren Objekttypen oder die Felder eines einzelnen Typs anzeigen:
sharpmail-cli describe
sharpmail-cli describe Route
sharpmail-cli describe TransactionalSend

# Einzelnes Objekt oder globale Singleton-Konfiguration lesen:
sharpmail-cli get Domain firma.de
sharpmail-cli get SmtpQueue --json | jq '{paused: .outboundQueuePaused, tls: .outboundTlsCertValidation}'

# Gefilterte Tabellen-Abfrage mit Spaltenprojektion:
sharpmail-cli query Account --filter domain=firma.de,isActive=true --fields email,role,quotaMb,twoFactorEnabled

# NDJSON-Pipeline (Bash + jq): Alle aktiven Admin-Konten ohne 2FA auflisten:
sharpmail-cli query Account --filter isActive=true --json \
  | jq -r 'select(.role != "User" and .twoFactorEnabled == false) | "\(.email)\t\(.role)"'

# PowerShell-Pipeline auf Windows Server: Postfächer > 80 % Quota finden:
sharpmail-cli query Account --json | ForEach-Object { $_ | ConvertFrom-Json } |
  Where-Object { $_.quotaMb -gt 0 -and ($_.usedBytes / 1MB) -gt ($_.quotaMb * 0.8) } |
  Select-Object email, quotaMb, @{N="UsedMB";E={[math]::Round($_.usedBytes/1MB,1)}}

# 1. Domain mit Dual-DKIM (RSA-2048 + Ed25519) und 10 Jahren GoBD-Aufbewahrung anlegen:
sharpmail-cli create Domain \
  --set name=firma.de \
  --set dkimSigningMode=Dual \
  --set retentionLockMode=Compliance \
  --set retentionDays=3650

# 2. Benutzerpostfach, Verteilerliste & Datenschutz-Alias anlegen:
sharpmail-cli create Account/User --set email=buchhaltung@firma.de --set displayName="Buchhaltung" --set password='...' --set quotaMb=15360
sharpmail-cli create Account/List --set email=rechnung@firma.de --set members=buchhaltung@firma.de,archiv@firma.de
sharpmail-cli create Alias --set address=info@firma.de --set target=buchhaltung@firma.de --set description="Zentrale"

# 3. Scoped API-Key für Webshop/ERP (nur /api/v1/send, feste Absenderadresse & Subnetz-Filter):
sharpmail-cli create ApiKey \
  --set label="Shopware Produktion" \
  --set role=User \
  --set senderAddress=bestellung@firma.de \
  --set defaultCategory=transactional \
  --set allowedCidrs=10.20.0.0/16,198.51.100.12/32 \
  --set expiresInDays=180

# 4. Ausgehende Route / TLS-Ausnahme für Partner-MX mit RemoteCertificateNameMismatch (Auto DNS-MX):
sharpmail-cli create Route --set domain=neff.me --set tlsMode=StartTlsIgnoreCert --set description="Shared-MX TLS Override"

# 5. IP-Warming & Reputation Shield aktivieren oder JSON per Pipe (stdin) übergeben:
sharpmail-cli update TransactionalSend --set preset=warming_28d
sharpmail-cli update ReputationShield --set preset=recommended
echo '{"junkScoreThreshold":4.2,"clamAvEnabled":true}' | sharpmail-cli update SpamGuard --data -

# Öffentliche DNS-Einträge live gegen die konfigurierten DKIM/DMARC/TLSA-Werte prüfen & als BIND-Zone speichern:
sharpmail-cli dns firma.de --live
sharpmail-cli dns firma.de --bind --output firma.de.zone

# Aktuellen Serverzustand als versionierbaren NDJSON-Plan exportieren (ohne Geheimnisse für Git):
sharpmail-cli snapshot Domain Account Alias Route TransactionalSend ReputationShield --output infra/mail-prod.ndjson

# Beispiel für deklarative Zeilen in infra/mail-prod.ndjson (inkl. Kommentaren & gezieltem Löschen):
# {"op":"upsert","type":"Domain","key":"firma.de","fields":{"name":"firma.de","dkimSigningMode":"Dual","retentionDays":3650}}
# {"op":"upsert","type":"Route","key":"neff.me","fields":{"domain":"neff.me","tlsMode":"StartTlsIgnoreCert","enabled":true}}
# {"op":"delete","type":"Alias","key":"alt-kampagne@firma.de"}

# CI/CD Pull-Request Check (verändert NICHTS in der Datenbank, Exit-Code != 0 bei Fehlern):
sharpmail-cli apply --file infra/mail-prod.ndjson --dry-run

# Nach Freigabe idempotent auf Produktion anwenden:
sharpmail-cli apply --file infra/mail-prod.ndjson