PUT /v1/sites/{siteId}/mail-smtp
Save (and prove) the site's own SMTP server.
Authentication
Send an API key as a bearer token. The key must carry the mail.manage permission; a key without it is refused with 403, not 404.
This endpoint takes no organisation id. Your key already identifies the organisation it belongs to, and the response is scoped to it.
Try it
Replace anything in angle brackets with your own values, and the key placeholder with a key from your dashboard.
curl -X PUT https://api.zinndigital.com/v1/sites/{siteId}/mail-smtp \
-H "Authorization: Bearer zdk_live_…" \
-H "Content-Type: application/json" \
-d '{ "host": <string>, "port": <integer<25, 465, 587, 2525>>, "username": <string>, "from_address": <string> }'Signed in? The API console in your dashboard fills in your real organisation id and your own key, and runs the request against the live API so you can see the actual response. Open this endpoint in the API console
Details
Saves the settings — the password goes to the secret store and is write-only; omit it to keep the stored one (required the first time) — then proves the server FROM THE SITE'S SERVER, as the site (encrypted connection + login, nothing sent). Only a successful proof switches the site's mail to it; otherwise the site keeps sending through our relay and status is failing with the reason. Ports 587/2525 (STARTTLS), 465 (SSL/TLS) or 25. Requires mail.manage.
Parameters
| Name | Type | Required | What it is |
|---|---|---|---|
siteId (path) | Uuid | Yes | Site ID (UUIDv7). |
Request body
| Name | Type | Required | What it is |
|---|---|---|---|
host | string | Yes | — |
port | integer<25, 465, 587, 2525> | Yes | — |
tls | string<starttls, implicit> | No | Defaults to implicit on 465 and starttls otherwise. |
username | string | Yes | — |
password | string | No | Required the first time; omit to keep the stored one. |
from_address | string | Yes | — |
enabled | boolean | No | — |
Response
| Name | Type | Required | What it is |
|---|---|---|---|
configured | boolean | Yes | — |
host | string | No | — |
port | integer<25, 465, 587, 2525> | No | — |
tls | string<starttls, implicit> | No | — |
username | string | No | — |
from_address | string | No | — |
enabled | boolean | No | — |
status | string<unverified, active, failing> | No | — |
last_error | string | No | A code: auth, tls, unreachable, unsupported, password_unreadable, server, or empty. |
proven_at | string | No | — |
updated_at | string | No | — |
Errors this endpoint can return
401 · 403 · 404 · 422 · 429