Chapter 12 Clients, Groupware & CLI Admin: #pApiAuth

Complete API & CLI Field Reference: All 12 Object Types, REST Endpoints & POST /api/v1/send

This reference documents every JSON property, data type, enum value, default setting, and minimum RBAC role across all 12 management objects (/api/admin/cli/objects/{type} & sharpmail-cli) as well as transactional email delivery (POST /api/v1/send). Use the instant filter box above the table to search any property such as dkimSigningMode, tlsMode, allowedCidrs, or warmingEnabled.

Operational Tip & Architecture Note

Live introspection in your terminal or via HTTP: every SharpMailserver exposes this complete schema in machine-readable JSON at GET /api/admin/cli/schema (with SHA-256 header X-SharpMail-Schema-Version). In your terminal, run sharpmail-cli describe <Type> (e.g. sharpmail-cli describe Domain or sharpmail-cli describe SmtpQueue) at any time.

⬇ schema.json ⬇ openapi.json

TransactionalSendRequest (POST /api/v1/send) 13 Tenant 11 Domain 19 Account (Account/User & Account/List) 18 Alias 7 ApiKey 11 Route 10 TransactionalSend (Singleton) 11 ReputationShield (Singleton) 20 SpamGuard (Singleton) 15 SmtpQueue (Singleton) 19 TransportRules & Server (Singletons) 11

Transactional Delivery

`TransactionalSendRequest (POST /api/v1/send)`

Key: Idempotency-Key RBAC: User+

13 Properties

High-throughput HTTP JSON delivery endpoint for web apps, ERPs, CRMs, and 2FA codes with category prioritization, IP warming, suppression pre-check, and 24h idempotency.

POST /api/v1/send Enqueues and signs transactional email (UTF-8 Multipart/Alternative + attachments)

POST /api/v1/unsubscribe/{token} Public RFC 8058 One-Click-Unsubscribe endpoint (DKIM-signed token)

{ } Object Schema & Typed Properties application/json · camelCase

├─ from string OPTIONAL

Default: Key senderAddress

Sender address. Automatically defaults to the key's bound senderAddress for Role=User keys.

├─ to string[] REQUIRED

Array of primary recipient email addresses (at least 1 required).

├─ cc string[] OPTIONAL

Default: []

Optional carbon-copy recipients.

├─ bcc string[] OPTIONAL

Default: []

Optional blind carbon-copy recipients.

├─ replyTo string OPTIONAL

Optional Reply-To address.

├─ subject string REQUIRED

Email subject line (UTF-8).

├─ textBody string OPTIONAL

Plain-text body (text/plain). At least one of textBody or htmlBody is required.

├─ htmlBody string OPTIONAL

HTML body (text/html). Supply alongside textBody for 10/10 deliverability.

├─ category string OPTIONAL

Default: transactional

Selects queue priority, IP warming bypass, and recipient-provider quota bucket.

Enum:"critical""transactional""notification""marketing"

├─ overflowMode string OPTIONAL

Default: DeferQueue

Behavior when destination provider hourly quota is reached (smooth queue pacing vs. HTTP 429 + Retry-After).

Enum:"DeferQueue""Reject429"

├─ idempotencyKey string OPTIONAL

Default: Header Idempotency-Key

Deterministic deduplication key (e.g. invoice ID) preventing duplicate sends within 24 hours.

├─ headers Record<string, string> OPTIONAL

Default: {}

Custom RFC 5322 X-headers dictionary.

├─ attachments SendAttachmentDto[] OPTIONAL

Default: []

Array of { fileName: string, contentType: string, base64Content: string }.

{
  "from": "Abrechnung <rechnung@firma.de>",
  "to": ["einkauf@kunde.de"],
  "cc": ["buchhaltung@firma.de"],
  "subject": "Ihre elektronische Rechnung RE-2026-90412",
  "category": "transactional",
  "overflowMode": "DeferQueue",
  "textBody": "Guten Tag,\nanbei erhalten Sie Ihre Rechnung RE-2026-90412.",
  "htmlBody": "<p>Guten Tag,</p><p>anbei erhalten Sie Ihre Rechnung <strong>RE-2026-90412</strong>.</p>",
  "headers": {
    "X-ERP-Document-Id": "RE-2026-90412"
  },
  "attachments": [
    {
      "fileName": "RE-2026-90412.pdf",
      "contentType": "application/pdf",
      "base64Content": "JVBERi0xLjcKJcfs..."
    }
  ]
}

# 1) Kleinstprivilegierten Sende-Key (Role=User) für rechnung@firma.de erstellen:
sharpmail-cli create ApiKey \
  --set label="ERP Rechnungsversand" \
  --set role=User \
  --set senderAddress=rechnung@firma.de \
  --set defaultCategory=transactional \
  --set allowedCidrs=10.20.0.0/16

# 2) Risikofreier Trockentest gegen die integrierte Sandbox-Sink-Domain:
# ok@sink.sharpmail.local | bounce@sink.sharpmail.local | defer@sink.sharpmail.local

curl -fsS -X POST "https://mail.firma.de/api/v1/send" \
  -H "Authorization: Bearer smk_01968f2a_..." \
  -H "Idempotency-Key: inv-2026-90412" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "rechnung@firma.de",
    "to": ["einkauf@kunde.de"],
    "subject": "Ihre Rechnung RE-2026-90412",
    "category": "transactional",
    "textBody": "Guten Tag, anbei Ihre Rechnung RE-2026-90412.",
    "htmlBody": "<p>Guten Tag, anbei Ihre Rechnung <b>RE-2026-90412</b>.</p>"
  }'

using System.Net.Http.Headers;
using System.Net.Http.Json;

using var http = new HttpClient { BaseAddress = new Uri("https://mail.firma.de") };
http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "smk_01968f2a_...");
http.DefaultRequestHeaders.Add("Idempotency-Key", "inv-2026-90412");

var response = await http.PostAsJsonAsync("/api/v1/send", new
{
    from = "rechnung@firma.de",
    to = new[] { "einkauf@kunde.de" },
    subject = "Ihre Rechnung RE-2026-90412",
    category = "transactional",
    textBody = "Guten Tag, anbei Ihre Rechnung RE-2026-90412.",
    htmlBody = "<p>Guten Tag, anbei Ihre Rechnung <strong>RE-2026-90412</strong>.</p>"
});
response.EnsureSuccessStatusCode();

Collection Object (CRUD)

`Tenant`

Key: slug RBAC: ServerAdmin+

11 Properties

Multi-tenant organization boundary isolating domains, principals, storage quotas (GiB), and default GoBD WORM compliance retention.

GET /api/admin/cli/objects/Tenant Lists all tenants

GET /api/admin/cli/objects/Tenant/{slugOrId} Gets tenant by slug or UUID

POST /api/admin/cli/objects/Tenant Creates a new tenant

PATCH /api/admin/cli/objects/Tenant/{slugOrId} Updates tenant quotas in place

{ } Object Schema & Typed Properties application/json · camelCase

├─ id guid READ-ONLY

Default: UUIDv7

Internal immutable UUIDv7 identifier.

├─ slug string PRIMARY KEY

Unique URL-safe tenant key (e.g. "default", "acme").

├─ name string REQUIRED

Human-readable organization display name.

├─ isActive boolean OPTIONAL

Default: true

Enable or suspend tenant.

├─ maxDomains integer OPTIONAL

Default: 100

Maximum domains allowed in this tenant.

├─ maxPrincipals integer OPTIONAL

Default: 10000

Maximum accounts and distribution lists.

├─ quotaGb integer OPTIONAL

Default: 100

Tenant storage ceiling in GiB.

├─ outboundDailyLimit integer OPTIONAL

Default: 25000

Maximum outbound emails per day across the tenant.

├─ defaultLockMode string OPTIONAL

Default: Normal

Default GoBD WORM lock mode for newly created domains.

Enum:"Normal""Governance""Compliance""LegalHold"

├─ defaultRetentionDays integer OPTIONAL

Default: 0

Default mandatory retention period in days (3650 = 10y GoBD).

├─ createdAtUtc datetime READ-ONLY

Creation timestamp in UTC.

{
  "slug": "acme",
  "name": "ACME Logistik GmbH",
  "isActive": true,
  "maxDomains": 50,
  "maxPrincipals": 2500,
  "quotaGb": 250,
  "outboundDailyLimit": 25000,
  "defaultLockMode": "Compliance",
  "defaultRetentionDays": 3650
}

# Mandant anlegen:
sharpmail-cli create Tenant \
  --set slug=acme \
  --set name="ACME Logistik GmbH" \
  --set quotaGb=250 \
  --set defaultLockMode=Compliance \
  --set defaultRetentionDays=3650

# Mandant abfragen & Kontingent erhöhen:
sharpmail-cli get Tenant acme
sharpmail-cli update Tenant acme --set quotaGb=500

curl -fsS -X POST "https://mail.firma.de/api/admin/cli/objects/Tenant" \
  -H "Authorization: Bearer smk_..." \
  -H "Content-Type: application/json" \
  -d '{"slug":"acme","name":"ACME Logistik GmbH","quotaGb":250,"defaultLockMode":"Compliance","defaultRetentionDays":3650}'

var payload = new
{
    slug = "acme",
    name = "ACME Logistik GmbH",
    quotaGb = 250,
    defaultLockMode = "Compliance",
    defaultRetentionDays = 3650
};
using var res = await http.PostAsJsonAsync("/api/admin/cli/objects/Tenant", payload);

Collection Object (CRUD)

`Domain`

Key: name RBAC: TenantAdmin+

19 Properties

Hosted mail domain with automatic parallel Dual-DKIM key generation (RSA-2048 + Ed25519), GoBD WORM retention policy, plus-addressing, and rate limits.

GET /api/admin/cli/objects/Domain Lists all domains

GET /api/admin/cli/objects/Domain/{name} Gets domain configuration & DKIM selectors

POST /api/admin/cli/objects/Domain Creates domain & generates RSA-2048 + Ed25519 DKIM keys

PATCH /api/admin/cli/objects/Domain/{name} Updates DKIM mode, quotas, or retention in 0 ms

GET /api/admin/cli/dns/{name}?live=true Verifies live DNS records or exports RFC 1035 BIND zone

{ } Object Schema & Typed Properties application/json · camelCase

├─ id guid READ-ONLY

Default: UUIDv7

Internal domain UUIDv7.

├─ name string PRIMARY KEY

DNS domain name (e.g. "muster-logistik.de").

├─ tenant string OPTIONAL

Default: default

Owning tenant slug or GUID.

├─ isActive boolean OPTIONAL

Default: true

Enable or pause domain.

├─ postmasterAddress string OPTIONAL

Default: postmaster@<name>

RFC 5321 postmaster contact address.

├─ dkimSigningMode string OPTIONAL

Default: Dual

Active DKIM signing mode (Dual signs with both RSA-2048 and Ed25519).

Enum:"Rsa2048""Ed25519""Dual"

├─ dkimRsaSelector string OPTIONAL

Default: s2026

RSA-2048 DNS selector.

├─ dkimRsaDnsName string READ-ONLY

Default: s2026._domainkey.<name>

Computed RSA-2048 _domainkey FQDN.

├─ dkimEd25519Selector string OPTIONAL

Default: ed2026

Ed25519 DNS selector.

├─ dkimEd25519DnsName string READ-ONLY

Default: ed2026._domainkey.<name>

Computed Ed25519 _domainkey FQDN.

├─ retentionLockMode string OPTIONAL

Default: Normal

GoBD WORM archive lock mode for this domain.

Enum:"Normal""Governance""Compliance""LegalHold"

├─ retentionDays integer OPTIONAL

Default: 0

Mandatory retention duration in days (3650 = 10y GoBD).

├─ quotaGb integer OPTIONAL

Default: 50

Domain storage ceiling in GiB.

├─ maxMessageSizeMb integer OPTIONAL

Default: 50

Maximum message size in MiB.

├─ maxAccounts integer OPTIONAL

Default: 1000

Maximum mailboxes in this domain.

├─ outboundDailyLimit integer OPTIONAL

Default: 5000

Daily outbound send limit for this domain.

├─ outboundHourlyLimit integer OPTIONAL

Default: 1000

Hourly outbound send limit for this domain.

├─ usePlusAddressing boolean OPTIONAL

Default: true

Enables RFC 5233 plus-addressing (user+tag@domain).

├─ createdAtUtc datetime READ-ONLY

Creation timestamp in UTC.

