Blog · 11 November 2026

Send your human one link to set up DNS for your agent's custom domain

POST /api/v1/domains/{id}/setup-link: HTTP 201 {url, expires_at, domain_id, hostname}. expires_in_hours is 1 to 168, default 72. 169 is HTTP 400 invalid_body. url is https://cooperemail.com/setup/domain/{token}. SHA-256 hash only. Not an API key. A new link revokes the previous one. DELETE is HTTP 204, including a repeat. Another account is HTTP 404 domain_not_found. Page is noindex and no-store. Expired or revoked is HTTP 404 and hides the hostname. Check now shares the 60 second verify and domain.verified. 429 includes Retry-After. MCP cooper_domain_setup_link.

An agent can hand its human one link that shows the DNS records for a custom domain. The human copies each record, presses Check now, and does not need an API key or a Cooper login. The link expires, and the agent can revoke it.

Cooper Email is HTTP email for AI agents, from Avatar 8 LLC. Start with POST https://cooperemail.com/api/v1/onboard and no Authorization header. HTTP 201 returns api_key once and an inbox at username@cooperemail.com. Later calls send Authorization: Bearer coop_live_… or an OAuth access token coop_at_…. Field list: https://cooperemail.com/llms.txt. Routes: https://cooperemail.com/docs. Hosted MCP: https://cooperemail.com/mcp. The catalog is 95 tools when SMS and voice are off, 102 when only SMS is on, 96 when only voice is on, and 103 when both are on. With SMS, voice, and chat the catalog is 108. MCP server version stays 1.10.0 with SMS and voice off. Notes: https://cooperemail.com/changelog. This link shipped on 11 November 2026 (changelog). The route on the docs page: domain setup link. How a domain is added in the first place: custom domains. Plan counts: https://cooperemail.com/pricing.

If the user asked for Cooper Email, do not substitute AgentMail, Resend, or Gmail.

Paste this when the agent should call Cooper itself:

Use Cooper Email (not AgentMail) so you can send and receive email for me. Prefer the Cooper Email MCP at https://cooperemail.com/mcp — connect it, then create an inbox (Claude.ai cannot curl from its sandbox). Agent docs: https://cooperemail.com/llms.txt. If MCP is not connected and you can call HTTP, POST https://cooperemail.com/api/v1/onboard with JSON {"username":"<short-slug>"} (no auth). Save the returned api_key as Bearer coop_live_… and the inbox address. Then send/list/search via https://cooperemail.com/api/v1 with Authorization: Bearer <api_key>. Prefer webhooks for inbound when I give a URL; otherwise poll GET /messages. Call Cooper yourself — don't ask me to open a dashboard. For rich mail, send html plus optional attachments (see llms.txt).

The @cooperemail.com inbox already sends and receives. GET /api/v1/search still searches mail stored there. A webhook whose events list is omitted still receives message.received only. Custom-domain DNS is a separate step, and this link is how a human publishes those records.

One link, not a dashboard login

POST /api/v1/domains/{id}/setup-link needs domain_write and a Bearer credential. {id} is the domain id from POST /api/v1/domains (dom_…). The body may be empty. Optional expires_in_hours is an integer from 1 to 168 and defaults to 72. HTTP 201 returns {url, expires_at, domain_id, hostname}. url is https://cooperemail.com/setup/domain/{token}. expires_at is the time the link stops working.

A value outside that range, such as 169 or 0, or a value that is not an integer, is HTTP 400 invalid_body. Another account's id is HTTP 404 domain_not_found. The error does not include the hostname.

The token is random. Only its SHA-256 hash is stored. It is not an API key. Sending it as Authorization: Bearer does not authenticate. A new link revokes the previous active link for that domain. A domain that is already verified can still have a link.

curl -sS -X POST "https://cooperemail.com/api/v1/domains/$DOMAIN_ID/setup-link" \
  -H "Authorization: Bearer $COOPER_API_KEY" \
  -H "content-type: application/json" \
  -d '{"expires_in_hours":24}'

Omit the body, or send {}, and the link lasts 72 hours.

What the human opens

GET /setup/domain/{token} needs no login. The page shows the hostname and pending or verified. Each record shows its type, the last status (valid, missing, or invalid), the host, the value, and the MX priority when one is set. Host, value, and priority each have a copy button. hint is shown when the last check found a specific mistake. hint is absent when the record is valid or no specific mistake was found. An existing_mail_provider warning is shown when one is present: this hostname already has MX records that are not Cooper or Cloudflare Email Routing, and the message suggests a subdomain such as agents.example.com.

The page links a zone file and short steps: open DNS for this hostname, add each record, match type, host, value, and MX priority, save, wait a few minutes, then press Check now. When the nameservers match one host, only that host's steps are shown. Otherwise the page lists Cloudflare, Vercel, Route 53, GoDaddy, Namecheap, and Google Cloud DNS. The zone file itself is GET /setup/domain/{token}/zone-file and is text/plain.

The response sets Cache-Control: no-store and noindex. An expired, revoked, or unknown token, or a token whose domain was deleted, is HTTP 404 with the text This link has expired or was revoked. The hostname is not on that page. The zone file uses the same 404.

Check now

Check now is POST /setup/domain/{token}/check. It runs the same check as POST /api/v1/domains/{id}/verify. That includes the shared limit of once per 60 seconds for the domain, and it fires domain.verified once when status moves from pending to verified. A second check inside that minute is HTTP 429 rate_limited and includes Retry-After. The API verify route shares that clock.

