Skip to content

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/expire

Headers:

  • Authorization: Bearer <address_jwt>

Request body (JSON):

FieldTypeDescription
expire_atnumber | nullUnix 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/settings as expire_at (null when 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.

Docs adapted from the MIT-licensed cloudflare_temp_email project — License & attribution