{
  "name": "muster-logistik.de",
  "tenant": "default",
  "isActive": true,
  "postmasterAddress": "postmaster@muster-logistik.de",
  "dkimSigningMode": "Dual",
  "dkimRsaSelector": "s2026",
  "dkimEd25519Selector": "ed2026",
  "retentionLockMode": "Compliance",
  "retentionDays": 3650,
  "quotaGb": 100,
  "maxMessageSizeMb": 50,
  "maxAccounts": 500,
  "outboundDailyLimit": 10000,
  "outboundHourlyLimit": 2000,
  "usePlusAddressing": true
}

# Domain mit Dual-DKIM und 10 Jahren GoBD-Compliance anlegen:
sharpmail-cli create Domain \
  --set name=muster-logistik.de \
  --set dkimSigningMode=Dual \
  --set retentionLockMode=Compliance \
  --set retentionDays=3650

# Fertige RFC-1035 BIND-Zonendatei exportieren & DNS live prüfen:
sharpmail-cli dns muster-logistik.de --bind > muster-logistik.de.zone
sharpmail-cli dns muster-logistik.de --live

curl -fsS -X PATCH "https://mail.firma.de/api/admin/cli/objects/Domain/muster-logistik.de" \
  -H "Authorization: Bearer smk_..." \
  -H "Content-Type: application/json" \
  -d '{"dkimSigningMode":"Dual","retentionLockMode":"Compliance","retentionDays":3650}'

using var res = await http.PatchAsJsonAsync(
    "/api/admin/cli/objects/Domain/muster-logistik.de",
    new { dkimSigningMode = "Dual", quotaGb = 200 });
res.EnsureSuccessStatusCode();

Collection Object (CRUD)

`Account (Account/User & Account/List)`

Key: email RBAC: TenantAdmin+

18 Properties

Represents a user mailbox (@type="User", with IMAP/JMAP/CalDAV/CardDAV/ActiveSync) or a distribution list (@type="List" with members[]).

GET /api/admin/cli/objects/Account?filter=role=TenantAdmin Lists/filters accounts and distribution lists

POST /api/admin/cli/objects/Account/User Creates a new user mailbox with RFC 6154 folders

POST /api/admin/cli/objects/Account/List Creates a new distribution list

PATCH /api/admin/cli/objects/Account/{email} Updates quota, forwarding, vacation, or password

DELETE /api/admin/cli/objects/Account/{email} Soft-deletes an account

{ } Object Schema & Typed Properties application/json · camelCase

├─ id guid READ-ONLY

Default: UUIDv7

Internal principal UUIDv7.

├─ @type string OPTIONAL

Default: User

Account variant: User mailbox or List distribution group.

Enum:"User""List"

├─ email string PRIMARY KEY

Primary email address of the mailbox or list.

├─ displayName string OPTIONAL

Default: Lokalteil

Display name shown in Webmail, GAL, and From headers.

├─ password string WRITE-ONLY (SECRET)

Plaintext password on create/update (immediately hashed with Argon2id).

├─ role string OPTIONAL

Default: User

Administrative RBAC role.

Enum:"User""ComplianceAuditor""TenantAdmin""ServerAdmin"

├─ isActive boolean OPTIONAL

Default: true

Enable or suspend account.

├─ quotaMb integer OPTIONAL

Default: 5120

Mailbox storage quota in MiB (5120 = 5 GiB).

├─ usedBytes long READ-ONLY

Default: 0

Current mailbox storage usage in bytes.

├─ outboundDailyLimit integer OPTIONAL

Default: 500

Daily outbound message limit for this account.

├─ forwardAddress string OPTIONAL

Optional SRS-safe forwarding destination email.

├─ forwardKeepOriginal boolean OPTIONAL

Default: true

Keep a local copy in INBOX when forwarding is active.

├─ vacationEnabled boolean OPTIONAL

Default: false

Enable automatic out-of-office responder.

├─ vacationSubject string OPTIONAL

Out-of-office auto-reply subject.

├─ vacationBody string WRITE-ONLY (SECRET)

Out-of-office auto-reply body text.

├─ twoFactorEnabled boolean READ-ONLY

Default: false

Indicates whether TOTP 2FA is active.

├─ members string[] OPTIONAL

Default: []

Member email addresses (for @type="List").

├─ createdAtUtc datetime READ-ONLY

Creation timestamp in UTC.

{
  "@type": "User",
  "email": "anna.weber@muster-logistik.de",
  "displayName": "Anna Weber (IT-Leitung)",
  "password": "SicheresStartPasswort!2026",
  "role": "TenantAdmin",
  "isActive": true,
  "quotaMb": 15360,
  "outboundDailyLimit": 1000,
  "forwardAddress": null,
  "forwardKeepOriginal": true,
  "vacationEnabled": false,
  "vacationSubject": "Abwesenheitsnotiz: Anna Weber",
  "vacationBody": "Ich bin ab Montag wieder erreichbar."
}

# Benutzerpostfach (15 GiB Quota) anlegen:
sharpmail-cli create Account/User \
  --set email=anna.weber@muster-logistik.de \
  --set displayName="Anna Weber" \
  --set password="SicheresStartPasswort!2026" \
  --set quotaMb=15360

# Verteilerliste anlegen:
sharpmail-cli create Account/List \
  --set email=team@muster-logistik.de \
  --set displayName="Disposition & Einkauf" \
  --set members=anna.weber@muster-logistik.de,dispo@muster-logistik.de

curl -fsS -X POST "https://mail.firma.de/api/admin/cli/objects/Account/User" \
  -H "Authorization: Bearer smk_..." \
  -H "Content-Type: application/json" \
  -d '{"email":"anna.weber@muster-logistik.de","displayName":"Anna Weber","password":"SicheresStartPasswort!2026","quotaMb":15360}'

await http.PostAsJsonAsync("/api/admin/cli/objects/Account/User", new
{
    email = "anna.weber@muster-logistik.de",
    displayName = "Anna Weber",
    password = "SicheresStartPasswort!2026",
    quotaMb = 15360
});

Collection Object (CRUD)

`Alias`

Key: address RBAC: TenantAdmin+

7 Properties

Secondary email alias or disposable masked privacy alias routed to a primary Account mailbox or distribution list.

GET /api/admin/cli/objects/Alias Lists all aliases and masked emails

POST /api/admin/cli/objects/Alias Creates a new alias routed to a target mailbox

PATCH /api/admin/cli/objects/Alias/{address} Enables/pauses an alias or updates its target

DELETE /api/admin/cli/objects/Alias/{address} Deletes the alias

{ } Object Schema & Typed Properties application/json · camelCase

├─ address string PRIMARY KEY

The alias email address.

├─ target string REQUIRED

Target primary Account email address.

├─ principalId guid READ-ONLY

Resolved target principal UUID.

├─ description string OPTIONAL

Default: ""

Purpose note or external service label (also shown in Webmail composer).

├─ isMasked boolean OPTIONAL

Default: false

Marks the alias as a masked privacy alias.

├─ isEnabled boolean OPTIONAL

Default: true

When false, mail to this alias is rejected without releasing the address.

├─ createdAtUtc datetime READ-ONLY

Creation timestamp in UTC.

{
  "address": "shop-8f2k@muster-logistik.de",
  "target": "anna.weber@muster-logistik.de",
  "description": "Fachbuchhandlung / Online-Bestellung",
  "isMasked": true,
  "isEnabled": true
}

# Masked-Email-Alias anlegen:
sharpmail-cli create Alias \
  --set address=shop-8f2k@muster-logistik.de \
  --set target=anna.weber@muster-logistik.de \
  --set description="Fachbuchhandlung" \
  --set isMasked=true

# Alias bei Spam-Aufkommen mit 1 Befehl stummschalten:
sharpmail-cli update Alias shop-8f2k@muster-logistik.de --set isEnabled=false

curl -fsS -X POST "https://mail.firma.de/api/admin/cli/objects/Alias" \
  -H "Authorization: Bearer smk_..." \
  -H "Content-Type: application/json" \
  -d '{"address":"vertrieb@muster-logistik.de","target":"anna.weber@muster-logistik.de","description":"Vertrieb & Angebote"}'

await http.PostAsJsonAsync("/api/admin/cli/objects/Alias", new
{
    address = "vertrieb@muster-logistik.de",
    target = "anna.weber@muster-logistik.de",
    description = "Vertrieb & Angebote",
    isEnabled = true
});

Collection Object (CRUD)

`ApiKey`

Key: id RBAC: TenantAdmin+

11 Properties

Immutable, RBAC- and CIDR-restricted Scoped API Key (smk_<id>_<secret>) for /api/v1/send, SCIM 2.0, or sharpmail-cli.

GET /api/admin/cli/objects/ApiKey Lists active API keys (secret omitted)

POST /api/admin/cli/objects/ApiKey Mints a new API key and returns apiKey (smk_...) once

DELETE /api/admin/cli/objects/ApiKey/{id} Revokes the API key immediately

{ } Object Schema & Typed Properties application/json · camelCase

├─ id guid READ-ONLY

Default: UUIDv7

Unique key UUID (used to revoke via DELETE).

├─ apiKey string CREATE-ONLY

Default: smk_<id>_<secret>

Full Bearer token returned ONLY once upon creation.

├─ label string REQUIRED

Human-readable label (e.g. "Ansible GitOps" or "Shopware 6").

├─ role string OPTIONAL

Default: TenantAdmin

Privilege scope (User is strictly restricted to POST /api/v1/send).

Enum:"User""ComplianceAuditor""TenantAdmin""ServerAdmin"

├─ senderAddress string OPTIONAL

Authorized sender address (required when role="User").

├─ defaultCategory string OPTIONAL

Default: transactional

Default send category for this key.

Enum:"critical""transactional""notification""marketing"

├─ allowedCidrs string[] OPTIONAL

Default: [] (Alle IPs)

Allowed source IPv4/IPv6 CIDR networks.

├─ expiresInDays integer WRITE-ONLY (SECRET)

Default: null (Kein Ablauf)

Optional automatic expiration in days from creation.

├─ expiresAtUtc datetime READ-ONLY

Computed UTC expiration timestamp.

├─ outboundDailyLimit integer OPTIONAL

Default: 10000

Daily outbound send limit for this key.

├─ isActive boolean READ-ONLY

Default: true

Active status.

{
  "label": "Shopware 6 ERP Rechnungsversand",
  "role": "User",
  "senderAddress": "rechnung@muster-logistik.de",
  "defaultCategory": "transactional",
  "allowedCidrs": ["10.20.10.15/32", "2a01:4f8:120:44aa::/64"],
  "expiresInDays": 180,
  "outboundDailyLimit": 10000
}

# CIDR-geschützten Key für Ansible / sharpmail-cli erstellen:
sharpmail-cli create ApiKey \
  --set label="GitLab CI / Ansible" \
  --set role=TenantAdmin \
  --set allowedCidrs=10.20.0.0/16 \
  --set expiresInDays=90

# Schlüssel widerrufen:
sharpmail-cli delete ApiKey 0195f2a0-8b14-7000-9a10-001122334455

curl -fsS -X POST "https://mail.firma.de/api/admin/cli/objects/ApiKey" \
  -H "Authorization: Bearer smk_..." \
  -H "Content-Type: application/json" \
  -d '{"label":"Shopware 6","role":"User","senderAddress":"rechnung@muster-logistik.de","allowedCidrs":["10.20.10.15/32"],"expiresInDays":180}'

var res = await http.PostAsJsonAsync("/api/admin/cli/objects/ApiKey", new
{
    label = "Shopware 6",
    role = "User",
    senderAddress = "rechnung@muster-logistik.de",
    allowedCidrs = new[] { "10.20.10.15/32" },
    expiresInDays = 180
});
var created = await res.Content.ReadFromJsonAsync<JsonElement>();
string oneTimeSecretKey = created.GetProperty("apiKey").GetString()!;

Collection Object (CRUD)

`Route`

Key: domain RBAC: ServerAdmin+

10 Properties

Per-domain outbound SMTP routing or TLS certificate exception (e.g. StartTlsIgnoreCert for partner MX hosts with mismatched certificates, or smart-host connector).

GET /api/admin/cli/objects/Route Lists all custom outbound routes

POST /api/admin/cli/objects/Route Creates a custom domain route or TLS override

PATCH /api/admin/cli/objects/Route/{domain} Updates target host, port, or TLS mode

DELETE /api/admin/cli/objects/Route/{domain} Deletes the custom route

{ } Object Schema & Typed Properties application/json · camelCase

├─ domain string PRIMARY KEY

Destination recipient domain (e.g. "neff.me" or "*.partner-holding.eu").

├─ targetHost string OPTIONAL

Default: "" (Auto DNS-MX)

