Mailbox Expiry API
Set or clear a user-defined expiry for the mailbox. An expired mailbox stops working immediately (its credentials are rejected like a deleted mailbox and new mail is refused) and its remaining data is deleted during automatic cleanup. There is no recovery.
The endpoint requires address token permission.
bash
POST /api/expireHeaders:
Authorization: Bearer <address_jwt>
Request body (JSON):
| Field | Type | Description |
|---|---|---|
expire_at | number | null | Unix timestamp (seconds) when the mailbox expires. Must be between 1 minute and 30 days ahead. null clears the expiry. |
Examples:
bash
# expire in 10 minutes
curl -X POST https://example.com/api/expire \
-H "Authorization: Bearer <address_jwt>" \
-H "Content-Type: application/json" \
-d "{\"expire_at\": $(( $(date +%s) + 600 ))}"json
{ "expire_at": 1795415039 }Clear the expiry:
bash
curl -X POST https://example.com/api/expire \
-H "Authorization: Bearer <address_jwt>" \
-H "Content-Type: application/json" \
-d "{\"expire_at\": null}"json
{ "success": true, "expire_at": null }Notes:
- The current expiry is included in
/api/settingsasexpire_at(nullwhen unset). - Addresses bound to a user account cannot set an expiry; the request is rejected.
- The scheduled cleanup removes expired addresses together with all their data (mails, sender settings, bindings) before any admin auto-cleanup settings are applied.
- Incoming mail to an expired address is rejected with
Mailbox expired.