Mail API reference

Mail API · Domains

post/v1/workspaces/{workspace_id}/domains/{domain_id}/share-linksAuth

Create a share link: a read-only DNS setup page for whoever manages the domain's DNS.

Returns a link (valid 1–7 days, default 7) to a public page that shows the domain name, its DNS records with copy-ready values, their live status and zone-file / CSV downloads, without an account. The page shows nothing else about the workspace. The link is shown only in this response (only its hash is stored); revoke it with `DELETE .../share-links/{link_id}`. Optionally emails it from ProductCraft to up to 5 recipients per domain per day (20 per workspace). Requires `mail.update` on the domain.

Path parameters

workspace_id*string · uuid

Id of the workspace.

domain_id*string · uuid

Id of the domain.

Headers

Idempotency-Keystring

Opaque client-generated string (1–256 chars, `[A-Za-z0-9._:-]`) used to deduplicate retries within a 24h window. A replay returns the same link and sends no second email.

Request body

expires_in_daysinteger

Days until the link stops working (1–7).

Example: 7

email_toarray

Optional: email the link to these people (whoever manages the DNS). At most 5 recipients per domain per UTC day and 20 per workspace, counted across all links; over that the request is refused with 429 and no link is created. Each recipient gets their own email from ProductCraft with the domain name, the link and its expiry.

Example: ["it@example.com"]

Response · 201

id*string · uuid

The share link id.

domain_id*string · uuid

The domain the link shares the DNS setup of.

status*object

`active` until `expires_at` or until revoked.

Example: "active"

created_by*string

Principal (`sub`) that created the link.

created_at*string · date-time

When the link was created.

expires_at*string · date-time

When the link stops working.

revoked_at*string · date-time

When the link was revoked; null while not revoked.

last_viewed_at*string · date-time

Last time the public page was opened (updated at most once a minute).

emailed_to_count*integer

How many recipients the link was emailed to.

Example: 1

url*string · uri

The page to send: a read-only setup page with the records, live status and downloads, no account needed. Shown only in this response; it cannot be retrieved again (only a hash is stored). When the request carried an `Idempotency-Key`, a retry with the same key within 24 h returns this same response.

Example: "https://console.productcraft.co/mail/setup/3q2-7wVdZ6xYb9mJk1Lr0pQs4tUv8wXyZaBcDeFgHiJ"

api_url*string · uri

The same link as JSON (`GET /v1/public/domain-setup/{token}`), for scripts.

Example: "https://api.mail.productcraft.co/v1/public/domain-setup/3q2-7wVdZ6xYb9mJk1Lr0pQs4tUv8wXyZaBcDeFgHiJ"

emailed_to*array

Recipients the email was queued for (an address whose email could not be queued is left out).

Example: ["it@example.com"]

Example

Request

POST https://api.mail.productcraft.co/v1/workspaces/{workspace_id}/domains/{domain_id}/share-links
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "expires_in_days": 7,
  "email_to": [
    "it@example.com"
  ]
}

Response

{
  "id": "00000000-0000-0000-0000-000000000000",
  "domain_id": "00000000-0000-0000-0000-000000000000",
  "status": "active",
  "created_by": "string",
  "created_at": "2026-01-01T00:00:00.000Z",
  "expires_at": "2026-01-01T00:00:00.000Z",
  "revoked_at": "2026-01-01T00:00:00.000Z",
  "last_viewed_at": "2026-01-01T00:00:00.000Z",
  "emailed_to_count": 1,
  "url": "https://console.productcraft.co/mail/setup/3q2-7wVdZ6xYb9mJk1Lr0pQs4tUv8wXyZaBcDeFgHiJ",
  "api_url": "https://api.mail.productcraft.co/v1/public/domain-setup/3q2-7wVdZ6xYb9mJk1Lr0pQs4tUv8wXyZaBcDeFgHiJ",
  "emailed_to": [
    "it@example.com"
  ]
}