> ## Documentation Index
> Fetch the complete documentation index at: https://openmail-docs-cc-replies.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom domains

> Send and receive email from your own domain with OpenMail. Learn how to configure DNS records, verify ownership, and enable custom domain routing.

By default, inboxes use `@openmail.sh` addresses. With a custom domain you can use any domain you own — for example `agent@yourdomain.com`.

## How it works

1. Add your domain in the dashboard
2. OpenMail returns the DNS records you need to set
3. Once DNS propagates, verify the domain
4. Create inboxes on it by passing the domain when you create an inbox

## Adding a domain

Go to **Settings → Domains** in the dashboard and click **Add domain**. Enter the domain you want to use (e.g. `mail.acme.com`).

<Note>
  You can use a subdomain like `mail.acme.com` or an apex domain like `acme.com`. A subdomain is generally easier to configure without affecting other email on your domain.
</Note>

After adding your domain, OpenMail returns three DNS records to set at your registrar.

## DNS records

| Type | Host                                     | Value                                 |
| ---- | ---------------------------------------- | ------------------------------------- |
| MX   | `@` (or your subdomain)                  | `mxa.mailgun.org` (priority 10)       |
| MX   | `@` (or your subdomain)                  | `mxb.mailgun.org` (priority 10)       |
| TXT  | `@` (or your subdomain)                  | `v=spf1 include:spf.openmail.sh ~all` |
| TXT  | `openmail._domainkey` (+ your subdomain) | Provided by OpenMail                  |

**MX records** route inbound email to OpenMail.

**SPF record** authorises OpenMail to send on your domain's behalf. If you already have an SPF record, add `include:spf.openmail.sh` to the existing record rather than creating a new one.

**DKIM record** adds a cryptographic signature to outbound email, proving messages were sent by you. The value is unique to your account and provided after you add the domain.

DNS changes typically propagate within minutes but can take up to 48 hours.

## Verifying your domain

Once you've set your DNS records, click **Verify** in the dashboard. OpenMail checks all three record types and updates the domain status to `verified`.

If verification fails, double-check each record at your registrar and try again. Common issues:

* Existing MX records that weren't replaced
* SPF record merged incorrectly (only one `v=spf1` per domain is allowed)
* DKIM host copied without the subdomain suffix

## Using your domain

Once a domain shows as **Verified**, it is ready to use — there is no separate activation step. Verifying the domain is what makes it available.

Your account default domain never switches automatically. To create an inbox on your custom domain, choose it explicitly:

<CodeGroup>
  ```bash API theme={null}
  curl -X POST https://api.openmail.sh/v1/inboxes \
    -H "Authorization: Bearer $OPENMAIL_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "mailboxName": "support",
      "domain": "yourdomain.com"
    }'
  ```

  ```text Dashboard theme={null}
  Inboxes → Create inbox → pick yourdomain.com in the domain selector
  ```
</CodeGroup>

The resulting address uses your domain:

```
{mailboxName}@yourdomain.com
```

If you omit `domain`, the inbox is created on your account default domain (for example `@openmail.sh`). Passing a domain that is not verified or does not belong to your account returns `invalid_domain`.

## Limits

Custom domains are available on the Developer plan and above.

| Plan       | Custom domains |
| ---------- | -------------- |
| Free       | —              |
| Developer  | 10             |
| Launch     | 150            |
| Enterprise | Custom         |

## Removing a domain

You can delete a custom domain from the dashboard as long as it has no inboxes. Delete the inboxes on that domain first, then remove the domain.

Deleting a domain removes it from OpenMail but does not delete your DNS records — you can remove those from your registrar separately.