JA
無料で始める
第 14 章 クライアント、グループウェアと CLI 管理: #pApiAuth

API と CLI の完全なフィールド リファレンス: 全 12 オブジェクト タイプ、REST エンドポイントと POST /api/v1/send

このリファレンスでは、12 個すべての管理オブジェクト (/api/admin/cli/objects/{type} & nextxch-cli) とトランザクション メール配信 (POST /api/v1/send) について、すべての JSON プロパティ、データ型、列挙値、既定値、最小 RBAC ロールを記載しています。表の上にある即時フィルター ボックスで、dkimSigningMode、tlsMode、allowedCidrs、warmingEnabled などの任意のプロパティを検索できます。

運用のヒントとアーキテクチャに関する注記

ターミナルまたは HTTP でのライブ イントロスペクション: すべての nextxch は、この完全なスキーマを機械可読な JSON として GET /api/admin/cli/schema で公開します (SHA-256 ヘッダー X-Nextxch-Schema-Version 付き)。ターミナルでは、nextxch-cli describe <Type> (例: nextxch-cli describe Domain または nextxch-cli describe SmtpQueue) をいつでも実行できます。

⬇ schema.json ⬇ openapi.json
TransactionalSendRequest (POST /api/v1/send) 13 IntegrationKey (API v1) 9 CalendarEvent (API v1) 12 Rooms & Booking (API v1) 6 Contact, Directory & Sharing (API v1) 9 Webhook (API v1) 4 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
トランザクション配信

TransactionalSendRequest (POST /api/v1/send)

キー: Idempotency-Key RBAC: User+
13 個のプロパティ

Web アプリ、ERP、CRM、2FA コード向けの高スループット HTTP JSON 配信エンドポイント。カテゴリ優先度、IP ウォーミング、抑制リストの事前チェック、24 時間のべき等性を備えています。