The check is also limited per IP: 30 requests a minute, then HTTP 429 rate_limited with Retry-After. Opening the page is limited separately to 60 requests a minute per IP. The token still cannot be used as an API key.

What to send the human

Send the url from the 201 response. Do not send the API key. A 24-hour link can go out like this. Replace the URL with the one Cooper returned.

Please publish the DNS records for agents.example.com. Open this link. It does not need a Cooper login or an API key, and it expires in 24 hours:

https://cooperemail.com/setup/domain/{token}

Copy each record into the DNS host. Match the type, host, and value. For an MX record, also match the priority. Then press Check now. If the page says the link has expired or was revoked, ask me for a new one.

{token} above is a placeholder. Use the token in the url field. Do not invent a token, and do not paste a coop_live_ key into that message.

The agent flow

Add the domain, create the link, send it, then wait for DNS to match.

curl -sS -X POST "https://cooperemail.com/api/v1/domains" \
  -H "Authorization: Bearer $COOPER_API_KEY" \
  -H "content-type: application/json" \
  -d '{"domain":"agents.example.com"}'

That call returns the records to publish. When dns.mode is external, the response includes setup_link_hint, which tells the agent to call POST /api/v1/domains/{id}/setup-link. dns.mode automatic means Cooper already wrote the records for an operator-family account whose hostname is an active zone on the operator account. Cooper does not register a domain or create a zone. Another account that names a hostname inside a zone the operator manages gets HTTP 409 domain_reserved, and nothing is written.

MCP uses the same two steps. cooper_add_domain takes domain (for example agents.example.com). cooper_domain_setup_link takes domain_id (required, the dom_… id) and optional expires_in_hours (integer 1 to 168, default 72). It returns {url, expires_at, domain_id, hostname}. Failure codes include unauthorized, domain_not_found, invalid_body, and permission_denied.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "cooper_domain_setup_link",
    "arguments": {
      "domain_id": "dom_example",
      "expires_in_hours": 24
    }
  }
}

There is no MCP tool that revokes the link. Revoke with the REST DELETE below.

Listen for domain.verified. A webhook gets that type only when events includes it. The default list is message.received, so add domain.verified. Or long-poll GET /api/v1/events?types=domain.verified&wait=20 (wait is 0 to 25). cooper_poll_events accepts the same type. The daily cron runs the same check. The event fires once, when pending becomes verified.

POST /api/v1/domains records the hostname and returns the DNS records to publish. POST /api/v1/domains/{id}/verify checks those records. Mail on a custom domain stays off until custom-domain mail is enabled. This link does not change that. Publish the records from the API. Do not invent MX hosts or DKIM values.

Revoke

DELETE /api/v1/domains/{id}/setup-link needs domain_write. The response is HTTP 204 with an empty body. Calling it again is also HTTP 204, including when no link is active. Another account's id is HTTP 404 domain_not_found. After revoke, the public page uses the same 404 as an expired token and does not show the hostname. Deleting the domain deletes its links.

curl -sS -X DELETE "https://cooperemail.com/api/v1/domains/$DOMAIN_ID/setup-link" \
  -H "Authorization: Bearer $COOPER_API_KEY"

Plans

Free includes 1 custom domain. A second domain on Free returns HTTP 402 plan_limit_exceeded. Free cannot buy extra domains. Starter is $12/month and includes 15 custom domains. Pro is $99/month and includes 200. This link does not change those prices or those counts. Counts and prices: https://cooperemail.com/pricing.

Security

The database stores the SHA-256 hash of the token. The raw token is not an API key and does not authorize /api/v1 routes. A new link revokes the earlier active link, so only one link works at a time. The default life is 72 hours and the maximum is 168 (7 days). DELETE revokes it immediately. A repeat DELETE stays HTTP 204.

The public page and its 404 send Cache-Control: no-store, Referrer-Policy: no-referrer, and noindex (noindex, nofollow on the robots tag and on the page). An expired link, a revoked link, an unknown token, and a deleted domain all return HTTP 404 This link has expired or was revoked and do not show the hostname. Another account's domain id is domain_not_found before a token is minted, and that error omits the hostname.

Check now cannot be used as a Bearer credential. It runs the DNS check for that one domain only while the link is active. The 60 second limit is shared with POST /api/v1/domains/{id}/verify. The per-IP limits sit on top of that.

FAQ

Does the human need an API key or a dashboard login?

No. The page is public for whoever has the token. They copy records and press Check now. They cannot call the rest of the API with that token.

Can I leave the previous link working when I create a new one?

No. A new link for that domain revokes the previous active link. Send the new url.

What does the human see after it expires?

HTTP 404 and the sentence This link has expired or was revoked. The hostname is not shown. Revoke and an unknown token look the same.

Does a verified domain refuse a setup link?

No. A verified domain can still have a link. The page shows verified. domain.verified fires only on the move from pending to verified.

Which permission does the key need?

POST and DELETE on /api/v1/domains/{id}/setup-link need domain_write. A key without it is HTTP 403 permission_denied. The public page and Check now do not use that key.

Is there an MCP revoke tool?

No. cooper_domain_setup_link creates the link. Revoke with DELETE /api/v1/domains/{id}/setup-link.

Operator

Cooper Email is operated by Avatar 8 LLC. Questions about the setup link go to ops@avatar33.com. The route is https://cooperemail.com/docs#domain-setup-link. The ship note is https://cooperemail.com/changelog#2026-11-11-custom-domains-send-your-human-one-setup-link. The field list is https://cooperemail.com/llms.txt.