/v1/workspaces/{workspace_id}/mailboxes/{id}AuthUpdate mailbox display name, retention, or status. Status transitions are restricted (active ↔ suspended; archived is terminal).
Path parameters
workspace_id*string · uuidId of the workspace.
id*string · uuidId of the mailboxe.
Headers
Idempotency-KeystringOpaque client-generated string (1–256 chars, `[A-Za-z0-9._:-]`) used to deduplicate retries within a 24h window. A retry with the same key and body returns the original response with `Idempotent-Replay: true`.
Request body
display_namestringDisplay name
retention_daysnumberRetention period in days (1–30)
statusenum (2)Mailbox status
Response · 200
id*string · uuidThe mailbox id.
seq_id*stringSequential id per workspace (stable, monotonic).
Example: "7"
workspace_id*string · uuidThe workspace that owns the mailbox.
domain_id*string · uuidThe domain the mailbox receives on.
local_part*stringThe part before the @ of the mailbox address.
display_name*stringDisplay name of the mailbox; null for none.
owner_account_id*string · uuidPlatform account that created the mailbox; null when created with an API key.
retention_days*numberRetention period in days.
Example: 14
status*object`active` mailboxes receive mail; `disabled` ones reject it.
Example: "active"
created_at*string · date-timeWhen the mailbox was created.
Example
Request
PATCH https://api.mail.productcraft.co/v1/workspaces/{workspace_id}/mailboxes/{id}
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
{
"display_name": "string",
"retention_days": 0,
"status": "active"
}Response
{
"id": "00000000-0000-0000-0000-000000000000",
"seq_id": "7",
"workspace_id": "00000000-0000-0000-0000-000000000000",
"domain_id": "00000000-0000-0000-0000-000000000000",
"local_part": "string",
"display_name": "string",
"owner_account_id": "00000000-0000-0000-0000-000000000000",
"retention_days": 14,
"status": "active",
"created_at": "2026-01-01T00:00:00.000Z"
}