POST /api/v1/send トランザクション メールをキューに登録して署名します (UTF-8 Multipart/Alternative + 添付ファイル)
POST /api/v1/unsubscribe/{token} 公開 RFC 8058 ワンクリック配信停止エンドポイント (DKIM 署名付きトークン)
{ } オブジェクト スキーマ & 型付きプロパティ application/json · camelCase
├─ from string 任意
既定値: Key senderAddress
送信者アドレス。Role=User のキーでは、キーに紐付いた senderAddress が自動的に既定値になります。
├─ to string[] 必須
主要な受信者のメール アドレスの配列 (1 件以上必須)。
├─ cc string[] 任意
既定値: []
オプションの CC 受信者。
├─ bcc string[] 任意
既定値: []
オプションの BCC 受信者。
├─ replyTo string 任意
オプションの Reply-To アドレス。
├─ subject string 必須
メールの件名 (UTF-8)。
├─ textBody string 任意
プレーン テキスト本文 (text/plain)。textBody または htmlBody の少なくとも一方が必須です。
├─ htmlBody string 任意
HTML 本文 (text/html)。10/10 の到達率を得るには textBody と併せて指定してください。
├─ category string 任意
既定値: transactional
キューの優先度、IP ウォーミングのバイパス、受信側プロバイダーのクォータ バケットを選択します。
Enum:"critical""transactional""notification""marketing"
├─ overflowMode string 任意
既定値: DeferQueue
宛先プロバイダーの時間あたりクォータに達した場合の動作 (キューによる平滑な送信ペース調整、または HTTP 429 + Retry-After)。
Enum:"DeferQueue""Reject429"
├─ idempotencyKey string 任意
既定値: Header Idempotency-Key
24 時間以内の重複送信を防ぐ決定的な重複排除キー (例: 請求書 ID)。
├─ headers Record<string, string> 任意
既定値: {}
カスタム RFC 5322 X ヘッダーのディクショナリ。
├─ attachments SendAttachmentDto[] 任意
既定値: []
{ 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:
nextxch-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.nextxch.local | bounce@sink.nextxch.local | defer@sink.nextxch.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 オブジェクト (CRUD)

IntegrationKey (API v1)

キー: id RBAC: TenantAdmin+
9 つのプロパティ

/api/v1 用のスコープ付き連携キー。キーは 1 人のユーザーとして、またはテナント連携として X-Nextxch-Act-As ヘッダーで指定されたユーザーとして動作します。スコープがない場合、API は 403 を返し、他テナントのユーザーの場合は 404 を返します。オプションで OAuth 2.0 クライアント資格情報 (トークンの有効期間は 1 時間) を利用できます。

POST /api/admin/integrations/keys キーを作成 (管理者、一度だけ表示)
PUT /api/admin/integrations/keys/{id} スコープを変更
DELETE /api/admin/integrations/keys/{id} キー (およびその OAuth トークン) を取り消す
POST /api/v1/oauth/token OAuth 2.0 client_credentials: キー ID + キーでアクセス トークンを取得
GET /api/v1/me キー、スコープ、実行ユーザー
GET /api/v1/openapi.json インストール環境の OpenAPI 3.1 ドキュメント
{ } オブジェクト スキーマ & 型付きプロパティ application/json · camelCase
├─ label string 必須
ラベル (例: CRM、ERP)。
├─ mode string 必須
既定値: user
user: 常に userEmail として動作します。tenant: X-Nextxch-Act-As として動作します (自テナントのユーザーのみ)。
Enum:"user""tenant"
├─ userEmail string 任意
mode=user の場合のユーザー。
├─ scopes string[] 必須
権限。.write は .read を含みます。crypto.read と crypto.manage (S/MIME、PGP) は予約済みです。
Enum:"calendar.read""calendar.write""rooms.read""booking.read""booking.write""contacts.read""contacts.write""directory.read""sharing.manage""webhooks.manage""mail.send"
├─ domainId guid 任意
このドメインのユーザーに限定されたテナント統合。
├─ allowedCidrs string[] 任意
既定値: []
許可する IP ネットワーク。
├─ expiresInDays integer 任意
有効期限 (日数、空欄: 無制限)。
├─ senderAddress string 任意
mail.send (POST /api/v1/send) の送信者。
├─ apiKey string 読み取り専用
smk_<id>_<secret>。作成時の応答でのみ返され、保存されるのはハッシュのみです。
{
  "label": "CRM",
  "mode": "tenant",
  "scopes": ["calendar.write", "rooms.read", "contacts.write", "webhooks.manage"],
  "allowedCidrs": ["203.0.113.0/24"],
  "expiresInDays": 365
}
# Integrations-Schlüssel: Admin > API & Integrationen > Neuer Schlüssel
# Danach z. B. ein Access-Token per OAuth 2.0 Client Credentials holen:
curl -fsS -X POST "https://mail.firma.de/api/v1/oauth/token" \
  -d grant_type=client_credentials \
  -d client_id=0196c3a2-5f1e-7c11-9a20-1c2d3e4f5a6b \
  -d client_secret=smk_0196c3a25f1e7c119a201c2d3e4f5a6b_... \
  -d scope="calendar.read rooms.read"
curl -fsS "https://mail.firma.de/api/v1/me" \
  -H "Authorization: Bearer smk_0196c3a2..." \
  -H "X-Nextxch-Act-As: anna@firma.de"
using var http = new HttpClient { BaseAddress = new Uri("https://mail.firma.de") };
http.DefaultRequestHeaders.Authorization = new("Bearer", "smk_0196c3a2...");
http.DefaultRequestHeaders.Add("X-Nextxch-Act-As", "anna@firma.de");
var me = await http.GetFromJsonAsync<JsonElement>("/api/v1/me");
Collection オブジェクト (CRUD)

CalendarEvent (API v1)

キー: hrefName RBAC: User+
12 個のプロパティ

定期的な予定と例外、出席者、会議室、招待、返答、空き時間情報、共有カレンダーとグローバル カレンダー、招待リンク。スコープは calendar.read と calendar.write。時刻は UTC (ISO-8601)、タイム ゾーンは IANA 名で指定します。

GET /api/v1/calendars 個人、共有、グローバル、リソースのカレンダー
GET /api/v1/calendar/events?from&to&calendarId&limit&cursor 期間内の発生 (展開されたシリーズ)
POST /api/v1/calendar/events 予定を作成 (ユーザーと会議室を招待)
GET /api/v1/calendar/events/{hrefName} 定期的な予定と例外を含む予定
PUT /api/v1/calendar/events/{hrefName} 変更。シリーズの一部には scope=occurrence|following
DELETE /api/v1/calendar/events/{hrefName} 削除します。必要に応じてキャンセル通知付き (notify=true)
POST /api/v1/calendar/events/{hrefName}/respond 招待に返信
POST /api/v1/calendar/events/{hrefName}/invite-link 署名付き招待リンク
GET /api/v1/calendar/events/{hrefName}/ics 生の iCalendar
POST /api/v1/calendar/freebusy ユーザーと会議室の空き時間情報
{ } オブジェクト スキーマ & 型付きプロパティ application/json · camelCase
├─ title string 必須
タイトル。
├─ startUtc datetime 必須
開始 (UTC)。
├─ endUtc datetime 必須
終了 (UTC)。
├─ timeZone string 任意
既定値: Europe/Berlin
予定の IANA タイム ゾーン (シリーズ、表示)。
├─ allDay boolean 任意
既定値: false
終日。
├─ attendees Attendee[] 任意
既定値: []
{ email, name, role }。会議室とリソースは、それぞれのルールに従って承諾または辞退します。
├─ sendInvitations boolean 任意
既定値: false
iMIP 招待を送信します。
├─ recurrence 繰り返し 任意
{ freq, interval, byDay, byMonthDay, count, until }。
├─ showAs string 任意
既定値: busy
表示方法。
Enum:"free""tentative""busy""oof""workingElsewhere"
├─ isPrivate boolean 任意
既定値: false
非公開 (詳細は所有者のみに表示)。
├─ calendarId string 任意
書き込み権限のある対象カレンダー ownerId:slug。
├─ teamsMeeting boolean 任意
Microsoft Teams 会議を作成します。
{
  "title": "Projektstart",
  "startUtc": "2026-12-03T09:00:00Z",
  "endUtc": "2026-12-03T10:00:00Z",
  "timeZone": "Europe/Berlin",
  "attendees": [
    { "email": "bernd@firma.de" },
    { "email": "raum-1@firma.de" }
  ],
  "sendInvitations": true
}
# Benötigte Scopes: calendar.read (lesen), calendar.write (schreiben)
# Einen Raum buchen: Raumadresse als Teilnehmer eintragen
curl -fsS -X POST "https://mail.firma.de/api/v1/calendar/events" \
  -H "Authorization: Bearer smk_0196c3a2..." \
  -H "X-Nextxch-Act-As: anna@firma.de" \
  -H "Content-Type: application/json" \
  -d '{"title":"Projektstart","startUtc":"2026-12-03T09:00:00Z","endUtc":"2026-12-03T10:00:00Z","timeZone":"Europe/Berlin","attendees":[{"email":"raum-1@firma.de"}]}'
var res = await http.PostAsJsonAsync("/api/v1/calendar/events", new
{
    title = "Projektstart",
    startUtc = DateTimeOffset.Parse("2026-12-03T09:00:00Z"),
    endUtc = DateTimeOffset.Parse("2026-12-03T10:00:00Z"),
    timeZone = "Europe/Berlin",
    attendees = new[] { new { email = "raum-1@firma.de" } }
});
string href = (await res.Content.ReadFromJsonAsync<JsonElement>()).GetProperty("data").GetProperty("hrefName").GetString()!;
Collection オブジェクト (CRUD)

Rooms & Booking (API v1)

キー: id RBAC: User+
6 つのプロパティ

空き状況付きの会議室とリソース (rooms.read)、Calendly のような予約ページ (booking.read、booking.write): 予約ページ、予定の種類、空き枠、予約の読み取りとキャンセル。会議室は、その会議室を出席者とする予定を通じて予約されます。

GET /api/v1/rooms?startUtc&endUtc&category 会議室とリソース、期間内の空き状況付き
GET /api/v1/rooms/{email}/availability 1 つの会議室の予定あり時間
GET /api/v1/booking/profile 受付時間と予定の種類を備えた予約ページ
GET /api/v1/booking/event-types イベントの種類
POST /api/v1/booking/event-types 予定タイプを作成
GET /api/v1/booking/event-types/{id}/slots?from&to 空いている開始時刻 (最大 42 日)
GET /api/v1/booking/bookings?status&from&to 予約
POST /api/v1/booking/bookings/{id}/cancel 予約をキャンセル (ゲストに通知されます)
{ } オブジェクト スキーマ & 型付きプロパティ application/json · camelCase
├─ slots[].startUtc datetime 読み取り専用
空き時間の開始 (UTC)。
├─ slots[].endUtc datetime 読み取り専用
終了 (開始 + 期間)。
├─ slots[].staff object[] 読み取り専用
チーム予定タイプの空いているスタッフ。
├─ status string 読み取り専用
予約ステータス。
Enum:"confirmed""cancelled"
├─ guest object 読み取り専用
{ name, email, phone, timeZone }。
├─ free boolean 読み取り専用
指定時間帯に会議室が空いています。
{
  "ok": true,
  "data": {
    "eventTypeId": "beratung-3f2a",
    "durationMinutes": 30,
    "timeZone": "Europe/Berlin",
    "slots": [
      { "startUtc": "2026-12-04T08:00:00Z", "endUtc": "2026-12-04T08:30:00Z", "staff": [] }
    ]
  }
}
# Benötigte Scopes: rooms.read, booking.read, booking.write
curl -fsS "https://mail.firma.de/api/v1/rooms?startUtc=2026-12-03T09:00:00Z&endUtc=2026-12-03T10:00:00Z" \
  -H "Authorization: Bearer smk_0196c3a2..."
var slots = await http.GetFromJsonAsync<JsonElement>("/api/v1/booking/event-types/beratung/slots");
foreach (var s in slots.GetProperty("data").GetProperty("slots").EnumerateArray())
    Console.WriteLine(s.GetProperty("startUtc").GetString());
Collection オブジェクト (CRUD)

Contact, Directory & Sharing (API v1)

キー: hrefName RBAC: User+
9 つのプロパティ

すべてのフィールドと写真を備えた個人の連絡先 (contacts.read、contacts.write、競合防止のための If-Match)、グローバル アドレス一覧 (directory.read)、共有と委任 (sharing.manage、委任 = sendAs または sendOnBehalf 付きのメールボックス許可)。

GET /api/v1/contacts?q 連絡先を検索
POST /api/v1/contacts 連絡先を作成
PUT /api/v1/contacts/{hrefName} 連絡先を変更 (null のフィールドは維持)
DELETE /api/v1/contacts/{hrefName} 連絡先を削除
GET /api/v1/directory?q&type グローバル アドレス一覧
GET /api/v1/sharing/grants 自分の許可
PUT /api/v1/sharing/grants 許可を設定または削除します
GET /api/v1/sharing/shared-with-me 共有されたアイテム
{ } オブジェクト スキーマ & 型付きプロパティ application/json · camelCase
├─ givenName string 任意
名。
├─ familyName string 任意
姓。
├─ organization string 任意
会社。
├─ emails TypedValue[] 任意
既定値: []
{ type: work|home|other, value }。
├─ phones TypedValue[] 任意
既定値: []
{ type: cell|work|home|fax, value }。
├─ addresses Address[] 任意
既定値: []
{ type, street, city, region, postalCode, country }。
├─ birthday string 任意
yyyy-MM-dd または --MM-dd。
├─ photo string 書き込み専用 (シークレット)
data:image/jpeg;base64,... (最大 512 KB)、空にすると削除されます。
├─ permissions string[] 任意
付与の権限 (PUT /sharing/grants)。
Enum:"freeBusy""read""write""delete""sendOnBehalf""sendAs""manage"
{
  "givenName": "Clara",
  "familyName": "Kunde",
  "organization": "Kunde AG",
  "emails": [{ "type": "work", "value": "clara@kunde.example" }],
  "phones": [{ "type": "cell", "value": "+49 170 1234567" }]
}
# Benötigte Scopes: contacts.read, contacts.write, directory.read, sharing.manage
curl -fsS -X POST "https://mail.firma.de/api/v1/contacts" \
  -H "Authorization: Bearer smk_0196c3a2..." \
  -H "Content-Type: application/json" \
  -d '{"givenName":"Clara","familyName":"Kunde","emails":[{"type":"work","value":"clara@kunde.example"}]}'
await http.PutAsJsonAsync("/api/v1/sharing/grants", new
{
    kind = "calendar", granteeType = "user", grantee = "bernd@firma.de", permissions = new[] { "read" }
});
Collection オブジェクト (CRUD)

Webhook (API v1)

キー: id RBAC: User+
4 つのプロパティ

署名付き JSON POST として送信されるイベント: calendar.event.created、calendar.event.updated、calendar.event.deleted、calendar.invitation.replied、booking.created、booking.rescheduled、booking.cancelled。署名 X-Nextxch-Signature: v1=hex(HMAC-SHA256(secret, X-Nextxch-Timestamp + "." + body))。再試行は 30 秒、2 分、10 分、1 時間、6 時間後です。

GET /api/v1/webhooks テナントの Webhook
POST /api/v1/webhooks Webhook を登録 (シークレットは応答時のみ)
DELETE /api/v1/webhooks/{id} Webhook を削除
GET /api/v1/webhooks/{id}/deliveries 最近の配信
POST /api/v1/webhooks/{id}/test テスト イベントを送信
{ } オブジェクト スキーマ & 型付きプロパティ application/json · camelCase
├─ url string 必須
HTTPS ターゲット (内部アドレスはブロックされます)。
├─ events string[] 必須
予定。キーには対応する .read スコープが必要です。
Enum:"calendar.event.created""calendar.event.updated""calendar.event.deleted""calendar.invitation.replied""booking.created""booking.rescheduled""booking.cancelled""*"
├─ secret string 読み取り専用
whsec_...、作成時のみ表示。暗号化して保存されます。
├─ id (Ereignis) string 読み取り専用
evt_... 変更ごとに一定で、重複排除に使用します。
{
  "id": "evt_5c1f0e9a2b7d4c3e8f601a2b",
  "type": "calendar.invitation.replied",
  "createdAtUtc": "2026-12-01T10:15:02Z",
  "tenantId": "0196c3a2-0000-7000-8000-000000000001",
  "data": {
    "calendarId": "0196c3a25f1e7c11:default",
    "hrefName": "0196c3a2@nextxch.ics",
    "title": "Projektstart",
    "startUtc": "2026-12-03T09:00:00Z",
    "attendee": { "email": "bernd@firma.de", "partStat": "ACCEPTED" }
  }
}
# Signatur prüfen (Bash):
# expected="v1=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | cut -d' ' -f2)"
curl -fsS -X POST "https://mail.firma.de/api/v1/webhooks" \
  -H "Authorization: Bearer smk_0196c3a2..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://crm.firma.de/hooks/nextxch","events":["calendar.event.created","booking.created"]}'
