title: "Domains" description: "Add custom domains to MachineMail, get their DNS records, zone file and Domain Connect setup, verify them and turn on catch-all, for the organization or a pod." canonical: "https://machinemail.dev/docs/reference/api/domains"

Domains

Add custom domains to MachineMail, get their DNS records, zone file and Domain Connect setup, verify them and turn on catch-all, for the organization or a pod.

Source: https://machinemail.dev/docs/reference/api/domains

List Domains

GET /v0/domains

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: domain_read.

Query parameters

Response

200 A page of domains (application/json)

Each item of domains is a DomainItem:

Errors

Error bodies use the error envelope.

Example

curl "https://api.machinemail.dev/v0/domains" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

{
  "count": 1,
  "limit": 50,
  "next_page_token": "eyJvIjo1MH0",
  "domains": [
    {
      "pod_id": "pod_01k6x2m9qd0001b8j4mr0w3d5f",
      "domain_id": "dom_01k6x3d5kq0000g3q9sx5b8j0m",
      "domain": "example.com",
      "feedback_enabled": false,
      "inbound_enabled": false,
      "subdomains_enabled": false,
      "tracking_enabled": false,
      "client_id": "my-client-id",
      "updated_at": "2026-10-01T12:00:00.000Z",
      "created_at": "2026-10-01T12:00:00.000Z",
      "status": "NOT_STARTED",
      "reason": "string",
      "records": [
        {
          "type": "TXT",
          "name": "Production",
          "value": "string",
          "status": "MISSING",
          "priority": 1,
          "reason": "string",
          "purpose": "inbound",
          "required": false
        }
      ],
      "organization_id": "org_01k6x2m9qd0000a7h3kq9v2c4e",
      "catch_all": false,
      "catch_all_ttl_seconds": 1,
      "nameservers": ["string"],
      "dns_provider": "cloudflare",
      "dns_provider_url": "https://example.com",
      "domain_connect": {
        "supported": false,
        "provider_name": "string",
        "apply_url": "https://example.com"
      },
      "verified_at": "2026-10-01T12:00:00.000Z",
      "last_checked_at": "2026-10-01T12:00:00.000Z"
    }
  ]
}

Create Domain

POST /v0/domains

Registers the domain and returns the DNS records to publish (status: NOT_STARTED). Publish them, then call Verify Domain. A background worker re-checks PENDING, INVALID and VERIFYING domains about every 5 minutes until 7 days after creation; a NOT_STARTED domain is only checked by Verify Domain. A domain that is never verified is removed 14 days after it was added, together with its inboxes and the mail in them; owners and admins of the organization are emailed at least 3 days before. A domain that was verified once is never removed this way.

A domain can be registered by one organization only (409), and the shared domain cannot be added (409). Inbox-scoped credentials cannot add domains (403).

allow_conflicting_provider, subdomains_enabled and tracking_enabled are not supported.

502 upstream_error when the email provider cannot register the domain (for example its domain capacity is reached, or it is rate limiting registrations): nothing is created.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: domain_create.

Request body

Content type: application/json.

Response

200 A domain with this client_id already exists; it is returned unchanged. (application/json)

Each item of records is a VerificationRecord:

201 Created (application/json)

Each item of records is a VerificationRecord:

Errors

Error bodies use the error envelope.

Example

curl -X POST "https://api.machinemail.dev/v0/domains" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "domain": "example.com",
  "feedback_enabled": false
}'

