---
title: "Purchase pre-warmed addresses on one domain"
method: POST
path: "/v1/prewarmed/purchase"
tags: ["Pre-warmed Marketplace"]
---

# Purchase pre-warmed addresses on one domain

`POST /v1/prewarmed/purchase`

## Request

- Base URL: `https://api.winnr.app`
- URL: `https://api.winnr.app/v1/prewarmed/purchase`
- Auth: HTTP bearer

Converts an available pre-warmed domain into a domain on your account with
live mailboxes. Two modes:

- **Keep** (default): you receive the domain's existing warmed addresses,
  credentials unchanged. Synchronous — the mailboxes are usable as soon as
  this call returns.
- **Custom** (`custom_usernames` present): the warmed sample addresses are
  dropped and brand-new mailboxes are provisioned with your local-parts on
  the same aged domain. Asynchronous — the response returns
  `provisioning: "async"` and the mailboxes appear on
  `GET /v1/email-users` a few minutes later. New mailboxes are not
  individually warmed but inherit the domain's reputation.

Warming is stopped at sale in both modes; the addresses are handed over
ready to send.

Billing is $3 per address per month with no minimum term, and the
domain is included. The first month is charged immediately and the purchase
is **fail-closed**: if the charge fails, everything is rolled back and you
are not billed. Pre-warmed mailboxes sit in a separate pool from your
regular mailbox allowance and are not counted against `email_user_limit`;
only `domain_limit` applies.

Idempotent per domain: repeating a successful purchase returns
`already_provisioned: true` without charging again.

## Request body

- PrewarmedPurchaseRequest
  - `domain` string, required: Pre-warmed domain to purchase. Normalized to lowercase.
  - `address_count` integer, required: How many of the domain's existing warmed addresses to take. Ignored when `custom_usernames` is supplied (the count is derived from that list).
  - `custom_usernames` string[], nullable: Optional. Custom-address mode: 3 to 10 unique local-parts to provision as NEW mailboxes on the warmed domain. The warmed sample addresses are dropped. Provisioning is asynchronous.

## Response `200`

Purchase completed

- PrewarmedPurchaseResponse
  - `data` object
    - `status` 'sold'
    - `domain` string
    - `address_count` integer
    - `minimum_term_end` string, date-time, nullable: Always null — the minimum term was removed in August 2026; cancellation is available anytime.
    - `provisioning` 'async': Present only in custom-address mode. The mailboxes are created in the background and appear on `GET /v1/email-users` shortly after.
    - `already_provisioned` boolean: Present when this domain was already purchased by your account. The call is a no-op and nothing was charged again.
  - `meta` Meta
    - `request_id` string
    - `timestamp` string, date-time

## Other responses

- `400`: Not purchasable. Includes `insufficient_inventory` (the domain has fewer warmed addresses than requested), a domain that is not in a purchasable state, or an infrastructure domain. No plan subscription is required — a missing payment method returns 402 `payment_method_required` instead.
- `401`: Authentication required or token invalid
- `403`: The pre-warmed marketplace is not enabled for this account
- `404`: Resource not found
- `409`: The domain was claimed by another buyer, or a non-pre-warmed domain with this name already exists on your account. Move to the next candidate.

---

[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)