// ASP.NET Core receiver
app.MapPost("/hooks/nextxch", async (HttpRequest req) =>
{
    using var ms = new MemoryStream();
    await req.Body.CopyToAsync(ms);
    string ts = req.Headers["X-Nextxch-Timestamp"]!;
    byte[] mac = HMACSHA256.HashData(Encoding.UTF8.GetBytes(secret), [.. Encoding.ASCII.GetBytes(ts + "."), .. ms.ToArray()]);
    return req.Headers["X-Nextxch-Signature"] == "v1=" + Convert.ToHexStringLower(mac) ? Results.Ok() : Results.Unauthorized();
});
Collection オブジェクト (CRUD)

Tenant

キー: slug RBAC: ServerAdmin+
11 個のプロパティ

ドメイン、プリンシパル、ストレージ クォータ (GiB)、既定の GoBD WORM コンプライアンス保持を分離するマルチテナント組織の境界です。

GET /api/admin/cli/objects/Tenant すべてのテナントを一覧表示します
GET /api/admin/cli/objects/Tenant/{slugOrId} slug または UUID でテナントを取得します
POST /api/admin/cli/objects/Tenant 新しいテナントを作成します
PATCH /api/admin/cli/objects/Tenant/{slugOrId} テナントのクォータをその場で更新します
{ } オブジェクト スキーマ & 型付きプロパティ application/json · camelCase
├─ id guid 読み取り専用
既定値: UUIDv7
内部の変更不可な UUIDv7 識別子。
├─ slug string PRIMARY KEY
一意で URL セーフなテナント キー (例: "default"、"acme")。
├─ name string 必須
人が読める組織の表示名。
├─ isActive boolean 任意
既定値: true
テナントを有効化または一時停止します。
├─ maxDomains integer 任意
既定値: 100
このテナントで許可される最大ドメイン数。
├─ maxPrincipals integer 任意
既定値: 10000
最大アカウント数と配布リスト数。
├─ quotaGb integer 任意
既定値: 100
テナントのストレージ上限 (GiB)。
├─ outboundDailyLimit integer 任意
既定値: 25000
テナント全体での 1 日あたりの最大送信メール数。
├─ defaultLockMode string 任意
既定値: Normal
新規作成されるドメインの既定の GoBD WORM ロック モード。
Enum:"Normal""Governance""Compliance""LegalHold"
├─ defaultRetentionDays integer 任意
既定値: 0
既定の必須保持期間 (日数、3650 = GoBD の 10 年)。
├─ createdAtUtc datetime 読み取り専用
作成日時 (UTC)。
{
  "slug": "acme",
  "name": "ACME Logistik GmbH",
  "isActive": true,
  "maxDomains": 50,
  "maxPrincipals": 2500,
  "quotaGb": 250,
  "outboundDailyLimit": 25000,
  "defaultLockMode": "Compliance",
  "defaultRetentionDays": 3650
}
# Mandant anlegen:
nextxch-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:
nextxch-cli get Tenant acme
nextxch-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 オブジェクト (CRUD)

