---
title: "Set up email on a domain"
method: POST
path: "/api/domains/{domain}/email/setup"
tags: ["Email"]
---

# Set up email on a domain

`POST /api/domains/{domain}/email/setup`

## Request

- Base URL: `https://domani.run`
- URL: `https://domani.run/api/domains/{domain}/email/setup`
- Auth: HTTP bearer

Pre-configure email DNS on a domain (optional). This is called automatically by create_mailbox when needed. Pass force=true to override existing email provider (Google Workspace, Fastmail, Proton).

## Path parameters

- `domain` string, required

## Request body

- object
  - `force` boolean: Override existing email provider (Google Workspace, Fastmail, Proton). Default: false

## Response `200`

Email set up successfully

- object
  - `domain` string
  - `status` 'configured' | 'already_configured'
  - `verified_at` string, nullable
  - `receiving_verified` boolean: True when the domain's MX points at the platform's receiver, so mail for its addresses is accepted.
  - `sending_configured` boolean
  - `sending_verified` boolean
  - `records` DnsRecord[]
    - `type` 'A' | 'AAAA' | 'CNAME' | 'MX' | 'TXT' | 'NS' | 'SRV' | 'CAA' | 'TLSA', required: DNS record type. TLSA publishes a DANE record; its value is the rdata 'usage selector matching-type hex-data'.
    - `name` string, required: Record name (@ for root, or subdomain, e.g. _443._tcp for TLSA)
    - `value` string, required: Record value (IP address, hostname, or TLSA rdata like '3 1 1 abc123...')
    - `ttl` integer, required: Time to live in seconds
    - `priority` integer: Priority value (required for MX records)
    - `required` boolean: False when the zone Domani manages for the domain cannot hold the record (a TXT longer than the registrar accepts); such a record is shown but not needed for mail to work. Absent on plain zone records.
  - `hint` string

## Other responses

- `400`: Conflict - external email provider active. Pass force=true to override
- `503`: The outbound provider cannot accept another domain yet

---

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