---
title: "Set the web app address"
description: "Sets the web app address of the workspace, replacing any it had, and returns it with the CNAME record to publish."
url: "https://openemail.uk/docs/api/app-host/set"
area: "API"
category: "Mailbox"
---

# Set the web app address

Sets the web app address of the workspace, replacing any it had, and returns it with the CNAME record to publish.

`PUT /app-host`

## PUT /app-host

Sets the web app address of the workspace, replacing any it had, and returns it with the CNAME record to publish.

## The request

**Parameters**

- `host` (string, required): A subdomain of a verified domain of this workspace, such as `mailbox.acme.com`, at most 253 characters. It is lowercased, and an `https://` prefix, a path and a trailing dot are stripped. The bare domain cannot be used.

## Example

Needs `domains:write`, a paid plan, and a key with no address or domain restriction.

**curl**

```
curl -X PUT "$OE/app-host" -H "$AUTH" -H "Content-Type: application/json" \
  -d '{ "host": "mailbox.acme.com" }'
```

**Response**

```
{
  "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"
  },
  "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` 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 record answers, 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`. An address outside the workspace’s domains answers `422` `invalid_app_host`, one on an unverified domain `409` `domain_not_verified`, and one another workspace uses `409` `app_host_in_use`.