---
title: "Add an email sender domain"
method: POST
path: "/email-domains"
tags: ["Domains"]
---

# Add an email sender domain

`POST /email-domains`

## Request

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

Registers a custom domain for the board’s outgoing email (job alerts, magic links, receipts, Inbox replies) and returns the DNS records to publish. The setup loop is: create the domain, publish every required record in `dnsRecords` at the DNS provider (DNS-only, not proxied), then call `POST /email-domains/{id}/verify` until `status` is `verified`. Cavuno also re-checks pending domains in the background and emails the board owners when the domain verifies. Until then board email keeps sending from the Cavuno address. Requires an active primary custom domain (see `POST /domains`) and a plan that includes branding removal.

## Request body

- CreateEmailDomainBody
  - `domain` string, required: Hostname to send from. It must be the board’s active primary custom domain or one of its subdomains; a subdomain such as `notifications.acme.com` is recommended so the main domain’s email reputation stays separate. Normalized to lowercase.
  - `senderName` string: Display name recipients see in the From header, for example `Acme Jobs`. Defaults to the board name.
  - `senderLocalPart` string: Mailbox before the `@`, for example `info` or `hello`. Defaults to `info`. Normalized to lowercase.

## Response `201`

Successful response.

- EmailDomain
  - `id` string, required
  - `object` 'email_domain', required
  - `domain` string, required: The sending hostname.
  - `status` 'pending' | 'verified' | 'failed', required: `pending` until the required DNS records verify, `verified` once board email sends from this domain, `failed` when the last check found a problem (see `statusReason`; publish or fix the records and verify again).
  - `senderName` string, required
  - `senderLocalPart` string, required
  - `senderAddress` string, required: The From address once the domain is verified.
  - `dnsRecords` EmailDomainDnsRecord[], required: Records to publish at the domain’s DNS provider. Empty while the domain is still being set up with the email provider; call verify to retry.
    - `purpose` 'dkim' | 'return_path' | 'dmarc', required: `dkim` signs outgoing mail, `return_path` receives bounces and complaints, `dmarc` is an optional policy record.
    - `type` string, required: DNS record type, for example `CNAME` or `TXT`.
    - `name` string, required: Host to create the record on, relative to the DNS zone the domain lives in (`@` is the zone itself), as most DNS providers expect it typed.
    - `value` string, required: Exact value to publish.
    - `ttl` string, required: Suggested TTL. `Auto` means the DNS provider’s default.
    - `required` boolean, required: Whether the domain needs this record to send. DMARC is recommended but optional.
    - `status` string, required: Last check of this record: `pending`, `verified`, or `failed`.
  - `statusReason` 'setup_required' | 'dns_verification_failed', nullable, required: Why the last check failed, when it did. `setup_required`: the domain must be set up with the email provider again; call verify, which re-stages it and returns fresh DNS records. `dns_verification_failed`: the published records do not match yet; check each record’s `status`, fix them and verify again.
  - `verifiedAt` string, nullable, required
  - `lastCheckedAt` string, nullable, required
  - `createdAt` string, required

## Other responses

- `400`: The hostname is malformed or is not the primary custom domain or one of its subdomains (`email_domains_invalid_hostname`).
- `403`: The plan does not include custom sender domains (`email_domains_plan_required`; Basic and above).
- `409`: The board already has a sender domain (`email_domains_already_exists`), or has no active primary custom domain (`email_domains_primary_domain_required`).
- `502`: The email provider failed or is unavailable (`email_domains_provider_error`). Retry later.

## Changes

- **2026-10-19** `c34152c38176`: 4 info
  - added the optional property `error/upgrade` to the response with the `400` status
  - added the optional property `error/upgrade` to the response with the `403` status
  - added the optional property `error/upgrade` to the response with the `409` status
  - added the optional property `error/upgrade` to the response with the `502` status

[Operation history](https://skmtc.dev/cavuno/apis/cavuno-v1-rest-api/changes/email-domains/post.md)

---

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