Domains API

Overview

The Domains API allows you to add custom domains to receive emails. After adding a domain, you'll need to configure DNS records and verify ownership before emails can be received. You can also manage domains from the dashboard.

List Domains

Retrieve all domains configured for your account.

curl -H "x-api-key: mh_your_api_key_here" \
     "undefined/api/v1/domains"

[
  {
    "id": "dom_1234567890",
    "domain": "mail.example.com",
    "verified": true,
    "enabled": true,
    "createdAt": "2024-01-01T00:00:00Z"
  }
]

Create Domain

Add a new custom domain to your account.

curl -X POST undefined/api/v1/domains \
     -H "x-api-key: mh_your_api_key_here" \
     -H "Content-Type: application/json" \
     -d '{
       "domain": "mail.example.com"
     }'

Get Domain Details

Retrieve details for a specific domain including DNS records and verification status.

curl -H "x-api-key: mh_your_api_key_here" \
     "undefined/api/v1/domains/dom_1234567890"

Verify Domain

Trigger domain verification after configuring DNS records. Mailhooks will check that the required MX and TXT records are properly configured.

curl -X POST undefined/api/v1/domains/mail.example.com/verify \
     -H "x-api-key: mh_your_api_key_here" \
     -H "Content-Type: application/json" \
     -d '{
       "code": "mh-verify-abc123"
     }'

Cloudflare Auto-Setup

If your domain is managed by Cloudflare, you can automatically configure DNS records using the Cloudflare API integration. This eliminates manual DNS configuration.

curl -X POST undefined/api/v1/domains/mail.example.com/setup-cloudflare \
     -H "x-api-key: mh_your_api_key_here" \
     -H "Content-Type: application/json" \
     -d '{
       "cloudflareApiToken": "your_cloudflare_api_token"
     }'

Enable / Disable Domain

Temporarily disable a domain to stop receiving emails, or re-enable it.

Delete Domain

Remove a domain from your account. This will stop all email reception for this domain.

Response Codes