---
title: "Retrieve the web app address"
description: "The web app address of the workspace, whether people can sign in there, and the DNS records it needs. With none set, `status` is `none` and `domains` lists the verified domains of the workspace."
url: "https://nextmail.sh/docs/api/app-host/get"
area: "API"
category: "Mailbox"
---

# Retrieve the web app address

The web app address of the workspace, whether people can sign in there, and the DNS records it needs. With none set, `status` is `none` and `domains` lists the verified domains of the workspace.

`GET /app-host`

## GET /app-host

The web app address of the workspace, whether people can sign in there, and the DNS records it needs. With none set, `status` is `none` and `domains` lists the verified domains of the workspace.

## What the web app address is

**shell**

```
export OE=https://api.nextmail.sh
export AUTH="Authorization: Bearer $NEXTMAIL_API_KEY"
```

A workspace on a paid plan can open the web app on a subdomain of its own, such as `mailbox.acme.com`, as well as on nextmail.sh. The subdomain can be on one of its verified domains or on any other domain it controls. It is the address the Branded app tab of the workspace’s Customisations page sets, and a workspace has at most one.

Only the members of the workspace, the people who sign in with one of its addresses and anyone with a pending invitation can sign in there, and only they get password reset and verification emails sent from it. It looks like nextmail.sh until the workspace sets a logo on its Customisations page, then shows the workspace’s logo, mark and name in place of ours. From then on the emails Nextmail sends them carry the brand and link back to the address. When the address is on a verified domain of the workspace, they also come from `noreply@` that domain once its signing records are verified.

It takes one CNAME record, which `record` spells out. An address that is not on a verified domain of the workspace also takes the TXT record in `ownershipRecord`, which proves the domain is yours, and nothing is set up for it until that record answers. The address is `pending` until its records answer and its certificate is issued, and `active` after that. On the free plan it is kept but paused: `paused` is true and nobody can sign in there until the workspace is on a paid plan again.

## Example

Needs `domains:read`.

**curl**

```
curl "$OE/app-host" -H "$AUTH"
```

**Response**

```
{
  "object": "app_host",
  "id": "ahost_3f9c2a71d0b84e56a1c7f2e9",
  "host": "mailbox.acme.com",
  "domainId": "b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f",
  "domain": "acme.com",
  "status": "active",
  "active": true,
  "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": "2026-10-01T09:04:11.000Z",
  "available": true,
  "paidPlan": true,
  "domains": ["acme.com"],
  "suggested": "mailbox.acme.com"
}
```

> Reading it checks the address again when its last check is more than 15 seconds old, so polling this route is how to wait for `active` to turn true.

> `active` is true only when `status` is `active` and the workspace is on a paid plan. `paused` is true when an address is set and the workspace is on the free plan.

## Reference

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