Mail API reference

Mail API · Mailboxes

patch/v1/workspaces/{workspace_id}/mailboxes/{id}Auth

Update mailbox display name, retention, or status. Status transitions are restricted (active ↔ suspended; archived is terminal).

Path parameters

workspace_id*string · uuid

Id of the workspace.

id*string · uuid

Id of the mailboxe.

Headers

Idempotency-Keystring

Opaque 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_namestring

Display name

retention_daysnumber

Retention period in days (1–30)

statusenum (2)

Mailbox status

Response · 200

id*string · uuid

The mailbox id.

seq_id*string

Sequential id per workspace (stable, monotonic).

Example: "7"

workspace_id*string · uuid

The workspace that owns the mailbox.

domain_id*string · uuid

The domain the mailbox receives on.

local_part*string

The part before the @ of the mailbox address.

display_name*string

Display name of the mailbox; null for none.

owner_account_id*string · uuid

Platform account that created the mailbox; null when created with an API key.

retention_days*number

Retention period in days.

Example: 14

status*object

`active` mailboxes receive mail; `disabled` ones reject it.

Example: "active"

created_at*string · date-time

When 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"
}