> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devhelm.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom domains and DNS

> Publish TXT and MX records so a hostname you own can receive test mail

A custom domain receives test mail on a hostname you control. Custom domains are available on Team, Business, and Enterprise. Free and Developer use the assigned domain only.

Mail is accepted after both DNS records are in place and verification succeeds. Until then the domain stays pending and senders are refused.

## Create the domain

```bash theme={null}
devhelm email domains create --name mail-test.example.com
```

```bash theme={null}
curl -X POST "https://api.devhelm.io/api/v1/email/domains" \
  -H "Authorization: Bearer $DEVHELM_API_TOKEN" \
  -H "x-phelm-workspace-id: $DEVHELM_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{"kind":"custom","name":"mail-test.example.com"}'
```

Use a subdomain you do not send real mail from. Its MX record will point at DevHelm.

## Publish DNS

Add both records at your DNS provider. The verification token is on the domain; `devhelm email domains get` prints the records.

| Type | Host | Value |
| - | - | - |
| TXT | `_devhelm-verification.mail-test.example.com` | `devhelm-verification=<token>` |
| MX | `mail-test.example.com` | `mx.devhelmmail.com` (priority 10) |

```bash theme={null}
devhelm email domains get mail-test.example.com
```

## Verify

```bash theme={null}
devhelm email domains verify mail-test.example.com
```

```bash theme={null}
curl -X POST "https://api.devhelm.io/api/v1/email/domains/mail-test.example.com/verify" \
  -H "Authorization: Bearer $DEVHELM_API_TOKEN" \
  -H "x-phelm-workspace-id: $DEVHELM_WORKSPACE_ID"
```

When both records resolve, the domain becomes active and any address on it can receive mail. DNS changes can take a few minutes to show up. Leave the records in place after verification.

## Next steps

<CardGroup cols={2}>
  <Card title="How capture works" icon="envelope" href="/testing/email/overview">
    What an active domain stores, and how long it is kept.
  </Card>

  <Card title="Wait for an email" icon="timer" href="/testing/email/wait">
    Block a test on an address at this domain.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.