Domain

キー: name RBAC: TenantAdmin+
19 プロパティ

Dual-DKIM キー (RSA-2048 + Ed25519) の自動並行生成、GoBD WORM 保持ポリシー、プラス アドレス指定、レート制限を備えたホスト型メール ドメイン。

GET /api/admin/cli/objects/Domain すべてのドメインを一覧表示します
GET /api/admin/cli/objects/Domain/{name} ドメイン構成 & DKIM セレクターを取得します
POST /api/admin/cli/objects/Domain ドメインを作成し、RSA-2048 + Ed25519 の DKIM キーを生成します
PATCH /api/admin/cli/objects/Domain/{name} DKIM モード、クォータ、保持を 0 ms で更新します
GET /api/admin/cli/dns/{name}?live=true ライブ DNS レコードを検証するか、RFC 1035 BIND ゾーンをエクスポートします
{ } オブジェクト スキーマ & 型付きプロパティ application/json · camelCase
├─ id guid 読み取り専用
既定値: UUIDv7
内部ドメイン UUIDv7。
├─ name string PRIMARY KEY
DNS ドメイン名 (例: "muster-logistik.de")。
├─ tenant string 任意
既定値: default
所有するテナントのスラッグまたは GUID。
├─ isActive boolean 任意
既定値: true
ドメインを有効化または一時停止します。
├─ postmasterAddress string 任意
既定値: postmaster@<name>
RFC 5321 の postmaster 連絡先アドレス。
├─ dkimSigningMode string 任意
既定値: Dual
有効な DKIM 署名モード (Dual は RSA-2048 と Ed25519 の両方で署名)。
Enum:"Rsa2048""Ed25519""Dual"
├─ dkimRsaSelector string 任意
既定値: s2026
RSA-2048 の DNS セレクター。
├─ dkimRsaDnsName string 読み取り専用
既定値: s2026._domainkey.<name>
算出された RSA-2048 _domainkey の FQDN。
├─ dkimEd25519Selector string 任意
既定値: ed2026
Ed25519 の DNS セレクター。
├─ dkimEd25519DnsName string 読み取り専用
既定値: ed2026._domainkey.<name>
計算された Ed25519 の _domainkey FQDN。
├─ retentionLockMode string 任意
既定値: Normal
このドメインの GoBD WORM アーカイブ ロック モード。
Enum:"Normal""Governance""Compliance""LegalHold"
├─ retentionDays integer 任意
既定値: 0
必須の保持期間 (日数、3650 = GoBD の 10 年)。
├─ quotaGb integer 任意
既定値: 50
ドメインのストレージ上限 (GiB)。
├─ maxMessageSizeMb integer 任意
既定値: 50
最大メッセージ サイズ (MiB)。
├─ maxAccounts integer 任意
既定値: 1000
このドメインの最大メールボックス数。
├─ outboundDailyLimit integer 任意
既定値: 5000
このドメインの 1 日あたりの送信上限。
├─ outboundHourlyLimit integer 任意
既定値: 1000
このドメインの時間あたりの送信上限。
├─ usePlusAddressing boolean 任意
既定値: true
RFC 5233 のプラス アドレス (user+tag@domain) を有効にします。
├─ createdAtUtc datetime 読み取り専用
作成日時 (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:
nextxch-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:
nextxch-cli dns muster-logistik.de --bind > muster-logistik.de.zone
nextxch-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 オブジェクト (CRUD)

Account (Account/User & Account/List)

キー: email RBAC: TenantAdmin+
18 のプロパティ

ユーザー メールボックス (@type="User"、IMAP/JMAP/CalDAV/CardDAV/ActiveSync 対応) または配布リスト (@type="List"、members[] 付き) を表します。

GET /api/admin/cli/objects/Account?filter=role=TenantAdmin アカウントと配布リストを一覧表示/フィルターします
POST /api/admin/cli/objects/Account/User RFC 6154 フォルダーを備えた新しいユーザー メールボックスを作成します
POST /api/admin/cli/objects/Account/List 新しい配布リストを作成します
PATCH /api/admin/cli/objects/Account/{email} クォータ、転送、自動応答、パスワードを更新します
DELETE /api/admin/cli/objects/Account/{email} アカウントを論理削除します
{ } オブジェクト スキーマ & 型付きプロパティ application/json · camelCase
├─ id guid 読み取り専用
既定値: UUIDv7
内部プリンシパル UUIDv7。
├─ @type string 任意
既定値: User
アカウントの種類: User (メールボックス) または List (配布グループ)。
Enum:"User""List"
├─ email string PRIMARY KEY
メールボックスまたはリストのプライマリ メール アドレス。
├─ displayName string 任意
既定値: Lokalteil
Webmail、GAL、From ヘッダーに表示される表示名。
├─ password string 書き込み専用 (シークレット)
作成/更新時のプレーン テキスト パスワード (Argon2id で即座にハッシュ化)。
├─ role string 任意
既定値: User
管理用の RBAC ロール。
Enum:"User""ComplianceAuditor""TenantAdmin""ServerAdmin"
├─ isActive boolean 任意
既定値: true
アカウントを有効化または一時停止します。
├─ quotaMb integer 任意
既定値: 5120
メールボックスのストレージ クォータ (MiB 単位、5120 = 5 GiB)。
├─ usedBytes long 読み取り専用
既定値: 0
現在のメールボックスのストレージ使用量 (バイト)。
├─ outboundDailyLimit integer 任意
既定値: 500
このアカウントの 1 日あたりの送信メッセージ上限。
├─ forwardAddress string 任意
オプションの SRS 対応転送先メール アドレス。
├─ forwardKeepOriginal boolean 任意
既定値: true
転送が有効な場合に、INBOX にローカル コピーを保持します。
├─ vacationEnabled boolean 任意
既定値: false
自動応答を有効にします。
├─ vacationSubject string 任意
自動応答 (不在時) の件名。
├─ vacationBody string 書き込み専用 (シークレット)
自動応答 (不在時) の本文テキスト。
├─ twoFactorEnabled boolean 読み取り専用
既定値: false
TOTP 2FA が有効かどうかを示します。
├─ members string[] 任意
既定値: []
メンバーのメール アドレス (@type="List" の場合)。
├─ createdAtUtc datetime 読み取り専用
作成日時 (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:
nextxch-cli create Account/User \
  --set email=anna.weber@muster-logistik.de \
  --set displayName="Anna Weber" \
  --set password="SicheresStartPasswort!2026" \
  --set quotaMb=15360

# Verteilerliste anlegen:
nextxch-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 オブジェクト (CRUD)

Alias

キー: address RBAC: TenantAdmin+
7 プロパティ

プライマリ アカウントのメールボックスまたは配布リストにルーティングされる、セカンダリ メール エイリアスまたは使い捨てのプライバシー保護用マスク エイリアス。

GET /api/admin/cli/objects/Alias すべてのエイリアスとマスクされたメールを一覧表示します
POST /api/admin/cli/objects/Alias 対象メールボックスにルーティングされる新しいエイリアスを作成します
PATCH /api/admin/cli/objects/Alias/{address} エイリアスを有効化/一時停止するか、転送先を更新します
DELETE /api/admin/cli/objects/Alias/{address} エイリアスを削除します
{ } オブジェクト スキーマ & 型付きプロパティ application/json · camelCase
├─ address string PRIMARY KEY
エイリアスのメール アドレス。
├─ target string 必須
転送先のプライマリ アカウントのメール アドレス。
├─ principalId guid 読み取り専用
解決された対象プリンシパルの UUID。
├─ description string 任意
既定値: ""
用途のメモまたは外部サービスのラベル (Webmail の作成画面にも表示されます)。
├─ isMasked boolean 任意
既定値: false
このエイリアスをマスクされたプライバシー エイリアスとしてマークします。
├─ isEnabled boolean 任意
既定値: true
false の場合、このエイリアス宛てのメールはアドレスを解放せずに拒否されます。
├─ createdAtUtc datetime 読み取り専用
作成日時 (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:
nextxch-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:
nextxch-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 オブジェクト (CRUD)

ApiKey

キー: id RBAC: TenantAdmin+
11 個のプロパティ

/api/v1/send、SCIM 2.0、nextxch-cli 向けの、変更不可で RBAC と CIDR により制限されたスコープ付き API キー (smk_<id>_<secret>)。

GET /api/admin/cli/objects/ApiKey 有効な API キーを一覧表示します (シークレットは除外)
POST /api/admin/cli/objects/ApiKey 新しい API キーを発行し、apiKey (smk_...) を 1 回だけ返します
DELETE /api/admin/cli/objects/ApiKey/{id} API キーを直ちに取り消します
{ } オブジェクト スキーマ & 型付きプロパティ application/json · camelCase
├─ id guid 読み取り専用
既定値: UUIDv7
一意のキー UUID (DELETE による失効に使用)。
├─ apiKey string 作成時のみ
既定値: smk_<id>_<secret>
完全な Bearer トークンは作成時に 1 回だけ返されます。
├─ label string 必須
人が読めるラベル (例: "Ansible GitOps" または "Shopware 6")。
├─ role string 任意
既定値: TenantAdmin
権限スコープ (User は POST /api/v1/send のみに厳格に制限されます)。
Enum:"User""ComplianceAuditor""TenantAdmin""ServerAdmin"
├─ senderAddress string 任意
許可された送信者アドレス (role="User" の場合は必須)。
├─ defaultCategory string 任意
既定値: transactional
このキーの既定の送信カテゴリ。
Enum:"critical""transactional""notification""marketing"
├─ allowedCidrs string[] 任意
既定値: [] (Alle IPs)
許可する送信元の IPv4/IPv6 CIDR ネットワーク。
├─ expiresInDays integer 書き込み専用 (シークレット)
既定値: null (Kein Ablauf)
作成からの日数によるオプションの自動有効期限。
├─ expiresAtUtc datetime 読み取り専用
算出された UTC の有効期限タイムスタンプ。
├─ outboundDailyLimit integer 任意
既定値: 10000
このキーの 1 日あたりの送信上限。
├─ isActive boolean 読み取り専用
既定値: true
有効状態。
{
  "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 / nextxch-cli erstellen:
nextxch-cli create ApiKey \
  --set label="GitLab CI / Ansible" \
  --set role=TenantAdmin \
  --set allowedCidrs=10.20.0.0/16 \
  --set expiresInDays=90

# Schlüssel widerrufen:
nextxch-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 オブジェクト (CRUD)

Route

キー: domain RBAC: ServerAdmin+
10 個のプロパティ

ドメインごとの送信 SMTP ルーティングまたは TLS 証明書の例外 (例: 証明書が一致しないパートナー MX ホスト向けの StartTlsIgnoreCert、またはスマート ホスト コネクタ)。

GET /api/admin/cli/objects/Route すべてのカスタム送信ルートを一覧表示します
POST /api/admin/cli/objects/Route カスタム ドメイン ルートまたは TLS オーバーライドを作成します
PATCH /api/admin/cli/objects/Route/{domain} ターゲット ホスト、ポート、または TLS モードを更新します
DELETE /api/admin/cli/objects/Route/{domain} カスタム ルートを削除します
{ } オブジェクト スキーマ & 型付きプロパティ application/json · camelCase
├─ domain string PRIMARY KEY
宛先の受信者ドメイン (例: "neff.me" または "*.partner-holding.eu")。
├─ targetHost string 任意
既定値: "" (Auto DNS-MX)
リレーのホスト名または IP。空のままにすると、宛先の MX を DNS で自動的に解決します。
├─ targetPort integer 任意
既定値: 25
宛先 TCP ポート (25、587、または 465)。
├─ tlsMode string 任意
既定値: StartTlsOptional
このドメインの送信 TLS と X.509 検証モード。
Enum:"StartTlsOptional""StartTlsRequired""StartTlsIgnoreCert""ImplicitTls""ImplicitTlsIgnoreCert""None"
├─ username string 任意
オプションの SMTP AUTH ユーザー名。
├─ password string 書き込み専用 (シークレット)
SMTP AUTH のパスワード (任意)。
├─ hasPassword boolean 読み取り専用
既定値: false
パスワードが保存されているかどうかを示します。
├─ clearPassword boolean 書き込み専用 (シークレット)
既定値: false
保存されたパスワードを消去するには true を設定します。
├─ description string 任意
管理者の監査用メモ。
├─ enabled boolean 任意
既定値: true
ルートを有効化または一時停止します。
{
  "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:
nextxch-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:
nextxch-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
});
シングルトン ポリシー

TransactionalSend (Singleton)

キー: singleton RBAC: TenantAdmin+
11 個のプロパティ

段階的な 28 日間の IP ウォーミング、メッセージ カテゴリ、受信側プロバイダーごとの時間/日単位のクォータ (Google、Microsoft、Yahoo/AOL、ドイツの ISP、iCloud、*) を管理します。

GET /api/admin/cli/objects/TransactionalSend/singleton アクティブな IP ウォーミングとプロバイダー クォータ ポリシーを取得します
PATCH /api/admin/cli/objects/TransactionalSend/singleton ウォーミング日、プリセット、またはプロバイダー クォータを更新
{ } オブジェクト スキーマ & 型付きプロパティ application/json · camelCase
├─ enabled boolean 任意
既定値: true
カテゴリとプロバイダー クォータの管理を有効にします。
├─ warmingEnabled boolean 任意
既定値: false
段階的な日次 IP ウォーミング ランプを有効にします。
├─ startAtWarmingDay integer 書き込み専用 (シークレット)
既定値: 1
ウォーミング スケジュールを N 日目 (1..365) にジャンプまたはリセットします。
├─ currentWarmingDay integer 読み取り専用
ウォーミング スケジュールの現在のアクティブ日。
├─ currentWarmingPercent integer 読み取り専用
対象プロバイダー クォータの現在の有効割合。
├─ warmingDailyRampPercents integer[] 任意
既定値: [5,7,10,...,100]
ウォーミング ランプの日ごとのパーセンテージ配列。
├─ maxDeferHours integer 任意
既定値: 48
DeferQueue のペース配分で先読みする最大時間 (時間単位)。
├─ defaultCategory string 任意
既定値: transactional
API 呼び出しで省略された場合のフォールバック カテゴリ。
Enum:"critical""transactional""notification""marketing"
├─ preset string 書き込み専用 (シークレット)
ワンステップのプリセット選択。
Enum:"warming_28d""warming_14d""production_100"
├─ categories CategoryPolicy[] 任意
既定値: 4 Kategorien
カテゴリ ポリシー オブジェクトの配列。
├─ providers ProviderQuota[] 任意
既定値: 6 Provider-Gruppen
受信者プロバイダーのクォータ定義の配列。
{
  "enabled": true,
  "warmingEnabled": true,
  "startAtWarmingDay": 1,
  "maxDeferHours": 48,
  "defaultCategory": "transactional",
  "preset": "warming_28d"
}
# 28-Tage IP-Warming aktivieren:
nextxch-cli update TransactionalSend --set preset=warming_28d

# Direkt auf Warming-Tag 14 vorspringen:
nextxch-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 });
シングルトン ポリシー

ReputationShield (Singleton)

キー: singleton RBAC: TenantAdmin+
20 のプロパティ

任意の送信レピュテーション保護: バウンス / 苦情の自動抑制リスト、RFC 8058 ワンクリック配信停止、バウンス サーキット ブレーカー、ISP の 421 に応じた適応型バックオフ、HMAC-SHA256 Webhook。

GET /api/admin/cli/objects/ReputationShield/singleton 現在の Reputation Shield 構成を取得します
PATCH /api/admin/cli/objects/ReputationShield/singleton 保護フラグを更新するか、プリセットを適用します
{ } オブジェクト スキーマ & 型付きプロパティ application/json · camelCase
├─ preset string 書き込み専用 (シークレット)
完全な保護プロファイルを 1 ステップで適用します。
Enum:"off""recommended""strict_bulk"
├─ enableSuppressionPreCheck boolean 任意
既定値: false
送信前に抑制対象のアドレスを除外します。
├─ enforceSuppressionOnSmtpRelay boolean 任意
既定値: false
SMTP 送信 (submission) でも抑制リストを適用します。
├─ allSuppressedBehavior string 任意
既定値: reject_422
すべての受信者が抑制されている場合の応答モード。
Enum:"reject_422""accept_noop"
├─ autoSuppressHardBounces boolean 任意
既定値: false
5xx の恒久的なハード バウンスを自動的に抑止します。
├─ hardBounceSuppressionDays integer 任意
既定値: 180
ハード バウンスによる抑制の保持日数。
├─ autoSuppressConsecutiveSoftBounces boolean 任意
既定値: false
繰り返し発生する 4xx ソフト バウンスを抑制リストに昇格させます。
├─ softBounceEscalationThreshold integer 任意
既定値: 5
抑止するまでの連続ソフト バウンス数。
├─ autoSuppressFblComplaints boolean 任意
既定値: false
受信した RFC 5965 ARF の不正利用レポートを自動的に解析します。
├─ enableOneClickUnsubscribe boolean 任意
既定値: false
DKIM 署名付きの RFC 8058 List-Unsubscribe ヘッダーを挿入します。
├─ oneClickUnsubscribeCategories string[] 任意
既定値: ["marketing","notification"]
RFC 8058 の配信停止ヘッダーを付与するカテゴリ。
├─ enableBounceCircuitBreaker boolean 任意
既定値: false
24 時間のバウンス率 / 苦情率が急上昇した場合、重要でない送信を一時停止します。
├─ maxHardBouncePercent number 任意
既定値: 5.0
24 時間のハード バウンス率の上限 (%)。
├─ maxComplaintPercent number 任意
既定値: 0.1
24 時間の ARF 苦情率の上限 (パーセント)。
├─ allowCriticalWhenTripped boolean 任意
既定値: true
サーキット ブレーカーが作動していても、重要な 2FA メールの送信を許可します。
├─ enableAdaptiveIspBackoff boolean 任意
既定値: false
リモート MX が 421/451 のスロットリングを返した場合の自動クールダウン。
├─ ispCooldownMinutes integer 任意
既定値: 15
クールダウン時間 (分)。
├─ webhookEnabled boolean 任意
既定値: false
HMAC-SHA256 署名付き Webhook を有効にします。
├─ webhookUrl string 任意
Webhook の送信先 HTTPS URL。
├─ webhookSecret string 書き込み専用 (シークレット)
X-Nextxch-Signature 用の HMAC-SHA256 シークレット。
{
  "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/nextxch"
}
# Empfohlenen Reputationsschutz aktivieren:
nextxch-cli update ReputationShield --set preset=recommended

# Webhook-Ziel konfigurieren:
nextxch-cli update ReputationShield \
  --set webhookEnabled=true \
  --set webhookUrl=https://erp.firma.de/webhooks/nextxch \
  --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" });
シングルトン ポリシー

SpamGuard (Singleton)

キー: singleton RBAC: ServerAdmin+
15 個のプロパティ

多段階の受信防御: SPF/DKIM/DMARC/ARC の検証、スマート グレーリスト (/24 IPv4 & /64 IPv6)、オンライン ML 分類器 (FTRL-Proximal)、DNSBL ゾーン、許可/ブロックリスト、ClamAV TCP スキャン。

GET /api/admin/cli/objects/SpamGuard/singleton SpamGuard のしきい値 & 学習カウンターを取得します
PATCH /api/admin/cli/objects/SpamGuard/singleton スコア、DNSBL、許可リスト、または ClamAV をその場で更新します
{ } オブジェクト スキーマ & 型付きプロパティ application/json · camelCase
├─ enableEmailAuthChecks boolean 任意
既定値: true
受信メールの SPF、DKIM、DMARC、ARC を検証します。
├─ enableGreylisting boolean 任意
既定値: true
初めての未知の送信者に対する適応型スマート グレーリスト。
├─ greylistRetryDelaySeconds integer 任意
既定値: 240
最小再試行間隔 (秒、既定: 240 秒)。
├─ junkScoreThreshold number 任意
既定値: 4.5
迷惑メール フォルダーに振り分けるスコアしきい値。
├─ rejectScoreThreshold number 任意
既定値: 9.0
SMTP 550 で完全拒否するスコアのしきい値。
├─ tagSubjectOnJunk boolean 任意
既定値: false
迷惑メールに件名プレフィックスを付加します。
├─ subjectTagPrefix string 任意
既定値: "[SPAM] "
件名プレフィックス文字列。
├─ enableStructuralHeuristics boolean 任意
既定値: true
MIME/HTML の構造的ヒューリスティックを評価します。
├─ dnsblZones string[] 任意
既定値: ["bl.spamcop.net","ix.dnsbl.manitu.net"]
照会する DNSBL ゾーン。
├─ dnsblHitScore number 任意
既定値: 3.5
DNSBL ヒットごとに加算されるスコア。
├─ allowedSendersOrDomains string[] 任意
既定値: []
明示的な送信者メール アドレスまたはドメインの許可リスト。
├─ blockedSendersOrDomains string[] 任意
既定値: []
明示的な送信者メール アドレスまたはドメインのブロックリスト。
├─ clamAvEnabled boolean 任意
既定値: false
ClamAV デーモンによる TCP INSTREAM スキャンを有効にします。
├─ clamAvHost string 任意
既定値: "127.0.0.1"
ClamAV デーモンのホストまたは IP。
├─ clamAvPort integer 任意
既定値: 3310
ClamAV デーモンの TCP ポート。
{
  "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:
nextxch-cli update SpamGuard \
  --set allowedSendersOrDomains=datev.de,partner-spedition.de

# Schwellenwerte anpassen:
nextxch-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 });
シングルトン ポリシー

