Chapter 11 Clients, Groupware & CLI Admin: #pApiAuth

Scoped API Keys, sharpmail-cli (Infrastructure-as-Code), SCIM 2.0, OIDC & Global Disclaimers

CI/CD pipelines (Ansible, GitLab CI), web apps, and ERP systems should never share human mailbox passwords. Under API Keys, SSO & Rules (#pApiAuth), mint least-privilege Scoped API Keys, manage your server declaratively via built-in sharpmail-cli, and configure global legal disclaimers.

Operational Tip & Architecture Note

Zero extra binary downloads: sharpmail-cli ships built directly into SharpMailserver.Server (auto-linked at /usr/local/bin/sharpmail-cli on Linux/macOS/Docker, and SharpMailserver.Server.exe cli on Windows). Accounts with 2FA enabled automatically reject bare HTTP Basic passwords - always use a scoped smk_... API key for automation.

sharpmail-cli & Declarative IaC Examples

Export SHARPMAIL_URL and SHARPMAIL_TOKEN in your environment so secrets never appear in process arguments.

Reference / Configuration

export SHARPMAIL_URL="https://mail.firma.de"
export SHARPMAIL_TOKEN="smk_01968f2a_..."

# Schema & Felder eines Objekttyps anzeigen
sharpmail-cli describe Account

# Alle Postfächer als NDJSON für jq abfragen
sharpmail-cli query Account --json | jq -r '.email'

# Kompletten Ist-Zustand exportieren & Änderungen per Dry-Run prüfen
sharpmail-cli snapshot > prod-state.ndjson
sharpmail-cli apply --file prod-state.ndjson --dry-run

Settings, Default Values & Best Practices

Setting / Location	Description	Default Value	Production Best Practice
`Scoped API-Keys (smk_<id>_<secret>)`	Least-privilege Bearer / X-Api-Key credentials with RBAC scopes (User, ComplianceAuditor, TenantAdmin, ServerAdmin), default message category, CIDR source IP allowlists, and optional expiration.	`Role = User (Least Privilege)`	Select Role = User (/api/v1/send only) with an explicit default category (e.g. critical for 2FA, transactional for invoices); select CIDR-restricted TenantAdmin or ServerAdmin keys for CI/CD & Ansible.
`IP-Warming, Kategorien & Empfänger-Anbieter-Limits (/api/v1/send)`	Enforces distinct hourly and daily quotas per message category (critical, transactional, notification, marketing) clearly separated by recipient provider (Google/Gmail, Microsoft Outlook/Hotmail/Live, Yahoo & AOL, T-Online/GMX/WEB.DE, Apple iCloud) and per individual destination domain (*).	`28-Tage IP-Warming / 100 % Produktion`	Enable the 28-day IP warming ramp (5% -> 100%) on fresh IPs: critical 2FA mail bypasses warming at queue priority 10, while bulk notifications and marketing emails smoothly pace across future hourly windows (DeferQueue) or fail fast with HTTP 429 + Retry-After.
`sharpmail-cli (describe / get / query / create / update / delete / dns)`	Schema-driven management CLI with automatic local XDG/AppData schema caching, aligned tables, compact JSON, and jq-ready NDJSON streams (--json).	`SHARPMAIL_URL + SHARPMAIL_TOKEN`	Inspect object schemas via sharpmail-cli describe <Type>, pipe NDJSON via sharpmail-cli query Account --json \| jq, and export RFC 1035 BIND zones via sharpmail-cli dns domain.com --bind.
`Deklaratives IaC (sharpmail-cli snapshot & apply --dry-run)`	Exports Tenants, Domains, Accounts, Lists, Aliases, and singleton policies as an idempotent NDJSON plan and applies desired state with --dry-run preview.	`--dry-run vor jedem Rollout`	Version-control state via sharpmail-cli snapshot and always preview changes first with sharpmail-cli apply --file plan.ndjson --dry-run.
`Globale Pflicht-Signatur / Disclaimer`	Automatically appends mandatory corporate/legal footers prior to DKIM signing across text/html and text/plain parts with reply anti-stacking.	`Optional aktivierbar`	Provide concise HTML and Plaintext variants and keep duplicate suppression enabled so reply chains stay clean.
`OIDC Single Sign-On & SCIM 2.0`	Connects Entra ID, Keycloak, Authentik, or Okta for OIDC Single Sign-On plus automated SCIM 2.0 user lifecycle provisioning (/scim/v2).	`Lokale Auth + Passkeys aktiv`	Enable FIDO2 Passkeys for interactive logins and use a CIDR-restricted TenantAdmin API key for SCIM 2.0 provisioning.