Save mail configuration. PUT /api/openapi/v1/mail-servers/current, scope admin.v1.mail-settings.manage.
- Scope: admin.v1.mail-settings.manage
- Permission: Manage enterprise mail (mail-settings)
- Permission type: Manage
- Endpoint: PUT/api/openapi/v1/mail-servers/current
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 |
|---|---|---|---|---|---|
| auth_enabled | body | boolean | Required | Server requires authentication | false |
| ca_pem | body | string | No | Custom CA certificate (optional) | "<string>" |
| from_address | body | string · email | Required | Sender email | "developer@example.com" |
| from_name | body | string | No | Display name | "<string>" |
| host | body | string | Required | SMTP host | "<string>" |
| password | body | string | No | Password or authorization code | "<string>" |
| port | body | integer · int64 | Required | Port | 1 |
| tls_mode | body | string | Required | Encryption mode | "tls" |
| username | body | string | No | Authentication account | "<string>" |
| version | body | integer · int64 | Required | Version used for concurrent update checks | 0 |
Request example
cURL
Responses
200 OK
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
| auth_enabled | boolean | Yes | Server requires authentication | false |
| ca_pem | string | Yes | Custom CA certificate (optional) | "<string>" |
| enabled | boolean | Yes | Whether custom SMTP is enabled | false |
| central_available | boolean | Yes | Whether the deployment provides the system mail service | true |
| delivery_available | boolean | Yes | Whether custom SMTP or the system service is available for delivery | true |
| configured | boolean | Yes | Whether configuration is present | false |
| from_address | string | Yes | Sender email | "<string>" |
| from_name | string | Yes | Display name | "<string>" |
| host | string | Yes | SMTP host | "<string>" |
| last_test | OpenapifacadeMailTestResult | No | Last test result | {"at":"2026-08-27T10:00:00Z","code":"<string>","server_version":0,"status":"unknown","template_id":"<string>"} |
| last_test.at | string · date-time | Yes | Test time | "2026-08-27T10:00:00Z" |
| last_test.code | string | Yes | Error code | "<string>" |
| last_test.server_version | integer · int64 | Yes | Mail server configuration version | 0 |
| last_test.status | string | Yes | Test status | "unknown" |
| last_test.template_id | string | No | Template ID | "<string>" |
| password_configured | boolean | Yes | Whether a password is configured | false |
| port | integer · int64 | Yes | Port | 0 |
| provider | string | Yes | Mail delivery provider | "central" |
| tls_mode | string | Yes | Encryption mode | "tls" |
| updated_at | string · date-time | No | Updated at | "2026-08-27T10:00:00Z" |
| username | string | Yes | Authentication account | "<string>" |
| version | integer · int64 | Yes | Version used for concurrent update checks | 0 |
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>" |