SmtpQueue (Singleton)

キー: singleton RBAC: ServerAdmin+
19 プロパティ

送信 MX 配信キュー、ワーカーの同時実行数、再試行間隔、ISP スロットリング、送信 TLS 検証、グローバル スマート ホスト、受信 ESMTP 制限を制御します。

GET /api/admin/cli/objects/SmtpQueue/singleton すべてのキュー、TLS、ESMTP の設定を取得します
PATCH /api/admin/cli/objects/SmtpQueue/singleton キュー ワーカー、再試行スケジュール、ESMTP 制限を 0 ms で更新します
{ } オブジェクト スキーマ & 型付きプロパティ application/json · camelCase
├─ outboundQueuePaused boolean 任意
既定値: false
メールの受け付けは継続しながら、送信 MX 配信を一時停止します。
├─ outboundWorkerConcurrency integer 任意
既定値: 8
並列で動作する送信配信ワーカーの数。
├─ maxDeliveryAttempts integer 任意
既定値: 10
恒久的なバウンスになるまでの最大配信試行回数。
├─ retryScheduleMinutes integer[] 任意
既定値: [5,15,60,240,720]
再試行のバックオフ スケジュール (分)。
├─ maxConcurrentConnectionsPerMxDomain integer 任意
既定値: 4
宛先 MX ドメインごとの最大同時接続数。
├─ strictThrottleDomains string[] 任意
既定値: ["t-online.de","gmx.de","web.de","yahoo.com"]
厳格な同時実行スロットリングの対象となるドメイン。
├─ strictThrottleMaxConcurrency integer 任意
既定値: 2
strictThrottleDomains の最大同時接続数。
├─ outboundConnectTimeoutSeconds integer 任意
既定値: 30
送信 TCP/TLS 接続のタイムアウト (秒)。
├─ outboundBindAddress string 任意
既定値: "" (Auto)
オプションのローカル送信元 IP バインド アドレス。
├─ outboundUseStartTls boolean 任意
既定値: true
送信 MX 接続で STARTTLS を使用します。
├─ requireOutboundTls boolean 任意
既定値: false
リモート MX が TLS を提供しない場合は配信を中止します。
├─ outboundTlsCertValidation string 任意
既定値: Opportunistic
送信時のグローバルな X.509 証明書検証モード。
Enum:"Opportunistic""IgnoreErrors""Strict"
├─ outboundSmartHost string 任意
既定値: ""
任意のグローバル上流リレー ホスト。
├─ outboundSmartPort integer 任意
既定値: 587
グローバル スマート ホストの TCP ポート。
├─ maxMessageSizeMb long 任意
既定値: 50
グローバルな ESMTP SIZE 制限 (MiB)。
├─ maxRecipientsPerTransaction integer 任意
既定値: 100
トランザクションあたりの RCPT TO コマンドの最大数。
├─ maxConnectionsPerIp integer 任意
既定値: 20
IP あたりの最大同時受信接続数。
├─ tarpitDelayMs integer 任意
既定値: 1500
認証/コマンド エラー時のターピット遅延 (ms)。
├─ requireTlsForAuth boolean 任意
既定値: true
SMTP AUTH を許可する前に TLS 暗号化を必須にします。
{
  "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:
nextxch-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 });
シングルトン ポリシー