Relay hostname or IP. Leave empty to resolve the destination MX via DNS automatically.

├─ targetPort integer OPTIONAL

Default: 25

Destination TCP port (25, 587, or 465).

├─ tlsMode string OPTIONAL

Default: StartTlsOptional

Outbound TLS and X.509 validation mode for this domain.

Enum:"StartTlsOptional""StartTlsRequired""StartTlsIgnoreCert""ImplicitTls""ImplicitTlsIgnoreCert""None"

├─ username string OPTIONAL

Optional SMTP AUTH username.

├─ password string WRITE-ONLY (SECRET)

Optional SMTP AUTH password.

├─ hasPassword boolean READ-ONLY

Default: false

Indicates whether a password is stored.

├─ clearPassword boolean WRITE-ONLY (SECRET)

Default: false

Set true to clear stored password.

├─ description string OPTIONAL

Admin audit note.

├─ enabled boolean OPTIONAL

Default: true

Enable or pause route.

{
  "domain": "neff.me",
  "targetHost": "",
  "targetPort": 25,
  "tlsMode": "StartTlsIgnoreCert",
  "username": null,
  "description": "Shared-Hosting-MX mit abweichendem Zertifikatsnamen (Auto DNS-MX)",
  "enabled": true
}

# Partner-Domain mit fehlerhaftem MX-Zertifikat per Auto-DNS-MX freigeben:
sharpmail-cli create Route \
  --set domain=neff.me \
  --set tlsMode=StartTlsIgnoreCert \
  --set description="TLS NameMismatch auf Partner-MX erlauben"

# Internes ERP-Subnetz an lokalen Connector routen:
sharpmail-cli create Route \
  --set domain=erp.firma.intern \
  --set targetHost=10.40.2.15 \
  --set targetPort=25

curl -fsS -X POST "https://mail.firma.de/api/admin/cli/objects/Route" \
  -H "Authorization: Bearer smk_..." \
  -H "Content-Type: application/json" \
  -d '{"domain":"neff.me","targetHost":"","targetPort":25,"tlsMode":"StartTlsIgnoreCert","enabled":true}'

await http.PostAsJsonAsync("/api/admin/cli/objects/Route", new
{
    domain = "neff.me",
    targetHost = "",
    targetPort = 25,
    tlsMode = "StartTlsIgnoreCert",
    enabled = true
});

Singleton Policy

`TransactionalSend (Singleton)`

Key: singleton RBAC: TenantAdmin+

11 Properties

Governs progressive 28-day IP warming, message categories, and per-recipient-provider hourly/daily quotas (Google, Microsoft, Yahoo/AOL, German ISPs, iCloud, *).

GET /api/admin/cli/objects/TransactionalSend/singleton Gets active IP warming & provider quota policy

PATCH /api/admin/cli/objects/TransactionalSend/singleton Updates warming day, preset, or provider quotas

{ } Object Schema & Typed Properties application/json · camelCase

├─ enabled boolean OPTIONAL

Default: true

Enables category and provider quota governance.

├─ warmingEnabled boolean OPTIONAL

Default: false

Enables progressive daily IP warming ramp.

├─ startAtWarmingDay integer WRITE-ONLY (SECRET)

Default: 1

Jumps or resets warming schedule to day N (1..365).

├─ currentWarmingDay integer READ-ONLY

Current active day in warming schedule.

├─ currentWarmingPercent integer READ-ONLY

Current active percentage of target provider quotas.

├─ warmingDailyRampPercents integer[] OPTIONAL

Default: [5,7,10,...,100]

Daily percentage array for the warming ramp.

├─ maxDeferHours integer OPTIONAL

Default: 48

Maximum lookahead window in hours for DeferQueue pacing.

├─ defaultCategory string OPTIONAL

Default: transactional

Fallback category when omitted in API calls.

Enum:"critical""transactional""notification""marketing"

├─ preset string WRITE-ONLY (SECRET)

One-step preset selector.

Enum:"warming_28d""warming_14d""production_100"

├─ categories CategoryPolicy[] OPTIONAL

Default: 4 Kategorien

Array of category policy objects.

├─ providers ProviderQuota[] OPTIONAL

Default: 6 Provider-Gruppen

Array of recipient-provider quota definitions.

{
  "enabled": true,
  "warmingEnabled": true,
  "startAtWarmingDay": 1,
  "maxDeferHours": 48,
  "defaultCategory": "transactional",
  "preset": "warming_28d"
}

# 28-Tage IP-Warming aktivieren:
sharpmail-cli update TransactionalSend --set preset=warming_28d

# Direkt auf Warming-Tag 14 vorspringen:
sharpmail-cli update TransactionalSend --set startAtWarmingDay=14

curl -fsS -X PATCH "https://mail.firma.de/api/admin/cli/objects/TransactionalSend/singleton" \
  -H "Authorization: Bearer smk_..." \
  -H "Content-Type: application/json" \
  -d '{"preset":"warming_28d","enabled":true}'

await http.PatchAsJsonAsync(
    "/api/admin/cli/objects/TransactionalSend/singleton",
    new { preset = "warming_28d", enabled = true });

Singleton Policy

`ReputationShield (Singleton)`

Key: singleton RBAC: TenantAdmin+

20 Properties

Optional outbound reputation protection: automatic bounce/complaint suppression list, RFC 8058 One-Click Unsubscribe, bounce circuit breaker, adaptive 421 ISP backoff, and HMAC-SHA256 webhooks.

GET /api/admin/cli/objects/ReputationShield/singleton Gets current Reputation Shield configuration

PATCH /api/admin/cli/objects/ReputationShield/singleton Updates protection flags or applies a preset

{ } Object Schema & Typed Properties application/json · camelCase

├─ preset string WRITE-ONLY (SECRET)

Applies a complete protection profile in one step.

Enum:"off""recommended""strict_bulk"

├─ enableSuppressionPreCheck boolean OPTIONAL

Default: false

Filters suppressed addresses pre-send.

├─ enforceSuppressionOnSmtpRelay boolean OPTIONAL

Default: false

Also enforces suppression list on SMTP submission.

├─ allSuppressedBehavior string OPTIONAL

Default: reject_422

Response mode when all recipients are suppressed.

Enum:"reject_422""accept_noop"

├─ autoSuppressHardBounces boolean OPTIONAL

Default: false

Automatically suppresses 5xx permanent hard bounces.

├─ hardBounceSuppressionDays integer OPTIONAL

Default: 180

Retention days for hard-bounce suppressions.

├─ autoSuppressConsecutiveSoftBounces boolean OPTIONAL

Default: false

Escalates repeated 4xx soft bounces to suppression list.

├─ softBounceEscalationThreshold integer OPTIONAL

Default: 5

Consecutive soft bounces before suppression.

├─ autoSuppressFblComplaints boolean OPTIONAL

Default: false

Parses inbound RFC 5965 ARF abuse reports automatically.

├─ enableOneClickUnsubscribe boolean OPTIONAL

Default: false

Injects DKIM-signed RFC 8058 List-Unsubscribe headers.

├─ oneClickUnsubscribeCategories string[] OPTIONAL

Default: ["marketing","notification"]

Categories receiving RFC 8058 unsubscribe headers.

├─ enableBounceCircuitBreaker boolean OPTIONAL

Default: false

Pauses non-critical sends if 24h bounce/complaint rate spikes.

├─ maxHardBouncePercent number OPTIONAL

Default: 5.0

24h hard-bounce rate ceiling in percent.

├─ maxComplaintPercent number OPTIONAL

Default: 0.1

24h ARF complaint rate ceiling in percent.

├─ allowCriticalWhenTripped boolean OPTIONAL

Default: true

Allows critical 2FA mail even when circuit breaker is tripped.

├─ enableAdaptiveIspBackoff boolean OPTIONAL

Default: false

Automatic cooldown when remote MX returns 421/451 throttling.

├─ ispCooldownMinutes integer OPTIONAL

Default: 15

Cooldown duration in minutes.

├─ webhookEnabled boolean OPTIONAL

Default: false

Enables HMAC-SHA256 signed webhooks.

├─ webhookUrl string OPTIONAL

Destination HTTPS URL for webhooks.

├─ webhookSecret string WRITE-ONLY (SECRET)

HMAC-SHA256 secret for X-SharpMail-Signature.

{
  "preset": "recommended",
  "enableSuppressionPreCheck": true,
  "autoSuppressHardBounces": true,
  "hardBounceSuppressionDays": 180,
  "enableOneClickUnsubscribe": true,
  "oneClickUnsubscribeCategories": ["marketing", "notification"],
  "enableBounceCircuitBreaker": true,
  "maxHardBouncePercent": 5.0,
  "maxComplaintPercent": 0.1,
  "allowCriticalWhenTripped": true,
  "enableAdaptiveIspBackoff": true,
  "webhookEnabled": true,
  "webhookUrl": "https://erp.firma.de/webhooks/sharpmail"
}

# Empfohlenen Reputationsschutz aktivieren:
sharpmail-cli update ReputationShield --set preset=recommended

# Webhook-Ziel konfigurieren:
sharpmail-cli update ReputationShield \
  --set webhookEnabled=true \
  --set webhookUrl=https://erp.firma.de/webhooks/sharpmail \
  --set webhookSecret=whsec_9f8e7d6c5b4a

curl -fsS -X PATCH "https://mail.firma.de/api/admin/cli/objects/ReputationShield/singleton" \
  -H "Authorization: Bearer smk_..." \
  -H "Content-Type: application/json" \
  -d '{"preset":"recommended"}'

await http.PatchAsJsonAsync(
    "/api/admin/cli/objects/ReputationShield/singleton",
    new { preset = "recommended" });

Singleton Policy

`SpamGuard (Singleton)`

Key: singleton RBAC: ServerAdmin+

15 Properties

Multi-stage inbound defense: SPF/DKIM/DMARC/ARC verification, Smart Greylisting (/24 IPv4 & /64 IPv6), online ML classifier (FTRL-Proximal), DNSBL zones, allow/blocklists, and ClamAV TCP scan.

GET /api/admin/cli/objects/SpamGuard/singleton Gets SpamGuard thresholds & training counters

PATCH /api/admin/cli/objects/SpamGuard/singleton Updates scores, DNSBLs, allowlists, or ClamAV in place

{ } Object Schema & Typed Properties application/json · camelCase

├─ enableEmailAuthChecks boolean OPTIONAL

Default: true

Verifies inbound SPF, DKIM, DMARC, and ARC.

├─ enableGreylisting boolean OPTIONAL

Default: true

Adaptive Smart Greylisting for unknown first-time senders.

├─ greylistRetryDelaySeconds integer OPTIONAL

Default: 240

Minimum retry delay in seconds (default: 240s).

├─ junkScoreThreshold number OPTIONAL

Default: 4.5

Score threshold for filing into the Junk folder.

├─ rejectScoreThreshold number OPTIONAL

Default: 9.0

Score threshold for hard SMTP 550 rejection.

├─ tagSubjectOnJunk boolean OPTIONAL

Default: false

Prepend subject prefix to Junk messages.

├─ subjectTagPrefix string OPTIONAL

Default: "[SPAM] "

Subject prefix string.

├─ enableStructuralHeuristics boolean OPTIONAL

Default: true

Evaluates MIME/HTML structural heuristics.

├─ dnsblZones string[] OPTIONAL

Default: ["bl.spamcop.net","ix.dnsbl.manitu.net"]

Queried DNSBL zones.

├─ dnsblHitScore number OPTIONAL

Default: 3.5

Score added per DNSBL hit.

├─ allowedSendersOrDomains string[] OPTIONAL

Default: []

Explicit sender email or domain allowlist.

├─ blockedSendersOrDomains string[] OPTIONAL

Default: []

Explicit sender email or domain blocklist.

├─ clamAvEnabled boolean OPTIONAL

Default: false

Enables ClamAV daemon TCP INSTREAM scanning.

├─ clamAvHost string OPTIONAL

Default: "127.0.0.1"

ClamAV daemon host or IP.

├─ clamAvPort integer OPTIONAL

Default: 3310

ClamAV daemon TCP port.

{
  "enableEmailAuthChecks": true,
  "enableGreylisting": true,
  "greylistRetryDelaySeconds": 240,
  "junkScoreThreshold": 4.5,
  "rejectScoreThreshold": 9.0,
  "enableStructuralHeuristics": true,
  "dnsblZones": ["bl.spamcop.net", "ix.dnsbl.manitu.net"],
  "dnsblHitScore": 3.5,
  "allowedSendersOrDomains": ["datev.de", "partner-spedition.de"],
  "blockedSendersOrDomains": [],
  "clamAvEnabled": false,
  "clamAvHost": "127.0.0.1",
  "clamAvPort": 3310
}

