Set the web app address
Sets the web app address of the workspace, replacing any it had, and returns it with the DNS records to publish.
Runs the real call on your workspace.
PUT /app-host
Sets the web app address of the workspace, replacing any it had, and returns it with the DNS records to publish.
The request
Parameters
hoststringrequired- A subdomain such as `mailbox.acme.com`, on a verified domain of this workspace or on any other domain you control, at most 253 characters. It is lowercased, and an `https://` prefix, a path and a trailing dot are stripped. A bare domain cannot be used.
Example
Needs domains:write, a paid plan, and a key with no address or domain restriction.
curl -X PUT "$OE/app-host" -H "$AUTH" -H "Content-Type: application/json" \ -d '{ "host": "mailbox.acme.com" }'{ "object": "app_host", "id": "ahost_3f9c2a71d0b84e56a1c7f2e9", "host": "mailbox.acme.com", "domainId": "b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f", "domain": "acme.com", "status": "pending", "active": false, "paused": false, "target": "cname.openemail.uk", "record": { "type": "CNAME", "name": "mailbox.acme.com", "value": "cname.openemail.uk" }, "ownershipRecord": null, "ownershipVerified": true, "error": null, "checkedAt": "2026-10-01T09:12:30.000Z", "verifiedAt": null, "available": true, "paidPlan": true, "domains": ["acme.com"], "suggested": "mailbox.acme.com"}The address starts pending. Publish record, and ownershipRecord when it is not null, at your DNS provider exactly as given, then poll GET /app-host or call POST /app-host/verify. It goes live a few minutes after the records answer, once its certificate is issued.
Setting the address it already has changes nothing and checks it again. An address on another domain replaces the old one once it is set up, and one on the same domain replaces it straight away. Everyone signed in at a replaced address is signed out.
A free workspace answers 403 plan_required. A bare domain, or an address that is not a hostname, answers 422 invalid_app_host, and one another workspace uses 409 app_host_in_use. An address another workspace set but never proved also answers 409 app_host_in_use, with the TXT record that frees it for you in the message.