{
  "pod_id": "pod_01k6x2m9qd0001b8j4mr0w3d5f",
  "domain_id": "dom_01k6x3d5kq0000g3q9sx5b8j0m",
  "domain": "example.com",
  "feedback_enabled": false,
  "inbound_enabled": false,
  "subdomains_enabled": false,
  "tracking_enabled": false,
  "client_id": "my-client-id",
  "updated_at": "2026-10-01T12:00:00.000Z",
  "created_at": "2026-10-01T12:00:00.000Z",
  "status": "NOT_STARTED",
  "reason": "string",
  "records": [
    {
      "type": "TXT",
      "name": "Production",
      "value": "string",
      "status": "MISSING",
      "priority": 1,
      "reason": "string",
      "purpose": "inbound",
      "required": false
    }
  ],
  "organization_id": "org_01k6x2m9qd0000a7h3kq9v2c4e",
  "catch_all": false,
  "catch_all_ttl_seconds": 1,
  "nameservers": ["string"],
  "dns_provider": "cloudflare",
  "dns_provider_url": "https://example.com",
  "domain_connect": {
    "supported": false,
    "provider_name": "string",
    "apply_url": "https://example.com"
  },
  "verified_at": "2026-10-01T12:00:00.000Z",
  "last_checked_at": "2026-10-01T12:00:00.000Z"
}

Get Domain

GET /v0/domains/{domain_id}

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: domain_read.

Path parameters

Response

200 The domain (application/json)

Each item of records is a VerificationRecord:

Errors

Error bodies use the error envelope.

Example

curl "https://api.machinemail.dev/v0/domains/dom_01k6x3d5kq0000g3q9sx5b8j0m" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

Update Domain

PATCH /v0/domains/{domain_id}

Fields you omit are unchanged. subdomains_enabled and tracking_enabled are not supported.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: domain_update.

Path parameters

Request body

Content type: application/json.

Response

200 The updated domain (application/json)

Each item of records is a VerificationRecord:

Errors

Error bodies use the error envelope.

Example

curl -X PATCH "https://api.machinemail.dev/v0/domains/dom_01k6x3d5kq0000g3q9sx5b8j0m" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "feedback_enabled": false
}'

Delete Domain

DELETE /v0/domains/{domain_id}

Inboxes on the domain are not deleted.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: domain_delete.

Path parameters

Response

200 Deleted (application/json)

Errors

Error bodies use the error envelope.

Example

curl -X DELETE "https://api.machinemail.dev/v0/domains/dom_01k6x3d5kq0000g3q9sx5b8j0m" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

{
  "ok": true
}

Get Domain Connect Setup

GET /v0/domains/{domain_id}/domain-connect

Discovers whether the domain's DNS provider supports Domain Connect (TXT _domainconnect.<zone> and the provider's /v2/<zone>/settings) and has onboarded the MachineMail template (machinemail.dev/email). When it has, apply_url is a signed synchronous-flow link (RS256, key=_dck1, sig last) that opens the provider with the outstanding MX, SPF, DKIM and DMARC records prefilled. Discovery is cached on the domain (6 h; provider errors 10 min) and re-run by Verify Domain.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: domain_read.

Path parameters

Response

200 Domain Connect support for the domain (application/json)

Errors

Error bodies use the error envelope.

Example

curl "https://api.machinemail.dev/v0/domains/dom_01k6x3d5kq0000g3q9sx5b8j0m/domain-connect" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

{
  "supported": false,
  "provider_name": "string",
  "apply_url": "https://example.com",
  "provider_id": "string",
  "url_sync_ux": "string",
  "width": 1,
  "height": 1,
  "reason": "no_domain_connect",
  "checked_at": "2026-10-01T12:00:00.000Z"
}

Verify Domain

POST /v0/domains/{domain_id}/verify

Checks every DNS record now, updates records[].status and status, and re-runs Domain Connect discovery. A domain.verified event is emitted when the domain becomes VERIFIED.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: domain_update.

Path parameters

Response

200 The domain after the check (application/json)

Each item of records is a VerificationRecord:

Errors

Error bodies use the error envelope.

Example

curl -X POST "https://api.machinemail.dev/v0/domains/dom_01k6x3d5kq0000g3q9sx5b8j0m/verify" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

Get Zone File

GET /v0/domains/{domain_id}/zone-file

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: domain_read.

Path parameters

Response

200 A BIND zone file with the records to publish (text/plain)

