---
title: "Convert an owned domain to the Subdomain Strategy"
method: POST
path: "/v1/domains/convert-subdomain-strategy"
tags: ["Domains"]
---

# Convert an owned domain to the Subdomain Strategy

`POST /v1/domains/convert-subdomain-strategy`

## Request

- Base URL: `https://api.winnr.app`
- URL: `https://api.winnr.app/v1/domains/convert-subdomain-strategy`
- Auth: HTTP bearer

Provisions up to 5 subdomains under a domain the account already owns.
Each subdomain becomes a full email domain (own DKIM/SPF/MX/DMARC and
mail server configuration) whose DNS records live inside the parent's zone, and
can carry up to 10 mailboxes. Free — no charge and no registration.

Mailboxes per subdomain are optional (`users` may be empty); they can
be added later via the email-users endpoints, which enforce the
5-per-subdomain cap. Retry-safe: re-sending the same request re-queues
provisioning for the same children without duplicating them.

Eligibility: the domain must have been purchased through Winnr
(registration complete), be fully provisioned (DNS complete), sit on
Winnr-managed DNS (Cloudflare or the winnr_X fleet), and not be a
subdomain or a pre-warmed marketplace domain. Ineligible domains get a
400 with a specific `code` (`not_registered_through_winnr`,
`dns_not_ready`, `unsupported_dns_provider`, `pre_warmed`,
`is_subdomain`, `domain_not_active`, `cloudflare_zone_unknown`,
`subdomain_limit`, `email_user_limit`).

## Request body

- object
  - `domain` string, required: Domain name already owned by the account
  - `subdomains` object[], required
    - `label` string, required: Subdomain label (validated against reserved and cold-email-signaling names)
    - `users` object[]: Optional mailboxes to create on this subdomain now
      - `name` string
      - `username` string, required

## Response `200`

Subdomains queued for provisioning

- object
  - `meta` Meta
    - `request_id` string
    - `timestamp` string, date-time
  - `data` object
    - `domain` string
    - `domain_id` string
    - `dns_provider` string
    - `message` string
    - `subdomains` object[]
      - `domain` string
      - `domain_id` string
      - `job_id` string
      - `status` string

## Other responses

- `400`: Validation error
- `401`: Authentication required or token invalid
- `404`: Resource not found

---

[API](https://skmtc.dev/winnr/apis/winnr-api.md) · [All operations](https://skmtc.dev/winnr/apis/winnr-api/llms.txt) · [OpenAPI document](https://skmtc.dev/winnr/apis/winnr-api/revisions/a4f960beb1eb?raw)