---
title: "Add a custom domain"
method: POST
path: "/v1/domains"
tags: ["domains"]
---

# Add a custom domain

`POST /v1/domains`

## Request

- Base URL: `https://api.mailfixture.com`
- URL: `https://api.mailfixture.com/v1/domains`
- Auth: HTTP bearer

Registers a custom receiving domain. The response's `setup` object carries the exact TXT challenge and MX records to publish; mail is accepted only after verification. Newly created domains are auto-rechecked every 60 s for their first 7 days.

## Request body

- CreateDomainRequest
  - `fqdn` string, required: Fully-qualified domain like mail.example.com; trimmed, trailing dot stripped, lowercased. Prefer a dedicated subdomain.

## Response `201`

Domain registered, verification pending.

- Domain
  - `created_at` string, date-time, required
  - `fqdn` string, required
  - `id` string, uuid, required
  - `kind` 'shared' | 'custom', required
  - `mx_ok_at` string, date-time, nullable, required
  - `setup` DomainSetup
    - `mx` object, required
      - `name` string, required
      - `priority` integer, required
      - `value` string, required: The MX hostname to point at.
    - `txt` object, required
      - `name` string, required: Record name, `_mfx.<fqdn>`.
      - `value` string, required: Record value, `mfx-verify=<token>`.
  - `verified_at` string, date-time, nullable, required
  - `verify_txt_token` string, nullable, required: TXT challenge value; null for shared domains.

## Other responses

- `400`: `fqdn` is not a valid domain name.
- `401`: Missing bearer token, malformed key, or unknown/revoked/invalid API key.
- `403`: Custom domains require a paid plan.
- `409`: That domain is already registered.
- `429`: Per-key rate limit exceeded. `Retry-After` says when the next request will be admitted; the RateLimit headers name the bucket that refused (`requests` or `creates`) with `r=0`.
- `500`: Unexpected server error. `detail` is null — internals are never leaked.

---

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