# Partner-Domains auf die Allowlist setzen:
sharpmail-cli update SpamGuard \
  --set allowedSendersOrDomains=datev.de,partner-spedition.de

# Schwellenwerte anpassen:
sharpmail-cli update SpamGuard --set junkScoreThreshold=4.5 --set rejectScoreThreshold=9.0

curl -fsS -X PATCH "https://mail.firma.de/api/admin/cli/objects/SpamGuard/singleton" \
  -H "Authorization: Bearer smk_..." \
  -H "Content-Type: application/json" \
  -d '{"junkScoreThreshold":4.5,"rejectScoreThreshold":9.0,"allowedSendersOrDomains":["datev.de"]}'

await http.PatchAsJsonAsync(
    "/api/admin/cli/objects/SpamGuard/singleton",
    new { junkScoreThreshold = 4.5, rejectScoreThreshold = 9.0 });

Singleton Policy

`SmtpQueue (Singleton)`

Key: singleton RBAC: ServerAdmin+

19 Properties

Controls the outbound MX delivery queue, worker concurrency, retry intervals, ISP throttling, outbound TLS validation, global smart-host, and inbound ESMTP limits.

GET /api/admin/cli/objects/SmtpQueue/singleton Gets all queue, TLS, and ESMTP settings

PATCH /api/admin/cli/objects/SmtpQueue/singleton Updates queue workers, retry schedule, or ESMTP limits in 0 ms

{ } Object Schema & Typed Properties application/json · camelCase

├─ outboundQueuePaused boolean OPTIONAL

Default: false

Pauses outbound MX delivery while continuing to accept mail.

├─ outboundWorkerConcurrency integer OPTIONAL

Default: 8

Number of parallel outbound delivery workers.

├─ maxDeliveryAttempts integer OPTIONAL

Default: 10

Maximum delivery attempts before permanent bounce.

├─ retryScheduleMinutes integer[] OPTIONAL

Default: [5,15,60,240,720]

Retry backoff schedule in minutes.

├─ maxConcurrentConnectionsPerMxDomain integer OPTIONAL

Default: 4

Max concurrent connections per destination MX domain.

├─ strictThrottleDomains string[] OPTIONAL

Default: ["t-online.de","gmx.de","web.de","yahoo.com"]

Domains subject to strict concurrency throttling.

├─ strictThrottleMaxConcurrency integer OPTIONAL

Default: 2

Max concurrent connections for strictThrottleDomains.

├─ outboundConnectTimeoutSeconds integer OPTIONAL

Default: 30

Outbound TCP/TLS connect timeout in seconds.

├─ outboundBindAddress string OPTIONAL

Default: "" (Auto)

Optional local source IP bind address.

├─ outboundUseStartTls boolean OPTIONAL

Default: true

Use STARTTLS on outbound MX connections.

├─ requireOutboundTls boolean OPTIONAL

Default: false

Abort delivery if remote MX does not offer TLS.

├─ outboundTlsCertValidation string OPTIONAL

Default: Opportunistic

Global outbound X.509 certificate validation mode.

Enum:"Opportunistic""IgnoreErrors""Strict"

├─ outboundSmartHost string OPTIONAL

Default: ""

Optional global upstream relay host.

├─ outboundSmartPort integer OPTIONAL

Default: 587

Global smart-host TCP port.

├─ maxMessageSizeMb long OPTIONAL

Default: 50

Global ESMTP SIZE limit in MiB.

├─ maxRecipientsPerTransaction integer OPTIONAL

Default: 100

Maximum RCPT TO commands per transaction.

├─ maxConnectionsPerIp integer OPTIONAL

Default: 20

Maximum simultaneous inbound connections per IP.

├─ tarpitDelayMs integer OPTIONAL

Default: 1500

Tarpit delay in ms on auth/command errors.

├─ requireTlsForAuth boolean OPTIONAL

Default: true

Requires TLS encryption before allowing SMTP AUTH.

{
  "outboundQueuePaused": false,
  "outboundWorkerConcurrency": 8,
  "maxDeliveryAttempts": 10,
  "retryScheduleMinutes": [5, 15, 60, 240, 720],
  "maxConcurrentConnectionsPerMxDomain": 4,
  "strictThrottleDomains": ["t-online.de", "gmx.de", "web.de", "yahoo.com"],
  "strictThrottleMaxConcurrency": 2,
  "outboundUseStartTls": true,
  "requireOutboundTls": false,
  "outboundTlsCertValidation": "Opportunistic",
  "maxMessageSizeMb": 50,
  "maxRecipientsPerTransaction": 100,
  "tarpitDelayMs": 1500,
  "requireTlsForAuth": true
}

# Outbound-TLS auf Opportunistic (RFC 7435) setzen & MaxMessageSize auf 75 MiB erhöhen:
sharpmail-cli update SmtpQueue \
  --set outboundTlsCertValidation=Opportunistic \
  --set maxMessageSizeMb=75

curl -fsS -X PATCH "https://mail.firma.de/api/admin/cli/objects/SmtpQueue/singleton" \
  -H "Authorization: Bearer smk_..." \
  -H "Content-Type: application/json" \
  -d '{"outboundTlsCertValidation":"Opportunistic","maxMessageSizeMb":75}'

await http.PatchAsJsonAsync(
    "/api/admin/cli/objects/SmtpQueue/singleton",
    new { outboundTlsCertValidation = "Opportunistic", maxMessageSizeMb = 75 });

Singleton Policy

`TransportRules & Server (Singletons)`

Key: singleton RBAC: ServerAdmin+

11 Properties

Organization-wide legal disclaimer (inserted prior to DKIM signing), global inbound Sieve script, Fail2Ban auto-ban thresholds, and canonical ServerHostName.

GET /api/admin/cli/objects/TransportRules/singleton Gets disclaimer, global Sieve, and auto-ban settings

PATCH /api/admin/cli/objects/TransportRules/singleton Updates transport rules in place

GET /api/admin/cli/objects/Server/singleton Gets ServerHostName, storage engine, queue depth, and license status

PATCH /api/admin/cli/objects/Server/singleton Updates canonical ServerHostName in 0 ms

{ } Object Schema & Typed Properties application/json · camelCase

├─ outboundDisclaimerEnabled boolean OPTIONAL

Default: false

Appends mandatory corporate footer to outbound messages.

├─ outboundDisclaimerExternalOnly boolean OPTIONAL

Default: true

Append footer only when sending to external domains.

├─ outboundDisclaimerText string OPTIONAL

Default: ""

Plain-text legal footer.

├─ outboundDisclaimerHtml string OPTIONAL

Default: ""

HTML legal footer.

├─ inboundSystemSieve string OPTIONAL

Default: ""

Global RFC 5228 Sieve script executed before user scripts.

├─ autoBanThreshold integer OPTIONAL

Default: 8

Failed logins before automatic IP ban.

├─ autoBanDurationMinutes integer OPTIONAL

Default: 30

Automatic IP ban duration in minutes.

├─ serverHostName string OPTIONAL

Default: mail.<domain>

Canonical EHLO, TLS, and Autodiscover FQDN (Object: Server).

├─ storageProvider string READ-ONLY

Default: Sqlite | SqlServer | Postgres

Active storage engine (Object: Server).

├─ activeQueueCount integer READ-ONLY

Default: 0

Current outbound queue count (Object: Server).

├─ licenseState string READ-ONLY

Default: EnterpriseActive

License state (Object: Server).

{
  "outboundDisclaimerEnabled": true,
  "outboundDisclaimerExternalOnly": true,
  "outboundDisclaimerText": "-- \nMuster Logistik GmbH · Industriestraße 18 · 70565 Stuttgart · HRB 774819",
  "outboundDisclaimerHtml": "<p style='font-size:11px;color:#64748b'><strong>Muster Logistik GmbH</strong> &middot; 70565 Stuttgart &middot; HRB 774819</p>",
  "inboundSystemSieve": "require [\"fileinto\"];\nif header :contains \"X-Spam-Flag\" \"YES\" { fileinto \"Junk\"; }",
  "autoBanThreshold": 8,
  "autoBanDurationMinutes": 30
}

# Pflicht-Impressum & Auto-Ban aktualisieren:
sharpmail-cli update TransportRules \
  --set outboundDisclaimerEnabled=true \
  --set autoBanThreshold=8

# Kanonischen Server-Hostnamen abfragen oder setzen:
sharpmail-cli get Server
sharpmail-cli update Server --set serverHostName=mail.muster-logistik.de

curl -fsS -X GET "https://mail.firma.de/api/admin/cli/objects/Server/singleton" \
  -H "Authorization: Bearer smk_..."

var status = await http.GetFromJsonAsync<JsonElement>("/api/admin/cli/objects/Server/singleton");
Console.WriteLine($"Host: {status.GetProperty("serverHostName")}, Queue: {status.GetProperty("activeQueueCount")}");

GET /api/admin/cli/schema · X-SharpMail-Schema-Version: sha256 · OpenAPI 3.1 kompatibel

