Anjal
Get started
All endpoints
Domains

Register a custom domain

POSThttps://anjal.app/v1/domains

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

Content-Type: application/json

domain
required
string
workspaceId
string

(Tenant master only) target workspace.

format: uuid

sharedWith
"google" | "microsoft" | "other"

Keep this provider as the domain's main mail server and add Anjal mailboxes alongside it (`shared_with` also works).

enum: "google" | "microsoft" | "other"

replaceMailProvider
boolean

Move all mail for the domain to Anjal (the returned MX record replaces the current one).

Responses

201application/jsonCreated
id
string

format: uuid

domain
string
status
"pending" | "verified" | "failed"

enum: "pending" | "verified" | "failed"

workspaceId
string

format: uuid

dnsRecords
object[]
type
"TXT" | "CNAME" | "MX" | "A"

enum: "TXT" | "CNAME" | "MX" | "A"

name
string
value
string
priority
integer
status
"pending" | "verified"

enum: "pending" | "verified"

note
string

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

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.

enum: "google" | "microsoft" | "other" | null

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

format: date-time

updatedAt
string

format: date-time

message
string
422application/jsonThe domain already receives mail at another provider
error
string
code
string
detectedProvider
"google" | "microsoft" | "other"

enum: "google" | "microsoft" | "other"

mx
string[]
fix
string

Authentication

Send your API key in the X-API-Key header (or Authorization: Bearer <key>). Any prefix accepted by this endpoint — tk_, wk_, ak_, or sa_ — is documented in the key prefix table.