---
title: "Set the web app address"
description: "Sets the web app address of the workspace, replacing any it had, and returns it with the DNS records to publish."
url: "https://nextmail.sh/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 DNS records 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 DNS records to publish.

## The request

**Parameters**

- `host` (string, required): 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**

```
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"
  },
  "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.

## Reference

- [`PUT /app-host`](https://nextmail.sh/docs/api/reference/domains#put-app-host): full reference