/v1/workspaces/{workspace_id}/mailboxesAuthCreate a mailbox under a verified domain. Local-part + domain combination must be globally unique.
Path parameters
workspace_id*string · uuidId of the workspace.
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
local_part*stringLocal part of the address (portion before @)
Example: "claude-qa-alpha"
domain_id*string · uuidDomain ID.
retention_daysnumberRetention period in days (1–30)
display_namestringHuman-readable display name
Response · 201
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
POST https://api.mail.productcraft.co/v1/workspaces/{workspace_id}/mailboxes
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
{
"local_part": "claude-qa-alpha",
"domain_id": "00000000-0000-0000-0000-000000000000",
"retention_days": 0,
"display_name": "string"
}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"
}