Domains API
Manage custom domains for receiving emails with Mailhooks.
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.
GET https://mailhooks.dev/api/v1/domainsExample Request
curl -H "x-api-key: mh_your_api_key_here" \
"https://mailhooks.dev/api/v1/domains"Response
[
{
"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.
POST https://mailhooks.dev/api/v1/domainsRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
domain | string | Required | The domain name (e.g., mail.example.com) |
Example Request
curl -X POST https://mailhooks.dev/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.
GET https://mailhooks.dev/api/v1/domains/:idExample Request
curl -H "x-api-key: mh_your_api_key_here" \
"https://mailhooks.dev/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.
POST https://mailhooks.dev/api/v1/domains/:domain/verifyExample Request
curl -X POST https://mailhooks.dev/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.
POST https://mailhooks.dev/api/v1/domains/:domain/setup-cloudflareRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
cloudflareApiToken | string | Required | Cloudflare API token with Zone:DNS:Edit permissions |
zoneId | string | Optional | Cloudflare Zone ID (auto-detected if not provided) |
Example Request
curl -X POST https://mailhooks.dev/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"
}'Zone:DNS:Edit permissions. The endpoint will automatically create MX and TXT records for domain verification.Enable / Disable Domain
Temporarily disable a domain to stop receiving emails, or re-enable it.
Enable
POST https://mailhooks.dev/api/v1/domains/:id/enableDisable
POST https://mailhooks.dev/api/v1/domains/:id/disableDelete Domain
Remove a domain from your account. This will stop all email reception for this domain.
DELETE https://mailhooks.dev/api/v1/domains/:idResponse Codes
| Code | Description |
|---|---|
200 | Successful request |
201 | Domain created successfully |
400 | Invalid domain or DNS verification failed |
401 | Unauthorized - Invalid API key |
404 | Domain not found |
409 | Domain already exists |