Disposable addresses

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.

• —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.

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.

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

• —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.

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

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.