Send test email. POST /api/openapi/v1/mail-tests, scope admin.v1.mail-tests.execute.
- Scope: admin.v1.mail-tests.execute
- Permission: Test enterprise mail (mail-tests)
- Permission type: Execute
- Endpoint: POST/api/openapi/v1/mail-tests
Authentication and request headers
Call with an application API key. This endpoint checks only the scope above; read, manage and execute permissions do not imply one another.
| Name | Location | Type | Required | Description | Example |
|---|---|---|---|---|---|
| Authorization | header | string | Yes | Application API key, passed as a Bearer token. | Bearer qwk_*** |
| X-Request-Id | header | string | No | Optional request tracing identifier; generated by the server if omitted. | req-20260831-001 |
Request parameters
| Name | Location | Type | Required | Description | Example |
|---|---|---|---|---|---|
| Idempotency-Key | header | string | Required | Idempotency key used to prevent duplicate submissions | "<string>" |
| server_version | body | integer · int64 | Required | Version returned by GET /mail-servers/current; the saved configuration must still match. | 1 |
| template_id | body | string | No | An existing ID from GET /mail-templates. Omit together with template_version to use the fixed test message. | "qw_vpc_EMAIL_VERIFICATION_CODE" |
| template_version | body | integer · int64 | No | Required when template_id is supplied. Use the saved template version; zero is valid for the default template. | 0 |
| to_email | body | string · email | Required | One test recipient; accepted means SMTP acceptance, not inbox delivery. | "developer@example.com" |
Request example
cURL
Responses
200 Accepted by SMTP; inbox delivery is not guaranteed.
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
| at | string · date-time | Yes | Test time | "2026-08-27T10:00:00Z" |
| code | string | Yes | Error code | "<string>" |
| server_version | integer · int64 | Yes | Mail server configuration version | 0 |
| status | string | Yes | Test status | "unknown" |
| template_id | string | No | Template ID | "<string>" |
502 SMTP failed or acceptance is unknown; inspect details and do not automatically resend.
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
| code | string | Yes | Error code | "<string>" |
| detail | string | Yes | Error description | "<string>" |
| details | OpenapifacadeMailTestResult | Yes | Test result details | {"at":"2026-08-27T10:00:00Z","code":"<string>","server_version":0,"status":"unknown","template_id":"<string>"} |
| details.at | string · date-time | Yes | Test time | "2026-08-27T10:00:00Z" |
| details.code | string | Yes | Error code | "<string>" |
| details.server_version | integer · int64 | Yes | Mail server configuration version | 0 |
| details.status | string | Yes | Test status | "unknown" |
| details.template_id | string | No | Template ID | "<string>" |
| error | string | Yes | Error type | "<string>" |
default Flat business error
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
| code | string | No | Stable business error code | "<string>" |
| detail | string | Yes | Human-readable error description | "<string>" |
| details | OpenapiErrorDetails | No | Test result details | {"field":"<string>","reason":"<string>","suggestion":"<string>"} |
| details.field | string | No | Request field that failed validation | "<string>" |
| details.reason | string | No | Stable validation failure reason | "<string>" |
| details.suggestion | string | No | Suggested normalized value | "<string>" |
| error | string | Yes | Stable HTTP error type | "<string>" |