---
title: "Disposable addresses"
description: "Give an address an expiry, choose whether it stops or is deleted when the time comes, hear about it from a webhook, and see how many addresses and webhook endpoints each plan holds."
url: "https://nextmail.sh/docs/knowledge/addresses/disposable-addresses"
area: "Knowledge base"
category: "Domains & addresses"
---

# Disposable addresses

Give an address an expiry, choose whether it stops or is deleted when the time comes, hear about it from a webhook, and see how many addresses and webhook endpoints each plan holds.

## An address that expires

An address can be given a time to expire, from a minute to ten years ahead. From that moment it takes no mail and sends none: mail to it is refused as if the address did not exist, with `5.1.1`, and a send from it is refused with 403 `address_expired`. Queued and scheduled mail from it fails when its turn comes. Within a minute after the time, the address is switched off, or deleted when it was set to be.

| Field | What it does |
| --- | --- |
| `expiresAt` | An RFC 3339 time, at least 60 seconds and at most 10 years ahead. Null clears it, and the address never expires. |
| `onExpiry` | `stop`, the default, switches the address off and keeps every conversation it received. `delete` removes the address and the conversations delivered to it. |
| `expiredAt` | Read only. When the address expired. It is cleared again when the address is turned back on. |

> Nothing expires unless somebody gives it a time. An address created without `expiresAt` works as it always has.

## Stop or delete

- A stopped address keeps its mail, its settings, its forwarding destinations and the people who reach it. Give it a later `expiresAt`, set `expiresAt` to null, or turn it on with `enabled: true`, and it takes mail again. Turning it on also clears an `expiresAt` that has passed.
- A deleted address is removed the way a person removes one, and the conversations delivered to it are deleted for good, as Delete forever deletes them, with their attachments and kept originals. Nothing of it comes back, and adding the address again later starts it fresh.
- Choosing `delete` needs `threads:write` beside `domains:write`. A member also needs a role that may manage the workspace, and an OAuth access token is asked for a verification code.
- The time is checked the moment mail arrives or is sent, so an address stops at exactly the time it was given, even before Nextmail has switched it off.

## The address.expired event

Each address that expires is announced once, as `address.expired`, to the endpoints that subscribe to it. It is the first event of the address family. An endpoint limited to some addresses or domains hears only about those, and an endpoint that lists no events does not get it, so name it in `eventTypes`.

| Field | What it holds |
| --- | --- |
| `addressId` | The address id. |
| `address` | The full address, lower-cased. |
| `domainId` | The domain the address is on. |
| `expiredAt` | When it expired. |
| `action` | `stop` when the address was switched off with its mail, `delete` when it was deleted with its conversations. |

**Payload**

```
{
  "type": "address.expired",
  "data": {
    "addressId": "7c9d2e41-0b8f-4a63-9e25-1f4d6a8b3c70",
    "address": "signup-0425@example.com",
    "domainId": "b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f",
    "expiredAt": "2026-11-01T09:00:12.000Z",
    "action": "stop"
  }
}
```

## Where to set it

- In the web app, the Expiry section on the Delivery tab of the address page sets the time and what happens then, clears it, and turns an expired address back on. A new address can get one at once with Set an expiry in the dialog that creates it.
- In the phone app, Expiry is on the Delivery tab of the address screen.
- Over REST, `expiresAt` and `onExpiry` on `POST /domains/{id}/addresses` and `PATCH /domains/{id}/addresses/{addressId}`, and every address reports them with `expiredAt`.
- In the SDKs, `expiresAt` and `onExpiry` on `domains.createAddress` and `domains.updateAddress`, written the way each language writes names.
- On the command line, `--expires-at` and `--on-expiry` on `nextmail domains create-address` and `nextmail domains update-address`.
- Over MCP and in the assistant, `expiresAt` and `onExpiry` on `addDomainAddress` and `updateDomainAddress`.

**Terminal**

```
nextmail domains update-address <domain-id> <address-id> --expires-at 2026-12-31T23:59:00Z --on-expiry stop
```

## Addresses and webhooks per plan

How many addresses and webhook endpoints a workspace may have depends on its plan. An address counts from the moment it is created until it is removed, whether it is on, off or expired, and a deleted one stops counting. Reaching either cap is a 422 `workspace_limit_reached`, and nothing was created.

| Resource | Free | Starter | Business | Enterprise |
| --- | --- | --- | --- | --- |
| Addresses | 1,000 | 10,000 | 100,000 | 1,000,000 |
| Webhook endpoints | 10 | 25 | 100 | 500 |

> Support can raise either cap for one workspace, and a raise holds whatever the plan. Moving to a smaller plan never removes an address or an endpoint: it only stops new ones until the workspace is below the cap.

- [Address limits](https://nextmail.sh/docs/knowledge/addresses/address-limits.md): What one address may send and receive.
- [Webhooks](https://nextmail.sh/docs/knowledge/developers/webhooks.md): Events, signatures, retries and what each payload carries.
- [SDK methods](https://nextmail.sh/docs/sdk/reference/domains.md): The `domains` methods, `createAddress` and `updateAddress` among them.
- [MCP tools](https://nextmail.sh/docs/mcp/tools/workspace.md): The tools that manage domains and addresses.