Add a custom domain
cooper_add_domainUse this when the user wants mail on their own hostname and the account is on Starter or Pro. Requires auth. One call returns the SPF, DKIM, DMARC, and MX records to publish, plus a verify TXT. Inputs: domain (required hostname, such as agents.example.com), client_id (optional idempotency key). Returns {id, domain, status, status_detail, mail, records, warnings, dns}. Each record includes status (valid, missing, or invalid), found from the last check, and hint. hint is null when the record is valid or no specific mistake was found. Otherwise hint is {code, message, found_at} and says what to change. warnings is an empty array when none. existing_mail_provider means this hostname already has MX at another provider. mail.receiving, mail.sending, and mail.inboxes stay false until the matching records for that domain verify. Inboxes on your own domain are included on Starter (15 custom domains) and Pro (200 custom domains). Free includes 0 custom domains and returns HTTP 402 plan_limit_exceeded. When the hostname is already a zone on the operator Cloudflare account, Cooper writes the DNS records and dns.mode is automatic. Cooper does not register a domain or create a zone. Any other zone stays manual. Publish the routing MX hosts, TXT SPF v=spf1 include:_spf.mx.cloudflare.net ~all, the routing DKIM TXT, the cf-bounce MX, SPF, and DKIM records, a DMARC TXT (an existing DMARC record is left as it is), and the _cooper-verify TXT. mail.receiving stays false until the receiving records check out and the catch-all is live. Receiving goes live within a few minutes. status_detail says so while you wait. POST /api/v1/inboxes with domain then creates username@domain. DELETE /api/v1/domains/:id puts back the catch-all that was there before, deletes only the DNS records Cooper created, turns Email Routing off only if Cooper turned it on, and removes the sending domain only if Cooper created it. A cleanup that does not finish keeps the row with status cleanup_failed and deleted false so a later delete can finish it. status is pending until DNS matches; calling again with the same domain returns the current status and does not create a second domain. dns.mode is automatic only when Cooper already controls that Cloudflare zone and wrote the records there; otherwise publish the records yourself. Cooper does not register a domain or create a zone. HTTP 402 plan_limit_exceeded with upgrade_url means this plan does not include another custom domain. HTTP 409 domain_exists means another account already registered it. HTTP 400 invalid_domain means the hostname is not usable. Subscribe to domain.verified on POST /api/v1/webhooks; the daily cron sends it when the records check out. List domains with cooper_list_domains. Check now with cooper_verify_domain. When usage is at 80 percent of a plan limit, the response includes notices: [{type: limit_warning, resource, used, limit, upgrade_url}].
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| domain | Yes | Hostname to attach, such as agents.example.com | |
| client_id | No | Optional idempotency key. The same key returns the original domain. |