Mail API reference

Mail API · Mailboxes

post/v1/workspaces/{workspace_id}/mailboxesAuth

Create a mailbox under a verified domain. Local-part + domain combination must be globally unique.

Path parameters

workspace_id*string · uuid

Id of the workspace.

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

local_part*string

Local part of the address (portion before @)

Example: "claude-qa-alpha"

domain_id*string · uuid

Domain ID.

retention_daysnumber

Retention period in days (1–30)

display_namestring

Human-readable display name

Response · 201

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

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