PPanel Edgenotify
由 openapi.json 自动生成的 7 个端点及其请求、响应和权限元数据。
此参考由已发布 API 契约生成。字段、请求头和权限要求如下。
下载完整 OpenAPI 文档 · SHA-256: ccaa20cec11fad96e369b88073ce3608a5b071ce55d6dc03fa31df7b0f08c525
标识符和数据结构与公开契约一致，说明直接给出调用规则。共享模型见 数据模型.
GET /api/v1/admin/notify/deliveries
GET /api/v1/admin/notify/deliveries
List deliveries (newest first, masked targets)
{
"parameters": [
{
"description": "Delivery status; repeat the parameter for several values",
"in": "query",
"name": "status",
"required": false,
"schema": {
"anyOf": [
{
"enum": [
"pending",
"sending",
"sent",
"failed",
"suppressed",
"dead"
],
"type": "string"
},
{
"items": {
"enum": [
"pending",
"sending",
"sent",
"failed",
"suppressed",
"dead"
],
"type": "string"
},
"type": "array"
}
],
"description": "Delivery status; repeat the parameter for several values"
}
},
{
"in": "query",
"name": "template_key",
"required": false,
"schema": {
"maxLength": 100,
"pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*){1,3}$",
"type": "string"
}
},
{
"in": "query",
"name": "event_key",
"required": false,
"schema": {
"maxLength": 200,
"minLength": 1,
"type": "string"
}
},
{
"in": "query",
"name": "recipient_id",
"required": false,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"description": "Exact recipient address (matched by hash)",
"in": "query",
"name": "to",
"required": false,
"schema": {
"description": "Exact recipient address (matched by hash)",
"format": "email",
"maxLength": 254,
"type": "string"
}
},
{
"in": "query",
"name": "channel",
"required": false,
"schema": {
"enum": [
"email",
"sms",
"telegram",
"inbox"
],
"type": "string"
}
},
{
"description": "Created at or after (inclusive)",
"in": "query",
"name": "created_from",
"required": false,
"schema": {
"description": "Created at or after (inclusive)",
"format": "date-time",
"type": "string"
}
},
{
"description": "Created before (exclusive)",
"in": "query",
"name": "created_to",
"required": false,
"schema": {
"description": "Created before (exclusive)",
"format": "date-time",
"type": "string"
}
},
{
"description": "Default 20, at most 100",
"in": "query",
"name": "page_size",
"required": false,
"schema": {
"description": "Default 20, at most 100",
"maximum": 100,
"minimum": 1,
"type": "integer"
}
},
{
"description": "`next_cursor` of the previous page",
"in": "query",
"name": "cursor",
"required": false,
"schema": {
"description": "`next_cursor` of the previous page",
"maxLength": 512,
"minLength": 1,
"type": "string"
}
},
{
"description": "Return `total` (first page only)",
"in": "query",
"name": "include_total",
"required": false,
"schema": {
"description": "Return `total` (first page only)",
"enum": [
"true",
"false"
],
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NotifyDeliveryPage"
}
}
},
"description": "A page of deliveries"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Invalid filter or cursor"
}
},
"summary": "List deliveries (newest first, masked targets)",
"tags": [
"notify"
],
"x-body": "none",
"x-body-limit": 0,
"x-permission": "notify.delivery.read",
"effectiveSecurity": []
}GET /api/v1/admin/notify/deliveries/{id}
GET /api/v1/admin/notify/deliveries/{id}
Delivery detail with masked values
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NotifyDeliveryDetail"
}
}
},
"description": "The delivery"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "No such delivery"
}
},
"summary": "Delivery detail with masked values",
"tags": [
"notify"
],
"x-body": "none",
"x-body-limit": 0,
"x-permission": "notify.delivery.read",
"effectiveSecurity": []
}POST /api/v1/admin/notify/deliveries/{id}/retry
POST /api/v1/admin/notify/deliveries/{id}/retry
Retry a failed or dead delivery (back to pending with a fresh attempt budget)
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NotifyDeliveryDetail"
}
}
},
"description": "The delivery, pending again"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "No such delivery"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "notify.delivery_not_retryable"
}
},
"summary": "Retry a failed or dead delivery (back to pending with a fresh attempt budget)",
"tags": [
"notify"
],
"x-audit": "notify.delivery.retry",
"x-body": "none",
"x-body-limit": 0,
"x-idempotency": "optional",
"x-permission": "notify.delivery.retry",
"effectiveSecurity": []
}GET /api/v1/admin/notify/templates
GET /api/v1/admin/notify/templates
List notification templates (built-in texts and saved locales)
{
"parameters": [
{
"in": "query",
"name": "key",
"required": false,
"schema": {
"maxLength": 100,
"pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*){1,3}$",
"type": "string"
}
},
{
"in": "query",
"name": "channel",
"required": false,
"schema": {
"enum": [
"email",
"sms",
"telegram",
"inbox"
],
"type": "string"
}
},
{
"in": "query",
"name": "locale",
"required": false,
"schema": {
"pattern": "^[a-z]{2,3}(-[A-Z][a-z]{3})?(-([A-Z]{2}|\\d{3}))?$",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NotifyTemplateList"
}
}
},
"description": "Templates"
}
},
"summary": "List notification templates (built-in texts and saved locales)",
"tags": [
"notify"
],
"x-body": "none",
"x-body-limit": 0,
"x-permission": "notify.template.manage",
"effectiveSecurity": []
}GET /api/v1/admin/notify/templates/{key}/{channel}/{locale}
GET /api/v1/admin/notify/templates/{key}/{channel}/{locale}
One template locale, with ETag
{
"parameters": [
{
"in": "path",
"name": "key",
"required": true,
"schema": {
"example": "commerce.order.fulfilled",
"maxLength": 100,
"pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*){1,3}$",
"type": "string"
}
},
{
"in": "path",
"name": "channel",
"required": true,
"schema": {
"enum": [
"email",
"sms",
"telegram",
"inbox"
],
"example": "email",
"type": "string"
}
},
{
"in": "path",
"name": "locale",
"required": true,
"schema": {
"example": "en-US",
"pattern": "^[a-z]{2,3}(-[A-Z][a-z]{3})?(-([A-Z]{2}|\\d{3}))?$",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NotifyTemplate"
}
}
},
"description": "The template",
"headers": {
"ETag": {
"description": "Current resource version for If-Match.",
"schema": {
"type": "string"
}
}
}
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unknown template or locale"
}
},
"summary": "One template locale, with ETag",
"tags": [
"notify"
],
"x-body": "none",
"x-body-limit": 0,
"x-concurrency": {
"etag": true
},
"x-permission": "notify.template.manage",
"effectiveSecurity": []
}PUT /api/v1/admin/notify/templates/{key}/{channel}/{locale}
PUT /api/v1/admin/notify/templates/{key}/{channel}/{locale}
Save one template locale (If-Match "v<version>"; "v0" overrides the built-in text or adds a locale)
{
"parameters": [
{
"in": "path",
"name": "key",
"required": true,
"schema": {
"example": "commerce.order.fulfilled",
"maxLength": 100,
"pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*){1,3}$",
"type": "string"
}
},
{
"in": "path",
"name": "channel",
"required": true,
"schema": {
"enum": [
"email",
"sms",
"telegram",
"inbox"
],
"example": "email",
"type": "string"
}
},
{
"in": "path",
"name": "locale",
"required": true,
"schema": {
"example": "en-US",
"pattern": "^[a-z]{2,3}(-[A-Z][a-z]{3})?(-([A-Z]{2}|\\d{3}))?$",
"type": "string"
}
},
{
"description": "Resource ETag; missing 428, malformed 412, stale 409.",
"in": "header",
"name": "If-Match",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NotifyTemplateUpdate"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NotifyTemplate"
}
}
},
"description": "Saved template, with ETag",
"headers": {
"ETag": {
"description": "Current resource version for If-Match.",
"schema": {
"type": "string"
}
}
}
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unknown template, channel or locale"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "common.version_conflict (with current)"
},
"412": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Malformed If-Match"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "notify.template_invalid or validation failed"
},
"428": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "If-Match missing"
}
},
"summary": "Save one template locale (If-Match \"v<version>\"; \"v0\" overrides the built-in text or adds a locale)",
"tags": [
"notify"
],
"x-audit": "notify.template.update",
"x-body": "json",
"x-body-limit": 524288,
"x-concurrency": {
"etag": true,
"ifMatch": true
},
"x-idempotency": "optional",
"x-permission": "notify.template.manage",
"effectiveSecurity": []
}POST /api/v1/admin/notify/test-send
POST /api/v1/admin/notify/test-send
Preview or test-send a template (synchronous; no delivery record)
{
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NotifyTestSend"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NotifyTestSendResult"
}
}
},
"description": "Rendered message and, unless dry_run, every provider attempt"
},
"403": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "auth.forbidden: recipient must be own verified email; other recipients/provider_id need notify.provider.manage"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unknown template"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "notify.template_invalid or validation failed"
},
"429": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "common.rate_limited: provider managers may make 10 real test-send attempts per hour per actor"
},
"503": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "notify.provider_unavailable: no enabled provider (or no such provider)"
}
},
"summary": "Preview or test-send a template (synchronous; no delivery record)",
"tags": [
"notify"
],
"x-audit": "notify.template.test_send",
"x-body": "json",
"x-body-limit": 524288,
"x-idempotency": "none",
"x-permission": "notify.template.manage",
"effectiveSecurity": []
}