⬇ Download JSON

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "SharpMailserver Management & Transactional API Schema (v1.2.5)",
  "product": "SharpMailserver",
  "cli": "sharpmail-cli",
  "schemaEndpoint": "/api/admin/cli/schema",
  "transactionalSendEndpoint": "/api/v1/send",
  "models": {
    "TransactionalSendRequest (POST /api/v1/send)": {
      "category": "Transactional",
      "singleton": false,
      "primaryKey": "Idempotency-Key",
      "minimumRole": "User",
      "properties": {
        "from": { "type": "string", "access": "optional", "default": "Key senderAddress", "description": "Sender address. Automatically defaults to the key's bound senderAddress for Role=User keys." },
        "to": { "type": "string[]", "access": "required", "description": "Array of primary recipient email addresses (at least 1 required)." },
        "cc": { "type": "string[]", "access": "optional", "default": "[]", "description": "Optional carbon-copy recipients." },
        "bcc": { "type": "string[]", "access": "optional", "default": "[]", "description": "Optional blind carbon-copy recipients." },
        "replyTo": { "type": "string", "access": "optional", "description": "Optional Reply-To address." },
        "subject": { "type": "string", "access": "required", "description": "Email subject line (UTF-8)." },
        "textBody": { "type": "string", "access": "optional", "description": "Plain-text body (text/plain). At least one of textBody or htmlBody is required." },
        "htmlBody": { "type": "string", "access": "optional", "description": "HTML body (text/html). Supply alongside textBody for 10/10 deliverability." },
        "category": { "type": "string", "access": "optional", "default": "transactional", "enum": ["critical", "transactional", "notification", "marketing"], "description": "Selects queue priority, IP warming bypass, and recipient-provider quota bucket." },
        "overflowMode": { "type": "string", "access": "optional", "default": "DeferQueue", "enum": ["DeferQueue", "Reject429"], "description": "Behavior when destination provider hourly quota is reached (smooth queue pacing vs. HTTP 429 + Retry-After)." },
        "idempotencyKey": { "type": "string", "access": "optional", "default": "Header Idempotency-Key", "description": "Deterministic deduplication key (e.g. invoice ID) preventing duplicate sends within 24 hours." },
        "headers": { "type": "Record<string, string>", "access": "optional", "default": "{}", "description": "Custom RFC 5322 X-headers dictionary." },
        "attachments": { "type": "SendAttachmentDto[]", "access": "optional", "default": "[]", "description": "Array of { fileName: string, contentType: string, base64Content: string }." }
      }
    },
    "Tenant": {
      "category": "Collection",
      "singleton": false,
      "primaryKey": "slug",
      "minimumRole": "ServerAdmin",
      "properties": {
        "id": { "type": "guid", "access": "read-only", "default": "UUIDv7", "description": "Internal immutable UUIDv7 identifier." },
        "slug": { "type": "string", "access": "key", "description": "Unique URL-safe tenant key (e.g. \"default\", \"acme\")." },
        "name": { "type": "string", "access": "required", "description": "Human-readable organization display name." },
        "isActive": { "type": "boolean", "access": "optional", "default": "true", "description": "Enable or suspend tenant." },
        "maxDomains": { "type": "integer", "access": "optional", "default": "100", "description": "Maximum domains allowed in this tenant." },
        "maxPrincipals": { "type": "integer", "access": "optional", "default": "10000", "description": "Maximum accounts and distribution lists." },
        "quotaGb": { "type": "integer", "access": "optional", "default": "100", "description": "Tenant storage ceiling in GiB." },
        "outboundDailyLimit": { "type": "integer", "access": "optional", "default": "25000", "description": "Maximum outbound emails per day across the tenant." },
        "defaultLockMode": { "type": "string", "access": "optional", "default": "Normal", "enum": ["Normal", "Governance", "Compliance", "LegalHold"], "description": "Default GoBD WORM lock mode for newly created domains." },
        "defaultRetentionDays": { "type": "integer", "access": "optional", "default": "0", "description": "Default mandatory retention period in days (3650 = 10y GoBD)." },
        "createdAtUtc": { "type": "datetime", "access": "read-only", "description": "Creation timestamp in UTC." }
      }
    },
    "Domain": {
      "category": "Collection",
      "singleton": false,
      "primaryKey": "name",
      "minimumRole": "TenantAdmin",
      "properties": {
        "id": { "type": "guid", "access": "read-only", "default": "UUIDv7", "description": "Internal domain UUIDv7." },
        "name": { "type": "string", "access": "key", "description": "DNS domain name (e.g. \"muster-logistik.de\")." },
        "tenant": { "type": "string", "access": "optional", "default": "default", "description": "Owning tenant slug or GUID." },
        "isActive": { "type": "boolean", "access": "optional", "default": "true", "description": "Enable or pause domain." },
        "postmasterAddress": { "type": "string", "access": "optional", "default": "postmaster@<name>", "description": "RFC 5321 postmaster contact address." },
        "dkimSigningMode": { "type": "string", "access": "optional", "default": "Dual", "enum": ["Rsa2048", "Ed25519", "Dual"], "description": "Active DKIM signing mode (Dual signs with both RSA-2048 and Ed25519)." },
        "dkimRsaSelector": { "type": "string", "access": "optional", "default": "s2026", "description": "RSA-2048 DNS selector." },
        "dkimRsaDnsName": { "type": "string", "access": "read-only", "default": "s2026._domainkey.<name>", "description": "Computed RSA-2048 _domainkey FQDN." },
        "dkimEd25519Selector": { "type": "string", "access": "optional", "default": "ed2026", "description": "Ed25519 DNS selector." },
        "dkimEd25519DnsName": { "type": "string", "access": "read-only", "default": "ed2026._domainkey.<name>", "description": "Computed Ed25519 _domainkey FQDN." },
        "retentionLockMode": { "type": "string", "access": "optional", "default": "Normal", "enum": ["Normal", "Governance", "Compliance", "LegalHold"], "description": "GoBD WORM archive lock mode for this domain." },
        "retentionDays": { "type": "integer", "access": "optional", "default": "0", "description": "Mandatory retention duration in days (3650 = 10y GoBD)." },
        "quotaGb": { "type": "integer", "access": "optional", "default": "50", "description": "Domain storage ceiling in GiB." },
        "maxMessageSizeMb": { "type": "integer", "access": "optional", "default": "50", "description": "Maximum message size in MiB." },
        "maxAccounts": { "type": "integer", "access": "optional", "default": "1000", "description": "Maximum mailboxes in this domain." },
        "outboundDailyLimit": { "type": "integer", "access": "optional", "default": "5000", "description": "Daily outbound send limit for this domain." },
        "outboundHourlyLimit": { "type": "integer", "access": "optional", "default": "1000", "description": "Hourly outbound send limit for this domain." },
        "usePlusAddressing": { "type": "boolean", "access": "optional", "default": "true", "description": "Enables RFC 5233 plus-addressing (user+tag@domain)." },
        "createdAtUtc": { "type": "datetime", "access": "read-only", "description": "Creation timestamp in UTC." }
      }
    },
    "Account (Account/User & Account/List)": {
      "category": "Collection",
      "singleton": false,
      "primaryKey": "email",
      "minimumRole": "TenantAdmin",
      "properties": {
        "id": { "type": "guid", "access": "read-only", "default": "UUIDv7", "description": "Internal principal UUIDv7." },
        "@type": { "type": "string", "access": "optional", "default": "User", "enum": ["User", "List"], "description": "Account variant: User mailbox or List distribution group." },
        "email": { "type": "string", "access": "key", "description": "Primary email address of the mailbox or list." },
        "displayName": { "type": "string", "access": "optional", "default": "Lokalteil", "description": "Display name shown in Webmail, GAL, and From headers." },
        "password": { "type": "string", "access": "write-only", "description": "Plaintext password on create/update (immediately hashed with Argon2id)." },
        "role": { "type": "string", "access": "optional", "default": "User", "enum": ["User", "ComplianceAuditor", "TenantAdmin", "ServerAdmin"], "description": "Administrative RBAC role." },
        "isActive": { "type": "boolean", "access": "optional", "default": "true", "description": "Enable or suspend account." },
        "quotaMb": { "type": "integer", "access": "optional", "default": "5120", "description": "Mailbox storage quota in MiB (5120 = 5 GiB)." },
        "usedBytes": { "type": "long", "access": "read-only", "default": "0", "description": "Current mailbox storage usage in bytes." },
        "outboundDailyLimit": { "type": "integer", "access": "optional", "default": "500", "description": "Daily outbound message limit for this account." },
        "forwardAddress": { "type": "string", "access": "optional", "description": "Optional SRS-safe forwarding destination email." },
        "forwardKeepOriginal": { "type": "boolean", "access": "optional", "default": "true", "description": "Keep a local copy in INBOX when forwarding is active." },
        "vacationEnabled": { "type": "boolean", "access": "optional", "default": "false", "description": "Enable automatic out-of-office responder." },
        "vacationSubject": { "type": "string", "access": "optional", "description": "Out-of-office auto-reply subject." },
        "vacationBody": { "type": "string", "access": "write-only", "description": "Out-of-office auto-reply body text." },
        "twoFactorEnabled": { "type": "boolean", "access": "read-only", "default": "false", "description": "Indicates whether TOTP 2FA is active." },
        "members": { "type": "string[]", "access": "optional", "default": "[]", "description": "Member email addresses (for @type=\"List\")." },
        "createdAtUtc": { "type": "datetime", "access": "read-only", "description": "Creation timestamp in UTC." }
      }
    },
    "Alias": {
      "category": "Collection",
      "singleton": false,
      "primaryKey": "address",
      "minimumRole": "TenantAdmin",
      "properties": {
        "address": { "type": "string", "access": "key", "description": "The alias email address." },
        "target": { "type": "string", "access": "required", "description": "Target primary Account email address." },
        "principalId": { "type": "guid", "access": "read-only", "description": "Resolved target principal UUID." },
        "description": { "type": "string", "access": "optional", "default": "\"\"", "description": "Purpose note or external service label (also shown in Webmail composer)." },
        "isMasked": { "type": "boolean", "access": "optional", "default": "false", "description": "Marks the alias as a masked privacy alias." },
        "isEnabled": { "type": "boolean", "access": "optional", "default": "true", "description": "When false, mail to this alias is rejected without releasing the address." },
        "createdAtUtc": { "type": "datetime", "access": "read-only", "description": "Creation timestamp in UTC." }
      }
    },
    "ApiKey": {
      "category": "Collection",
      "singleton": false,
      "primaryKey": "id",
      "minimumRole": "TenantAdmin",
      "properties": {
        "id": { "type": "guid", "access": "read-only", "default": "UUIDv7", "description": "Unique key UUID (used to revoke via DELETE)." },
        "apiKey": { "type": "string", "access": "create-only", "default": "smk_<id>_<secret>", "description": "Full Bearer token returned ONLY once upon creation." },
        "label": { "type": "string", "access": "required", "description": "Human-readable label (e.g. \"Ansible GitOps\" or \"Shopware 6\")." },
        "role": { "type": "string", "access": "optional", "default": "TenantAdmin", "enum": ["User", "ComplianceAuditor", "TenantAdmin", "ServerAdmin"], "description": "Privilege scope (User is strictly restricted to POST /api/v1/send)." },
        "senderAddress": { "type": "string", "access": "optional", "description": "Authorized sender address (required when role=\"User\")." },
        "defaultCategory": { "type": "string", "access": "optional", "default": "transactional", "enum": ["critical", "transactional", "notification", "marketing"], "description": "Default send category for this key." },
        "allowedCidrs": { "type": "string[]", "access": "optional", "default": "[] (Alle IPs)", "description": "Allowed source IPv4/IPv6 CIDR networks." },
        "expiresInDays": { "type": "integer", "access": "write-only", "default": "null (Kein Ablauf)", "description": "Optional automatic expiration in days from creation." },
        "expiresAtUtc": { "type": "datetime", "access": "read-only", "description": "Computed UTC expiration timestamp." },
        "outboundDailyLimit": { "type": "integer", "access": "optional", "default": "10000", "description": "Daily outbound send limit for this key." },
        "isActive": { "type": "boolean", "access": "read-only", "default": "true", "description": "Active status." }
      }
    },
    "Route": {
      "category": "Collection",
      "singleton": false,
      "primaryKey": "domain",
      "minimumRole": "ServerAdmin",
      "properties": {
        "domain": { "type": "string", "access": "key", "description": "Destination recipient domain (e.g. \"neff.me\" or \"*.partner-holding.eu\")." },
        "targetHost": { "type": "string", "access": "optional", "default": "\"\" (Auto DNS-MX)", "description": "Relay hostname or IP. Leave empty to resolve the destination MX via DNS automatically." },
        "targetPort": { "type": "integer", "access": "optional", "default": "25", "description": "Destination TCP port (25, 587, or 465)." },
        "tlsMode": { "type": "string", "access": "optional", "default": "StartTlsOptional", "enum": ["StartTlsOptional", "StartTlsRequired", "StartTlsIgnoreCert", "ImplicitTls", "ImplicitTlsIgnoreCert", "None"], "description": "Outbound TLS and X.509 validation mode for this domain." },
        "username": { "type": "string", "access": "optional", "description": "Optional SMTP AUTH username." },
        "password": { "type": "string", "access": "write-only", "description": "Optional SMTP AUTH password." },
        "hasPassword": { "type": "boolean", "access": "read-only", "default": "false", "description": "Indicates whether a password is stored." },
        "clearPassword": { "type": "boolean", "access": "write-only", "default": "false", "description": "Set true to clear stored password." },
        "description": { "type": "string", "access": "optional", "description": "Admin audit note." },
        "enabled": { "type": "boolean", "access": "optional", "default": "true", "description": "Enable or pause route." }
      }
    },
    "TransactionalSend (Singleton)": {
      "category": "Singleton",
      "singleton": true,
      "primaryKey": "singleton",
      "minimumRole": "TenantAdmin",
      "properties": {
        "enabled": { "type": "boolean", "access": "optional", "default": "true", "description": "Enables category and provider quota governance." },
        "warmingEnabled": { "type": "boolean", "access": "optional", "default": "false", "description": "Enables progressive daily IP warming ramp." },
        "startAtWarmingDay": { "type": "integer", "access": "write-only", "default": "1", "description": "Jumps or resets warming schedule to day N (1..365)." },
        "currentWarmingDay": { "type": "integer", "access": "read-only", "description": "Current active day in warming schedule." },
        "currentWarmingPercent": { "type": "integer", "access": "read-only", "description": "Current active percentage of target provider quotas." },
        "warmingDailyRampPercents": { "type": "integer[]", "access": "optional", "default": "[5,7,10,...,100]", "description": "Daily percentage array for the warming ramp." },
        "maxDeferHours": { "type": "integer", "access": "optional", "default": "48", "description": "Maximum lookahead window in hours for DeferQueue pacing." },
        "defaultCategory": { "type": "string", "access": "optional", "default": "transactional", "enum": ["critical", "transactional", "notification", "marketing"], "description": "Fallback category when omitted in API calls." },
        "preset": { "type": "string", "access": "write-only", "enum": ["warming_28d", "warming_14d", "production_100"], "description": "One-step preset selector." },
        "categories": { "type": "CategoryPolicy[]", "access": "optional", "default": "4 Kategorien", "description": "Array of category policy objects." },
        "providers": { "type": "ProviderQuota[]", "access": "optional", "default": "6 Provider-Gruppen", "description": "Array of recipient-provider quota definitions." }
      }
    },
    "ReputationShield (Singleton)": {
      "category": "Singleton",
      "singleton": true,
      "primaryKey": "singleton",
      "minimumRole": "TenantAdmin",
      "properties": {
        "preset": { "type": "string", "access": "write-only", "enum": ["off", "recommended", "strict_bulk"], "description": "Applies a complete protection profile in one step." },
        "enableSuppressionPreCheck": { "type": "boolean", "access": "optional", "default": "false", "description": "Filters suppressed addresses pre-send." },
        "enforceSuppressionOnSmtpRelay": { "type": "boolean", "access": "optional", "default": "false", "description": "Also enforces suppression list on SMTP submission." },
        "allSuppressedBehavior": { "type": "string", "access": "optional", "default": "reject_422", "enum": ["reject_422", "accept_noop"], "description": "Response mode when all recipients are suppressed." },
        "autoSuppressHardBounces": { "type": "boolean", "access": "optional", "default": "false", "description": "Automatically suppresses 5xx permanent hard bounces." },
        "hardBounceSuppressionDays": { "type": "integer", "access": "optional", "default": "180", "description": "Retention days for hard-bounce suppressions." },
        "autoSuppressConsecutiveSoftBounces": { "type": "boolean", "access": "optional", "default": "false", "description": "Escalates repeated 4xx soft bounces to suppression list." },
        "softBounceEscalationThreshold": { "type": "integer", "access": "optional", "default": "5", "description": "Consecutive soft bounces before suppression." },
        "autoSuppressFblComplaints": { "type": "boolean", "access": "optional", "default": "false", "description": "Parses inbound RFC 5965 ARF abuse reports automatically." },
        "enableOneClickUnsubscribe": { "type": "boolean", "access": "optional", "default": "false", "description": "Injects DKIM-signed RFC 8058 List-Unsubscribe headers." },
        "oneClickUnsubscribeCategories": { "type": "string[]", "access": "optional", "default": "[\"marketing\",\"notification\"]", "description": "Categories receiving RFC 8058 unsubscribe headers." },
        "enableBounceCircuitBreaker": { "type": "boolean", "access": "optional", "default": "false", "description": "Pauses non-critical sends if 24h bounce/complaint rate spikes." },
        "maxHardBouncePercent": { "type": "number", "access": "optional", "default": "5.0", "description": "24h hard-bounce rate ceiling in percent." },
        "maxComplaintPercent": { "type": "number", "access": "optional", "default": "0.1", "description": "24h ARF complaint rate ceiling in percent." },
        "allowCriticalWhenTripped": { "type": "boolean", "access": "optional", "default": "true", "description": "Allows critical 2FA mail even when circuit breaker is tripped." },
        "enableAdaptiveIspBackoff": { "type": "boolean", "access": "optional", "default": "false", "description": "Automatic cooldown when remote MX returns 421/451 throttling." },
        "ispCooldownMinutes": { "type": "integer", "access": "optional", "default": "15", "description": "Cooldown duration in minutes." },
        "webhookEnabled": { "type": "boolean", "access": "optional", "default": "false", "description": "Enables HMAC-SHA256 signed webhooks." },
        "webhookUrl": { "type": "string", "access": "optional", "description": "Destination HTTPS URL for webhooks." },
        "webhookSecret": { "type": "string", "access": "write-only", "description": "HMAC-SHA256 secret for X-SharpMail-Signature." }
      }
    },
    "SpamGuard (Singleton)": {
      "category": "Singleton",
      "singleton": true,
      "primaryKey": "singleton",
      "minimumRole": "ServerAdmin",
      "properties": {
        "enableEmailAuthChecks": { "type": "boolean", "access": "optional", "default": "true", "description": "Verifies inbound SPF, DKIM, DMARC, and ARC." },
        "enableGreylisting": { "type": "boolean", "access": "optional", "default": "true", "description": "Adaptive Smart Greylisting for unknown first-time senders." },
        "greylistRetryDelaySeconds": { "type": "integer", "access": "optional", "default": "240", "description": "Minimum retry delay in seconds (default: 240s)." },
        "junkScoreThreshold": { "type": "number", "access": "optional", "default": "4.5", "description": "Score threshold for filing into the Junk folder." },
        "rejectScoreThreshold": { "type": "number", "access": "optional", "default": "9.0", "description": "Score threshold for hard SMTP 550 rejection." },
        "tagSubjectOnJunk": { "type": "boolean", "access": "optional", "default": "false", "description": "Prepend subject prefix to Junk messages." },
        "subjectTagPrefix": { "type": "string", "access": "optional", "default": "\"[SPAM] \"", "description": "Subject prefix string." },
        "enableStructuralHeuristics": { "type": "boolean", "access": "optional", "default": "true", "description": "Evaluates MIME/HTML structural heuristics." },
        "dnsblZones": { "type": "string[]", "access": "optional", "default": "[\"bl.spamcop.net\",\"ix.dnsbl.manitu.net\"]", "description": "Queried DNSBL zones." },
        "dnsblHitScore": { "type": "number", "access": "optional", "default": "3.5", "description": "Score added per DNSBL hit." },
        "allowedSendersOrDomains": { "type": "string[]", "access": "optional", "default": "[]", "description": "Explicit sender email or domain allowlist." },
        "blockedSendersOrDomains": { "type": "string[]", "access": "optional", "default": "[]", "description": "Explicit sender email or domain blocklist." },
        "clamAvEnabled": { "type": "boolean", "access": "optional", "default": "false", "description": "Enables ClamAV daemon TCP INSTREAM scanning." },
        "clamAvHost": { "type": "string", "access": "optional", "default": "\"127.0.0.1\"", "description": "ClamAV daemon host or IP." },
        "clamAvPort": { "type": "integer", "access": "optional", "default": "3310", "description": "ClamAV daemon TCP port." }
      }
    },
    "SmtpQueue (Singleton)": {
      "category": "Singleton",
      "singleton": true,
      "primaryKey": "singleton",
      "minimumRole": "ServerAdmin",
      "properties": {
        "outboundQueuePaused": { "type": "boolean", "access": "optional", "default": "false", "description": "Pauses outbound MX delivery while continuing to accept mail." },
        "outboundWorkerConcurrency": { "type": "integer", "access": "optional", "default": "8", "description": "Number of parallel outbound delivery workers." },
        "maxDeliveryAttempts": { "type": "integer", "access": "optional", "default": "10", "description": "Maximum delivery attempts before permanent bounce." },
        "retryScheduleMinutes": { "type": "integer[]", "access": "optional", "default": "[5,15,60,240,720]", "description": "Retry backoff schedule in minutes." },
        "maxConcurrentConnectionsPerMxDomain": { "type": "integer", "access": "optional", "default": "4", "description": "Max concurrent connections per destination MX domain." },
        "strictThrottleDomains": { "type": "string[]", "access": "optional", "default": "[\"t-online.de\",\"gmx.de\",\"web.de\",\"yahoo.com\"]", "description": "Domains subject to strict concurrency throttling." },
        "strictThrottleMaxConcurrency": { "type": "integer", "access": "optional", "default": "2", "description": "Max concurrent connections for strictThrottleDomains." },
        "outboundConnectTimeoutSeconds": { "type": "integer", "access": "optional", "default": "30", "description": "Outbound TCP/TLS connect timeout in seconds." },
        "outboundBindAddress": { "type": "string", "access": "optional", "default": "\"\" (Auto)", "description": "Optional local source IP bind address." },
        "outboundUseStartTls": { "type": "boolean", "access": "optional", "default": "true", "description": "Use STARTTLS on outbound MX connections." },
        "requireOutboundTls": { "type": "boolean", "access": "optional", "default": "false", "description": "Abort delivery if remote MX does not offer TLS." },
        "outboundTlsCertValidation": { "type": "string", "access": "optional", "default": "Opportunistic", "enum": ["Opportunistic", "IgnoreErrors", "Strict"], "description": "Global outbound X.509 certificate validation mode." },
        "outboundSmartHost": { "type": "string", "access": "optional", "default": "\"\"", "description": "Optional global upstream relay host." },
        "outboundSmartPort": { "type": "integer", "access": "optional", "default": "587", "description": "Global smart-host TCP port." },
        "maxMessageSizeMb": { "type": "long", "access": "optional", "default": "50", "description": "Global ESMTP SIZE limit in MiB." },
        "maxRecipientsPerTransaction": { "type": "integer", "access": "optional", "default": "100", "description": "Maximum RCPT TO commands per transaction." },
        "maxConnectionsPerIp": { "type": "integer", "access": "optional", "default": "20", "description": "Maximum simultaneous inbound connections per IP." },
        "tarpitDelayMs": { "type": "integer", "access": "optional", "default": "1500", "description": "Tarpit delay in ms on auth/command errors." },
        "requireTlsForAuth": { "type": "boolean", "access": "optional", "default": "true", "description": "Requires TLS encryption before allowing SMTP AUTH." }
      }
    },
    "TransportRules & Server (Singletons)": {
      "category": "Singleton",
      "singleton": true,
      "primaryKey": "singleton",
      "minimumRole": "ServerAdmin",
      "properties": {
        "outboundDisclaimerEnabled": { "type": "boolean", "access": "optional", "default": "false", "description": "Appends mandatory corporate footer to outbound messages." },
        "outboundDisclaimerExternalOnly": { "type": "boolean", "access": "optional", "default": "true", "description": "Append footer only when sending to external domains." },
        "outboundDisclaimerText": { "type": "string", "access": "optional", "default": "\"\"", "description": "Plain-text legal footer." },
        "outboundDisclaimerHtml": { "type": "string", "access": "optional", "default": "\"\"", "description": "HTML legal footer." },
        "inboundSystemSieve": { "type": "string", "access": "optional", "default": "\"\"", "description": "Global RFC 5228 Sieve script executed before user scripts." },
        "autoBanThreshold": { "type": "integer", "access": "optional", "default": "8", "description": "Failed logins before automatic IP ban." },
        "autoBanDurationMinutes": { "type": "integer", "access": "optional", "default": "30", "description": "Automatic IP ban duration in minutes." },
        "serverHostName": { "type": "string", "access": "optional", "default": "mail.<domain>", "description": "Canonical EHLO, TLS, and Autodiscover FQDN (Object: Server)." },
        "storageProvider": { "type": "string", "access": "read-only", "default": "Sqlite | SqlServer | Postgres", "description": "Active storage engine (Object: Server)." },
        "activeQueueCount": { "type": "integer", "access": "read-only", "default": "0", "description": "Current outbound queue count (Object: Server)." },
        "licenseState": { "type": "string", "access": "read-only", "default": "EnterpriseActive", "description": "License state (Object: Server)." }
      }
    }
  }
}

