Mail API reference

Mail API · Domains

get/v1/workspaces/{workspace_id}/domainsAuth

List domains registered to this workspace (newest first), cursor-paginated.

Path parameters

workspace_id*string · uuid

Id of the workspace.

Query parameters

limitinteger

Page size. Defaults to 20; values above 100 are clamped to 100.

cursorstring

Opaque cursor from the previous page's `pagination.next_cursor`. Omit for the first page.

searchstring

Case-insensitive substring match on the domain fqdn.

statusenum (8)

Filter by `verification_status` (`not_started`, `pending`, `partially_verified`, `verified`, `temporary_failure`, `failed`, `disabled`), applied in the query so the cursor keeps its meaning. The legacy `status` value `active` is still accepted and matches `status = active`. `pending` now means the `verification_status` (checked, not verified yet, within 72 h); before 2026-10 it matched `status = pending`, which is `not_started`, `pending`, `partially_verified` and the pending part of `failed`. Unrecognised values are rejected with a 400.

Response · 200

data*array

The domains on this page.

pagination*object
next_cursor*string

Opaque cursor for the next page. `null` when no more pages are available.

Example: "eyJjcmVhdGVkX2F0IjoiMjAyNi0wNS0wMVQwMDowMDowMFoifQ"

has_more*boolean

True iff another page exists; if true, pass `next_cursor` on the next request.

Example: false

Example

Request

GET https://api.mail.productcraft.co/v1/workspaces/{workspace_id}/domains
Authorization: Bearer YOUR_TOKEN

Response

{
  "data": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "seq_id": "3",
      "workspace_id": "00000000-0000-0000-0000-000000000000",
      "owner_account_id": "00000000-0000-0000-0000-000000000000",
      "fqdn": "productcraft.co",
      "name": "productcraft.co",
      "intent": {},
      "capabilities": {
        "sending": "enabled",
        "receiving": "disabled"
      },
      "tls": "opportunistic",
      "open_tracking": false,
      "click_tracking": false,
      "tracking_subdomain": null,
      "status": "pending",
      "health": "ok",
      "health_changed_at": "2026-01-01T00:00:00.000Z",
      "health_grace_ends_at": "2026-01-01T00:00:00.000Z",
      "verification_token": "string",
      "test_token": "string",
      "test_received_at": "2026-01-01T00:00:00.000Z",
      "dkim_selector": "string",
      "dkim_public_key": "string",
      "dns_provider": {},
      "dns_provider_id": "cloudflare",
      "dns_provider_detected": {},
      "verification_status": "pending",
      "recommended_pending": 2,
      "region": "eu-north-1",
      "region_name": "Stockholm",
      "dns_check_results": {},
      "last_dns_check_at": "2026-01-01T00:00:00.000Z",
      "dns_zone": "example.com",
      "ses_dkim_status": {},
      "mail_from_subdomain": "bounce",
      "mail_from_status": {},
      "dmarc_managed": true,
      "setup_method": null,
      "dmarc_grade": {},
      "verified_at": "2026-01-01T00:00:00.000Z",
      "created_at": "2026-01-01T00:00:00.000Z",
      "dns_instructions": [
        {
          "purpose": "dkim",
          "type": "TXT",
          "host": "productcraft._domainkey.mail.example.com",
          "value": "string",
          "ttl": 0,
          "priority": 0,
          "required": true
        }
      ],
      "records": [
        {
          "record": "DKIM",
          "purpose": "dkim",
          "name": "productcraft._domainkey.mail",
          "type": "TXT",
          "value": "string",
          "priority": 10,
          "ttl": 3600,
          "status": "verified",
          "required": true
        }
      ],
      "test_address": "test-abc123@productcraft.co"
    }
  ],
  "pagination": {
    "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wNS0wMVQwMDowMDowMFoifQ",
    "has_more": false
  }
}