---
title: "Purchase domains"
method: POST
path: "/domains"
tags: ["Domains"]
---

# Purchase domains

`POST /domains`

## Request

- Base URL: `https://api.mailforge.ai/public`
- URL: `https://api.mailforge.ai/public/domains`
- Auth: API key in header `Authorization`

Purchases one or more domain names, creates DNS records, and triggers registration. Contact details are used for WHOIS registration.
For some ccTLDs (e.g. .eu), pass required Enom extended attributes in contactDetails.extra (discover via GET /public/domains/extra-fields). Missing required extras return 400 before charging.

## Request body

- ApiBuyDomainsRequest
  - `contactDetails` ApiContactDetails
    - `address1` string
    - `address2` string
    - `city` string
    - `country` string
    - `dmarcEmail` string
    - `email` string
    - `extra` object: Extra holds TLD-specific Enom extended attributes (e.g. eu_whoispolicy for .eu). Optional overall; required keys depend on the TLDs being purchased — discover via GET /public/domains/extra-fields.
    - `firstName` string
    - `forwardToDomain` string
    - `jobTitle` string
    - `lastName` string
    - `organization` string
    - `phone` string
    - `postalCode` string
    - `province` string
  - `domains` string[]
  - `workspaceId` string

## Response `200`

OK

- ApiBuyDomainsResponse
  - `domains` MailforgeExternalApiDeliveryApiDomainResponse[]
    - `autoRenewFailedReason` string
    - `autoRenewLastProcessedExpiration` string
    - `autoRenewProcessedAt` string
    - `autoRenewStatus` 'disabled' | 'enabled' | 'failed'
    - `createdAt` string
    - `dmarcEmail` string
    - `expiresAt` string
    - `failedReason` string
    - `forwardToDomain` string
    - `id` string
    - `isTransferred` boolean
    - `mailDeletionAt` string
    - `mailServerId` integer
    - `nameservers` string[]
    - `priceCents` integer
    - `setupId` string
    - `sld` string
    - `status` 'draft' | 'active' | 'pending' | 'failed' | 'expired' | 'warning' | 'scheduled_for_deletion' | 'not_paid'
    - `tld` string
    - `type` 'v2'
    - `updatedAt` string
    - `workspaceId` string

## Other responses

- `400`: Domain not available, invalid request, or missing required contactDetails.extra fields
- `402`: No payment method on file

---

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