TransportRules & Server (Singletons)

キー: singleton RBAC: ServerAdmin+
11 個のプロパティ

組織全体の法的免責事項 (DKIM 署名の前に挿入)、グローバル受信 Sieve スクリプト、Fail2Ban 自動禁止のしきい値、正規の ServerHostName。

GET /api/admin/cli/objects/TransportRules/singleton 免責事項、グローバル Sieve、自動禁止の設定を取得します
PATCH /api/admin/cli/objects/TransportRules/singleton トランスポート ルールをその場で更新します
GET /api/admin/cli/objects/Server/singleton ServerHostName、ストレージ エンジン、キューの深さ、ライセンス状態を取得します
PATCH /api/admin/cli/objects/Server/singleton 正規の ServerHostName を 0 ms で更新します
{ } オブジェクト スキーマ & 型付きプロパティ application/json · camelCase
├─ outboundDisclaimerEnabled boolean 任意
既定値: false
送信メッセージに必須の企業フッターを付加します。
├─ outboundDisclaimerExternalOnly boolean 任意
既定値: true
外部ドメインに送信する場合にのみフッターを追加します。
├─ outboundDisclaimerText string 任意
既定値: ""
プレーン テキストの法定フッター。
├─ outboundDisclaimerHtml string 任意
既定値: ""
HTML 法定フッター。
├─ inboundSystemSieve string 任意
既定値: ""
ユーザー スクリプトより前に実行されるグローバルな RFC 5228 Sieve スクリプト。
├─ autoBanThreshold integer 任意
既定値: 8
自動 IP 禁止までのログイン失敗回数。
├─ autoBanDurationMinutes integer 任意
既定値: 30
自動 IP 禁止の期間 (分)。
├─ serverHostName string 任意
既定値: mail.<domain>
正規の EHLO、TLS、Autodiscover の FQDN (オブジェクト: Server)。
├─ storageProvider string 読み取り専用
既定値: Sqlite | SqlServer | Postgres
有効なストレージ エンジン (オブジェクト: Server)。
├─ activeQueueCount integer 読み取り専用
既定値: 0
現在の送信キューの件数 (オブジェクト: Server)。
├─ licenseState string 読み取り専用
既定値: EnterpriseActive
ライセンスの状態 (オブジェクト: 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:
nextxch-cli update TransportRules \
  --set outboundDisclaimerEnabled=true \
  --set autoBanThreshold=8

# Kanonischen Server-Hostnamen abfragen oder setzen:
nextxch-cli get Server
nextxch-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")}");