---
title: "Remove a domain"
description: "Removes the domain from the workspace. Its addresses stop receiving, mail from it can no longer be sent, its tracking and files domains stop answering, and `domain.deleted` fires. Mail already received stays in the mailbox."
url: "https://nextmail.sh/docs/api/domains/delete"
area: "API"
category: "Mailbox"
---

# Remove a domain

Removes the domain from the workspace. Its addresses stop receiving, mail from it can no longer be sent, its tracking and files domains stop answering, and `domain.deleted` fires. Mail already received stays in the mailbox.

`DELETE /domains/{id}`

## DELETE /domains/{id}

Removes the domain from the workspace. Its addresses stop receiving, mail from it can no longer be sent, its tracking and files domains stop answering, and `domain.deleted` fires. Mail already received stays in the mailbox.

## Example

Needs `domains:write`. A key limited to particular addresses or domains needs to hold the whole domain.

**curl**

```
curl -X DELETE "$OE/domains/b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f" -H "$AUTH"
```

**Response**

```
{
  "object": "domain",
  "id": "b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f",
  "domain": "acme.com",
  "deleted": true,
  "leftBehind": []
}
```

> Records Nextmail wrote for you through a connected DNS account are withdrawn. Anything it could not withdraw is listed in `leftBehind`, and records you published by hand stay where they are until you remove them.

> The last domain in a workspace cannot be removed through the API and answers `409` `last_domain`, because removing it in the app deletes the whole mailbox with it. Do that in the app, where it is confirmed first.

> A domain that holds reserved account addresses answers `409` `domain_holds_reserved_addresses`.

> An OAuth access token of a member also needs `workspace:manage` in that member’s role, the permission the app asks for to remove a domain. It is console-only, so without it the call is `insufficient_authority`, a 403, whatever the app was given.

> An OAuth access token needs a verification code for this call. Until the app has verified one in the last 60 minutes, the call answers `403` `step_up_required` and changes nothing. An API key is never asked. The Authentication page shows how to ask for a code and verify it.

## Reference

- [`DELETE /domains/{id}`](https://nextmail.sh/docs/api/reference/domains#delete-domains-id): full reference