Headers:

Errors

Error bodies use the error envelope.

Example

curl "https://api.machinemail.dev/v0/domains/dom_01k6x3d5kq0000g3q9sx5b8j0m/zone-file" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

List Domains in Pod

GET /v0/pods/{pod_id}/domains

Same as List Domains (GET /v0/domains), limited to the pod.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: domain_read.

Path parameters

Query parameters

Response

200 A page of domains (application/json)

Each item of domains is a DomainItem:

Errors

Error bodies use the error envelope.

Example

curl "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/domains" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

Create Domain in Pod

POST /v0/pods/{pod_id}/domains

Same as Create Domain (POST /v0/domains), limited to the pod.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: domain_create.

Path parameters

Request body

Content type: application/json.

Response

200 A domain with this client_id already exists; it is returned unchanged. (application/json)

Each item of records is a VerificationRecord:

201 Created (application/json)

Each item of records is a VerificationRecord:

Errors

Error bodies use the error envelope.

Example

curl -X POST "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/domains" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "domain": "example.com",
  "feedback_enabled": false
}'

Get Domain in Pod

GET /v0/pods/{pod_id}/domains/{domain_id}

Same as Get Domain (GET /v0/domains/{domain_id}), limited to the pod.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: domain_read.

Path parameters

Response

200 The domain (application/json)

Each item of records is a VerificationRecord:

Errors

Error bodies use the error envelope.

Example

curl "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/domains/dom_01k6x3d5kq0000g3q9sx5b8j0m" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

Update Domain in Pod

PATCH /v0/pods/{pod_id}/domains/{domain_id}

Same as Update Domain (PATCH /v0/domains/{domain_id}), limited to the pod.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: domain_update.

Path parameters

Request body

Content type: application/json.

Response

200 The updated domain (application/json)

Each item of records is a VerificationRecord:

Errors

Error bodies use the error envelope.

Example

curl -X PATCH "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/domains/dom_01k6x3d5kq0000g3q9sx5b8j0m" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "feedback_enabled": false
}'

Delete Domain in Pod

DELETE /v0/pods/{pod_id}/domains/{domain_id}

Same as Delete Domain (DELETE /v0/domains/{domain_id}), limited to the pod.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: domain_delete.

Path parameters

Response

200 Deleted (application/json)

Errors

Error bodies use the error envelope.

Example

curl -X DELETE "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/domains/dom_01k6x3d5kq0000g3q9sx5b8j0m" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

{
  "ok": true
}

Get Domain Connect Setup in Pod

GET /v0/pods/{pod_id}/domains/{domain_id}/domain-connect

Same as Get Domain Connect Setup (GET /v0/domains/{domain_id}/domain-connect), limited to the pod.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: domain_read.

Path parameters

Response

200 Domain Connect support for the domain (application/json)

Errors

Error bodies use the error envelope.

Example

curl "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/domains/dom_01k6x3d5kq0000g3q9sx5b8j0m/domain-connect" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

Verify Domain in Pod

POST /v0/pods/{pod_id}/domains/{domain_id}/verify

Same as Verify Domain (POST /v0/domains/{domain_id}/verify), limited to the pod.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: domain_update.

Path parameters

Response

200 The domain after the check (application/json)

Each item of records is a VerificationRecord:

Errors

Error bodies use the error envelope.

Example

curl -X POST "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/domains/dom_01k6x3d5kq0000g3q9sx5b8j0m/verify" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

Get Zone File in Pod

GET /v0/pods/{pod_id}/domains/{domain_id}/zone-file

Same as Get Zone File (GET /v0/domains/{domain_id}/zone-file), limited to the pod.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: domain_read.

Path parameters

Response

200 A BIND zone file with the records to publish (text/plain)

Headers:

Errors

Error bodies use the error envelope.

Example

curl "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/domains/dom_01k6x3d5kq0000g3q9sx5b8j0m/zone-file" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"