1. HTTP REST Endpoints & Method Matrix (/api/admin/cli/* & /api/v1/send)

All endpoints accept Authorization: Bearer smk_<id>_<secret> or X-Api-Key: smk_<id>_<secret>. JSON property names use camelCase (case-insensitive on input).

Reference / Configuration

# A) Transaktionaler E-Mail-Versand (Rolle: User, TenantAdmin oder ServerAdmin)
POST   /api/v1/send                                  # Sendet E-Mail (JSON: from, to[], cc[], bcc[], subject, textBody, htmlBody, category, attachments[], headers{})
POST   /api/v1/unsubscribe/{token}                   # RFC 8058 One-Click-Unsubscribe (öffentlich, DKIM-signierter Token)

# B) Schema- & Objekt-Management-API hinter sharpmail-cli
GET    /api/admin/cli/schema                         # Liefert das vollständige JSON-Schema aller 12 Typen (Rolle: ComplianceAuditor+)
GET    /api/admin/cli/objects/{type}?filter=k=v      # Listet/filtert Objekte (Tenant, Domain, Account, Alias, ApiKey, Route, Singletons)
GET    /api/admin/cli/objects/{type}/{idOrName}      # Liest einzelnes Objekt per Name/E-Mail/Slug/GUID oder 'singleton'
POST   /api/admin/cli/objects/{type}                 # Erstellt neues Objekt (Tenant, Domain, Account, Alias, ApiKey, Route)
POST   /api/admin/cli/objects/Account/{User|List}    # Kurzform für Benutzerpostfach (Account/User) oder Verteilerliste (Account/List)
PATCH  /api/admin/cli/objects/{type}/{idOrName}      # Partielles Update einzelner Felder (0 ms Hot-Reload, für Singletons idOrName='singleton')
DELETE /api/admin/cli/objects/{type}/{idOrName}      # Löscht Alias/Route, widerruft ApiKey oder deaktiviert Domain/Account (Soft-Delete)

# C) Live-DNS, BIND-Zonenexport & Deklaratives GitOps (NDJSON)
GET    /api/admin/cli/dns/{domain}?live=true         # Prüft MX, SPF, Dual-DKIM, DMARC, MTA-STS & DANE TLSA live
GET    /api/admin/cli/dns/{domain}?format=bind       # Exportiert fertige RFC-1035-BIND-Zonendatei (text/plain)
GET    /api/admin/cli/snapshot?types=Domain,Account  # Exportiert idempotenten NDJSON-State-Snapshot (&includeSecrets=true für ServerAdmin)
POST   /api/admin/cli/apply?dryRun=true              # Prüft oder wendet deklarativen NDJSON-Plan an (HTTP 200 OK / 422 bei Zeilenfehler)

2. Complete JSON Schemas for the 6 Collection Objects (Tenant, Domain, Account, Alias, ApiKey, Route)

Exact JSON payloads for POST /api/admin/cli/objects/{type}, PATCH /api/admin/cli/objects/{type}/{idOrName}, and sharpmail-cli create/update --data @file.json.

Reference / Configuration

// 1) Tenant (Schlüssel: slug oder id · Mindestrolle: ServerAdmin)
{
  "slug": "acme",
  "name": "ACME Deutschland GmbH",
  "isActive": true,
  "maxDomains": 100,
  "maxPrincipals": 10000,
  "quotaGb": 250,
  "outboundDailyLimit": 25000,
  "defaultLockMode": "Compliance",     // Normal | Governance | Compliance | LegalHold
  "defaultRetentionDays": 3650
}

// 2) Domain (Schlüssel: name oder id · Mindestrolle: TenantAdmin)
{
  "name": "firma.de",
  "tenant": "default",
  "isActive": true,
  "postmasterAddress": "postmaster@firma.de",
  "dkimSigningMode": "Dual",           // Rsa2048 | Ed25519 | Dual
  "dkimRsaSelector": "s2026",
  "dkimEd25519Selector": "ed2026",
  "quotaGb": 100,
  "maxMessageSizeMb": 50,
  "maxAccounts": 1000,
  "outboundDailyLimit": 10000,
  "outboundHourlyLimit": 2000,
  "usePlusAddressing": true,
  "retentionLockMode": "Compliance",   // Normal | Governance | Compliance | LegalHold
  "retentionDays": 3650
}

// 3a) Account/User - Benutzerpostfach (Schlüssel: email oder id · Mindestrolle: TenantAdmin)
{
  "@type": "User",
  "email": "buchhaltung@firma.de",
  "displayName": "Buchhaltung & Einkauf",
  "password": "SicheresStartPasswort!2026",
  "role": "User",                      // User | ComplianceAuditor | TenantAdmin | ServerAdmin
  "isActive": true,
  "quotaMb": 15360,
  "outboundDailyLimit": 1000,
  "forwardAddress": null,
  "forwardKeepOriginal": true,
  "vacationEnabled": false,
  "vacationSubject": "Automatische Antwort: Abwesend",
  "vacationBody": "Vielen Dank für Ihre Nachricht."
}

// 3b) Account/List - Verteilerliste (Schlüssel: email oder id · Mindestrolle: TenantAdmin)
{
  "@type": "List",
  "email": "rechnung@firma.de",
  "displayName": "Rechnungseingang",
  "isActive": true,
  "members": ["buchhaltung@firma.de", "controlling@firma.de"]
}

// 4) Alias (Schlüssel: address · Mindestrolle: TenantAdmin)
{
  "address": "info@firma.de",
  "target": "buchhaltung@firma.de",
  "description": "Zentrale Kontaktadresse",
  "isMasked": false,
  "isEnabled": true
}

// 5) ApiKey (Nur create & delete · Mindestrolle: TenantAdmin)
{
  "label": "Shopware ERP Versand-Key",
  "role": "User",                      // User (nur /api/v1/send) | ComplianceAuditor | TenantAdmin | ServerAdmin
  "senderAddress": "rechnung@firma.de",
  "defaultCategory": "transactional",  // critical | transactional | notification | marketing
  "allowedCidrs": ["10.20.0.0/16", "198.51.100.25/32"],
  "expiresInDays": 180,
  "outboundDailyLimit": 10000
}

// 6) Route - Ausgehende Domain-Route & TLS-Zertifikats-Ausnahme (Schlüssel: domain · Mindestrolle: ServerAdmin)
{
  "domain": "neff.me",
  "targetHost": "",                    // Leer = Automatische DNS-MX-Auflösung (oder fester Relay-Host)
  "targetPort": 25,
  "tlsMode": "StartTlsIgnoreCert",     // StartTlsOptional | StartTlsRequired | StartTlsIgnoreCert | ImplicitTls | ImplicitTlsIgnoreCert | None
  "username": null,
  "password": null,
  "description": "Partner-MX mit RemoteCertificateNameMismatch (mailxch.com) erlauben",
  "enabled": true
}

3. Complete JSON Schemas for the 6 Singleton Policies (TransactionalSend, ReputationShield, SpamGuard, SmtpQueue, TransportRules, Server)

Singletons are updated via PATCH /api/admin/cli/objects/<Type>/singleton or sharpmail-cli update <Type>. Only the fields you wish to change need to be included.

Reference / Configuration

// 7) TransactionalSend (Singleton · Mindestrolle: TenantAdmin)
{
  "enabled": true,
  "warmingEnabled": true,
  "startAtWarmingDay": 1,
  "maxDeferHours": 48,
  "defaultCategory": "transactional",
  "preset": "warming_28d",             // Optional: warming_28d | warming_14d | production_100
  "categories": [
    { "slug": "critical", "displayName": "Kritisch (2FA / Auth)", "priority": 10, "bypassWarming": true, "shareOfProviderQuotaPercent": 100, "overflowAction": "DeferQueue" },
    { "slug": "transactional", "displayName": "Transaktional (Rechnung / Auftrag)", "priority": 5, "bypassWarming": false, "shareOfProviderQuotaPercent": 80, "overflowAction": "DeferQueue" },
    { "slug": "notification", "displayName": "Benachrichtigung", "priority": 2, "bypassWarming": false, "shareOfProviderQuotaPercent": 50, "overflowAction": "DeferQueue" },
    { "slug": "marketing", "displayName": "Marketing / Newsletter", "priority": 0, "bypassWarming": false, "shareOfProviderQuotaPercent": 35, "overflowAction": "Reject429" }
  ]
}

// 8) ReputationShield (Singleton · Mindestrolle: TenantAdmin)
{
  "preset": "recommended",             // Optional: off | recommended | strict_bulk
  "enableSuppressionPreCheck": true,
  "enforceSuppressionOnSmtpRelay": false,
  "allSuppressedBehavior": "reject_422", // reject_422 | accept_noop
  "autoSuppressHardBounces": true,
  "hardBounceSuppressionDays": 180,
  "autoSuppressConsecutiveSoftBounces": true,
  "softBounceEscalationThreshold": 5,
  "softBounceSuppressionDays": 14,
  "autoSuppressFblComplaints": true,
  "enableOneClickUnsubscribe": true,
  "oneClickUnsubscribeCategories": ["marketing", "notification"],
  "publicBaseUrl": "https://mail.firma.de",
  "enableBounceCircuitBreaker": true,
  "circuitBreakerMinSample": 50,
  "maxHardBouncePercent": 5.0,
  "maxComplaintPercent": 0.1,
  "allowCriticalWhenTripped": true,
  "enableAdaptiveIspBackoff": true,
  "ispCooldownMinutes": 15,
  "requireDkimConfiguredForApiSend": true,
  "enableSandboxSinkDomain": true,
  "sandboxSinkDomain": "sink.sharpmail.local",
  "webhookEnabled": false,
  "webhookUrl": "https://erp.firma.de/webhooks/mail-events",
  "webhookSecret": "whsec_..."
}

// 9) SpamGuard (Singleton · Mindestrolle: ServerAdmin)
{
  "enableEmailAuthChecks": true,
  "enableGreylisting": true,
  "greylistRetryDelaySeconds": 240,
  "junkScoreThreshold": 4.5,
  "rejectScoreThreshold": 9.0,
  "tagSubjectOnJunk": false,
  "subjectTagPrefix": "[SPAM] ",
  "enableStructuralHeuristics": true,
  "dnsblZones": ["zen.spamhaus.org", "bl.spamcop.net"],
  "dnsblHitScore": 3.5,
  "allowedSendersOrDomains": ["partner-bank.de"],
  "blockedSendersOrDomains": ["spam-sender.invalid"],
  "clamAvEnabled": false,
  "clamAvHost": "127.0.0.1",
  "clamAvPort": 3310
}

// 10) SmtpQueue (Singleton · Mindestrolle: ServerAdmin)
{
  "outboundQueuePaused": false,
  "outboundWorkerConcurrency": 8,
  "maxDeliveryAttempts": 10,
  "retryScheduleMinutes": [5, 15, 60, 240, 720],
  "maxConcurrentConnectionsPerMxDomain": 4,
  "strictThrottleDomains": ["gmail.com", "outlook.com", "hotmail.com", "yahoo.com", "t-online.de"],
  "strictThrottleMaxConcurrency": 2,
  "outboundConnectTimeoutSeconds": 30,
  "outboundUseStartTls": true,
  "requireOutboundTls": false,
  "outboundTlsCertValidation": "Opportunistic", // Opportunistic | IgnoreErrors | Strict
  "maxMessageSizeMb": 50,
  "maxRecipientsPerTransaction": 100,
  "sessionIdleTimeoutSeconds": 120,
  "maxConcurrentConnections": 500,
  "maxConnectionsPerIp": 20,
  "tarpitDelayMs": 1500,
  "requireTlsForAuth": true
}

// 11) TransportRules (Singleton · Mindestrolle: ServerAdmin)
{
  "outboundDisclaimerEnabled": false,
  "outboundDisclaimerExternalOnly": true,
  "outboundDisclaimerText": "-- \nFirma GmbH · Sitz: Stuttgart · HRB 12345",
  "outboundDisclaimerHtml": "<hr><p style='font-size:11px;color:#666'>Firma GmbH &middot; Sitz: Stuttgart &middot; HRB 12345</p>",
  "inboundSystemSieve": "",
  "autoBanThreshold": 8,
  "autoBanDurationMinutes": 30
}

// 12) Server (Singleton · Mindestrolle: ServerAdmin)
{
  "serverHostName": "mail.firma.de"
}

Settings, Default Values & Best Practices

Setting / Location	Description	Default Value	Production Best Practice
`POST /api/v1/send · from / to / cc / bcc`	from (string): Sender address (optional if Role=User key has a bound SenderAddress). to (string[], required): Recipients. cc / bcc (string[], optional): Carbon/blind copy recipients.	`Pflichtfeld: to[]`	Bind a fixed senderAddress to Role = User keys so the application can only send from its authorized address.
`POST /api/v1/send · subject / textBody / htmlBody`	subject (string): Message subject. textBody / text (string): Plain-text body. htmlBody / html (string): HTML body. At least one body part is required.	`UTF-8 Multipart/Alternative`	Always supply both textBody and htmlBody for optimal spam-filter reputation.
`POST /api/v1/send · category / overflowMode`	category (string): Selects priority & provider quota bucket (critical \| transactional \| notification \| marketing). overflowMode (string): DeferQueue or Reject429.	`category = transactional`	Use category = "critical" for 2FA/login codes (queue priority 10, bypasses IP warming & circuit breaker).
`POST /api/v1/send · attachments[] / headers{} / idempotencyKey`	attachments[]: Array of { fileName, contentType, base64Content }. headers{}: Custom headers dictionary. idempotencyKey (or Idempotency-Key header): 24h deduplication key.	`Deduplizierung: 24 Std.`	Pass your invoice or order number as Idempotency-Key so HTTP retries never send duplicate emails.
`Tenant · slug / name / isActive`	slug (string, key): Unique tenant identifier (e.g. default, acme). name (string): Organization display name. isActive (bool): Enable/suspend tenant. id (guid, read-only).	`isActive = true`	Role: ServerAdmin. Query via sharpmail-cli get Tenant acme or create via sharpmail-cli create Tenant --set slug=acme --set name="ACME Corp".
`Tenant · quotaGb / maxDomains / maxPrincipals / outboundDailyLimit`	quotaGb (long): Tenant storage ceiling in GiB. maxDomains (int): Max domains. maxPrincipals (int): Max accounts/lists. outboundDailyLimit (int): Daily outbound message cap.	`100 GiB · 100 Dom. · 25000/Tag`	Tenant ceilings strictly cap how much storage and how many mailboxes a delegated TenantAdmin can provision.
`Tenant · defaultLockMode / defaultRetentionDays`	defaultLockMode (Enum: Normal \| Governance \| Compliance \| LegalHold): Default WORM archive lock mode. defaultRetentionDays (int): Default retention days.	`Normal · 0 Tage`	Set to Compliance and defaultRetentionDays = 3650 for 10-year German GoBD tax compliance.
`Domain · name / tenant / isActive / postmasterAddress`	name (string, key): DNS domain name (e.g. company.com). tenant (string): Owning tenant slug or GUID. isActive (bool): Active flag. postmasterAddress (string): Postmaster address.	`postmaster@<domain>`	Role: TenantAdmin+. Creating a domain automatically generates both RSA-2048 and Ed25519 DKIM keypairs.
`Domain · dkimSigningMode / dkimRsaSelector / dkimEd25519Selector`	dkimSigningMode (Enum: Rsa2048 \| Ed25519 \| Dual): Active DKIM signing mode. dkimRsaSelector (string): RSA selector. dkimEd25519Selector (string): Ed25519 selector. dkimRsaDnsName / dkimEd25519DnsName (read-only).	`Dual · s2026 · ed2026`	Set dkimSigningMode = Dual to dual-sign every outbound message with both RSA-2048 and Ed25519 (RFC 8463).
`Domain · retentionLockMode / retentionDays / usePlusAddressing`	retentionLockMode (Enum: Normal \| Governance \| Compliance \| LegalHold): GoBD WORM mode. retentionDays (int): Retention days. usePlusAddressing (bool): Plus addressing user+tag@domain.	`Normal · PlusAddressing = true`	With retentionLockMode = Compliance and retentionDays = 3650, archived emails are cryptographically locked against deletion.
`Domain · quotaGb / maxMessageSizeMb / maxAccounts / outboundDailyLimit / outboundHourlyLimit`	quotaGb (long): Domain quota in GiB. maxMessageSizeMb (long): Max message size in MiB. maxAccounts (int): Max mailboxes. outboundDailyLimit / outboundHourlyLimit (int): Rate limits.	`50 GiB · 50 MiB · 5000/Tag`	Adjust limits live at any time via sharpmail-cli update Domain company.com --set quotaGb=200.
`Account · @type / email / displayName / password`	@type (Enum: User \| List): User mailbox (Account/User) or distribution list (Account/List). email (string, key): Primary email. displayName (string): Full name. password (string, write-only): Plaintext password (hashed via Argon2id).	`@type = User`	Creating Account/User automatically initializes all standard RFC 6154 Special-Use mailboxes.
`Account · role / isActive / twoFactorEnabled`	role (Enum: User \| ComplianceAuditor \| TenantAdmin \| ServerAdmin): RBAC role. isActive (bool): Account active flag. twoFactorEnabled (bool, read-only): Indicates active TOTP 2FA.	`role = User · isActive = true`	Only a ServerAdmin can assign role = ServerAdmin. Audit 2FA coverage via query Account --filter twoFactorEnabled=false.
`Account · quotaMb / usedBytes / outboundDailyLimit / members[]`	quotaMb (long): Mailbox quota in MiB. usedBytes (long, read-only): Current storage usage in bytes. outboundDailyLimit (int): Daily send limit. members (string[]): Member emails for Account/List.	`quotaMb = 5120 (5 GiB) · 500/Tag`	Create distribution lists via sharpmail-cli create Account/List --set email=team@company.com --set members=a@company.com,b@company.com.
`Account · forwardAddress / forwardKeepOriginal / vacationEnabled / vacationSubject / vacationBody`	forwardAddress (string): SRS-safe forwarding address. forwardKeepOriginal (bool): Keep local copy. vacationEnabled (bool): Out-of-office active. vacationSubject / vacationBody (string): Auto-reply subject & body.	`forwardKeepOriginal = true`	Enable out-of-office via CLI: sharpmail-cli update Account j.doe@company.com --set vacationEnabled=true --set forwardAddress=deputy@company.com.
`Alias · address / target / description / isMasked / isEnabled`	address (string, key): Alias email address. target (string): Target primary Account email. description (string): Purpose note. isMasked (bool): Masked privacy alias flag. isEnabled (bool): Enable/pause alias.	`isEnabled = true · isMasked = false`	Pause noisy aliases via --set isEnabled=false without releasing the address.
`ApiKey · label / role / senderAddress / defaultCategory`	label (string): Key description. role (Enum: User \| ComplianceAuditor \| TenantAdmin \| ServerAdmin): Scope. senderAddress (string): Authorized sender address (required for role=User). defaultCategory (string): Default category.	`role = TenantAdmin (CLI) / User (Send)`	The plaintext apiKey (smk_<id>_<secret>) is returned only once upon creation; store it immediately in your secret manager.
`ApiKey · allowedCidrs[] / expiresInDays / outboundDailyLimit`	allowedCidrs (string[]): Allowed source IPv4/IPv6 CIDRs. expiresInDays (int, write-only): Validity in days from creation. outboundDailyLimit (int): Daily send limit. expiresAtUtc (datetime, read-only).	`outboundDailyLimit = 10000`	API keys are immutable by design; rotate keys by creating a new key and revoking the old one via delete ApiKey <id>.
`Route · domain / targetHost / targetPort / tlsMode`	domain (string, key): Destination recipient domain (e.g. neff.me). targetHost (string): Relay host (leave blank for automatic DNS MX lookup!). targetPort (int): TCP port (25, 587, 465). tlsMode (Enum: StartTlsOptional \| StartTlsRequired \| StartTlsIgnoreCert \| ImplicitTls \| ImplicitTlsIgnoreCert \| None).	`Port 25 · StartTlsOptional`	For partner domains with a mismatched MX certificate (RemoteCertificateNameMismatch): leave targetHost empty and set tlsMode = StartTlsIgnoreCert.
`Route · username / password / clearPassword / description / enabled`	username (string): Smart-host SMTP AUTH user. password (string, write-only): SMTP AUTH password. hasPassword (bool, read-only). clearPassword (bool, write-only): Clear stored password. description (string): Audit note. enabled (bool): Route active.	`enabled = true`	Role: ServerAdmin. Remove custom routes at any time via sharpmail-cli delete Route <domain>.
`TransactionalSend (Singleton) · enabled / warmingEnabled / startAtWarmingDay / preset`	enabled (bool): Provider & category quotas active. warmingEnabled (bool): Progressive IP warming active. startAtWarmingDay (int, 1..365): Jump to warming day N. warmingDailyRampPercents (int[]): Daily ramp curve. preset (warming_28d \| warming_14d \| production_100).	`enabled = true · maxDeferHours = 48`	Apply a complete schedule in one command: sharpmail-cli update TransactionalSend --set preset=warming_28d.
`TransactionalSend (Singleton) · defaultCategory / maxDeferHours / categories[] / providers[]`	defaultCategory (string): Fallback category. maxDeferHours (int): Max defer lookahead hours. categories[]: Array of { slug, displayName, priority, bypassWarming, shareOfProviderQuotaPercent, overflowAction }. providers[]: Array of { id, displayName, domains[], hourlyLimit, dailyLimit, categoryOverrides, enabled }.	`5 Provider-Gruppen + Wildcard (*)`	Configure distinct hourly and daily limits for Google/Gmail, Microsoft, Yahoo/AOL, German ISPs, Apple iCloud, and per-domain wildcard (*) via providers[].
`ReputationShield (Singleton) · Suppression & Auto-Hygiene Felder`	enableSuppressionPreCheck (bool): Filter suppressed recipients pre-send. enforceSuppressionOnSmtpRelay (bool): Enforce on SMTP submission. allSuppressedBehavior (reject_422 \| accept_noop). autoSuppressHardBounces (bool), hardBounceSuppressionDays (int, default: 180). autoSuppressConsecutiveSoftBounces (bool), softBounceEscalationThreshold (int, default: 5), softBounceSuppressionDays (int, default: 14). autoSuppressFblComplaints (bool).	`Ab Werk: false (100 % optional)`	Run sharpmail-cli update ReputationShield --set preset=recommended to enable recommended reputation protection in one step.
`ReputationShield (Singleton) · One-Click-Unsubscribe, Circuit-Breaker, Backoff & Webhooks`	enableOneClickUnsubscribe (bool), oneClickUnsubscribeCategories (string[]), publicBaseUrl (string). enableBounceCircuitBreaker (bool), circuitBreakerMinSample (int: 50), maxHardBouncePercent (double: 5.0), maxComplaintPercent (double: 0.1), allowCriticalWhenTripped (bool: true). enableAdaptiveIspBackoff (bool), ispCooldownMinutes (int: 15). requireDkimConfiguredForApiSend (bool). enableSandboxSinkDomain (bool), sandboxSinkDomain (string: sink.sharpmail.local). webhookEnabled (bool), webhookUrl (string), webhookSecret (string, write-only), allowInternalWebhookUrls (bool). preset (off \| recommended \| strict_bulk).	`allowCriticalWhenTripped = true`	When webhookEnabled = true, SharpMailserver signs every bounce, complaint, and unsubscribe webhook payload with HMAC-SHA256 in X-SharpMail-Signature.
`SpamGuard (Singleton) · Alle 15 Konfigurationsfelder`	enableEmailAuthChecks (bool: true), enableGreylisting (bool: true), greylistRetryDelaySeconds (int: 240), junkScoreThreshold (double: 4.5), rejectScoreThreshold (double: 9.0), tagSubjectOnJunk (bool: false), subjectTagPrefix (string: "[SPAM] "), enableStructuralHeuristics (bool: true), dnsblZones (string[]), dnsblHitScore (double: 3.5), allowedSendersOrDomains (string[]), blockedSendersOrDomains (string[]), clamAvEnabled (bool: false), clamAvHost (string: "127.0.0.1"), clamAvPort (int: 3310). Read-only stats: trainedSpamCount, trainedHamCount, trackedGreylistTriplets.	`Junk: 4.5 · Reject: 9.0 · Greylist: 240s`	Add trusted domains to the allowlist via sharpmail-cli update SpamGuard --set allowedSendersOrDomains=partner1.com,partner2.com.
`SmtpQueue (Singleton) · Outbound-Queue, Worker, Throttling & TLS-Validierung`	outboundQueuePaused (bool: false), outboundWorkerConcurrency (int: 8), maxDeliveryAttempts (int: 10), retryScheduleMinutes (int[]: 5,15,60,240,720), maxConcurrentConnectionsPerMxDomain (int: 4), strictThrottleDomains (string[]), strictThrottleMaxConcurrency (int: 2), outboundConnectTimeoutSeconds (int: 30), outboundBindAddress (string), outboundUseStartTls (bool: true), requireOutboundTls (bool: false), outboundTlsCertValidation (Enum: Opportunistic \| IgnoreErrors \| Strict), outboundCustomRoutes (SmtpCustomRouteDto[]).	`outboundTlsCertValidation = Opportunistic`	Keep outboundTlsCertValidation = Opportunistic (RFC 7435) for Port 25 and manage domain-specific exceptions via the Route object.
`SmtpQueue (Singleton) · Globaler Smart-Host & Inbound-ESMTP-Limits`	outboundSmartHost (string), outboundSmartPort (int: 587), outboundSmartHostTlsMode (Enum: StartTlsOptional \| StartTlsRequired \| StartTlsIgnoreCert \| ImplicitTls \| None), outboundSmartHostUsername (string), outboundSmartHostPassword (string, write-only), clearSmartHostPassword (bool, write-only). Inbound limits: maxMessageSizeMb (long: 50), maxRecipientsPerTransaction (int: 100), sessionIdleTimeoutSeconds (int: 120), maxConcurrentConnections (int: 500), maxConnectionsPerIp (int: 20), tarpitDelayMs (int: 1500), requireTlsForAuth (bool: true).	`requireTlsForAuth = true · Tarpit: 1500 ms`	Never disable requireTlsForAuth so SMTP AUTH credentials are only accepted over encrypted TLS sessions.
`TransportRules (Singleton) · Pflicht-Signatur, System-Sieve & Fail2Ban`	outboundDisclaimerEnabled (bool: false), outboundDisclaimerExternalOnly (bool: true), outboundDisclaimerText (string), outboundDisclaimerHtml (string), inboundSystemSieve (string: global RFC 5228 Sieve script), autoBanThreshold (int: 8 failed logins), autoBanDurationMinutes (int: 30 minutes).	`autoBanThreshold = 8 · 30 Min.`	Use inboundSystemSieve to execute organization-wide compliance rules prior to personal user Sieve scripts.
`Server (Singleton) · serverHostName & Systemstatus-Felder`	serverHostName (string, writable): Canonical EHLO, TLS, and Autodiscover hostname. Read-only status fields: storageProvider (Sqlite \| SqlServer \| Postgres), activeQueueCount (int), licenseState (string), licensedMailboxes (int), activeUserMailboxes (int).	`Rolle: ServerAdmin`	One-line health check: sharpmail-cli get Server --json \| jq '{host: .serverHostName, queue: .activeQueueCount, license: .licenseState}'.