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

# Add a custom sending domain

`POST /api/v1/domains`

## Request

- Base URL: `https://postfleet.ai`
- URL: `https://postfleet.ai/api/v1/domains`
- Auth: HTTP bearer

Registers a custom domain with the provider and returns the DNS records to add. Account-plane, paid plan only. Returns `200` (not `201`).

## Request body

- object
  - `name` string, required: Domain name, e.g. mail.example.com.

## Response `200`

Domain registered; add the returned DNS records to verify it.

- DomainCreated
  - `id` string, required
  - `name` string, required
  - `status` 'pending' | 'verified' | 'failed', required
  - `records` object[], required: Provider DNS records to add for verification.

## Other responses

- `400`: Invalid domain name.
- `401`: Missing or invalid bearer token, or a key whose scope is not permitted for this endpoint.
- `403`: Mailbox-bound key (`code:key_scope`), custom domains require a paid plan, or the email provider has reached its domain cap (`code:provider_domain_limit`; not the Postfleet $20 plan).
- `409`: Domain already registered with Postfleet or the email provider.
- `502`: Email provider rejected the name for a reason other than already-registered or domain cap.
- `503`: Email provider is not configured.

---

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