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

# Register a custom domain

`POST /v1/domains`

## Request

- Base URL: `https://anjal.app`
- URL: `https://anjal.app/v1/domains`
- Auth: API key in header `X-API-Key`

Returns the DNS records you need to set at your registrar. Domain starts in `pending` status until you call the verify endpoint.

**Domains that already get mail elsewhere (Google Workspace, Microsoft 365).**
If the domain has MX records at another provider and you pass neither
`sharedWith` nor `replaceMailProvider`, the call returns
`422 DOMAIN_HAS_MAIL_PROVIDER` with `detectedProvider`, `mx` and a
`fix` string, because pointing the MX at Anjal would cut off that mail.
You then have three options:

1. **Keep the provider** (`sharedWith: "google" | "microsoft" | "other"`).
   No MX record is returned: the provider stays the main mail server.
   The SPF TXT record is merged into the domain's existing SPF (its
   `note` says to replace the existing record, since a domain may have
   only one). Anjal's DMARC record is only included if the domain has
   none. The response includes `routingSteps` for the provider's admin
   console: for Google, a Default routing rule that sends mail for
   non-recognized addresses to the Anjal host; for Microsoft, setting
   the Accepted domain to Internal relay plus an outbound connector to
   the Anjal smart host. In this setup the provider forwards mail for
   addresses it doesn't know, so it keeps its own users and Anjal
   receives mail only for addresses the provider doesn't have.
2. **Use a subdomain** such as `agents.example.com`, which has no MX
   yet and can point at Anjal without touching the main domain's mail.
3. **Move all mail to Anjal** (`replaceMailProvider: true`). The MX
   record returned replaces the current provider's.

## Request body

- object
  - `domain` string, required
  - `workspaceId` string, uuid: (Tenant master only) target workspace.
  - `sharedWith` 'google' | 'microsoft' | 'other': Keep this provider as the domain's main mail server and add Anjal mailboxes alongside it (`shared_with` also works).
  - `replaceMailProvider` boolean: Move all mail for the domain to Anjal (the returned MX record replaces the current one).

## Response `201`

Created

- object
  - `id` string, uuid
  - `domain` string
  - `status` 'pending' | 'verified' | 'failed'
  - `workspaceId` string, uuid
  - `dnsRecords` DnsRecord[]
    - `type` 'TXT' | 'CNAME' | 'MX' | 'A'
    - `name` string
    - `value` string
    - `priority` integer, nullable
    - `status` 'pending' | 'verified', nullable
    - `note` string, nullable: Extra instructions for this record. On a shared domain the SPF record is merged into your existing one, and the note says to replace the existing record (a domain must have only one SPF record).
  - `sharedWith` 'google' | 'microsoft' | 'other' | 'null', nullable: Set when the domain's main mail stays at another provider (Google Workspace, Microsoft 365 or other) and Anjal mailboxes live alongside it. Null for a domain whose MX points at Anjal.
  - `routingSteps` string[]: Present only for shared domains. Steps for the provider's admin console so it passes mail for addresses it doesn't know on to Anjal.
  - `createdAt` string, date-time
  - `updatedAt` string, date-time
  - `message` string

## Other responses

- `422`: The domain already receives mail at another provider

---

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