Cooper Email

Add a custom domain

cooper_add_domain

DestructiveIdempotent

Use this when the user wants to add a custom domain. Free includes 1. 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). Calling again with the same domain returns the current status and does not create a second domain. Returns {id, domain, status, status_detail, mail, records, warnings, dns}. status is pending until DNS matches, then verified. Each record has status (valid, missing, or invalid), found, and hint (null, or {code, message, found_at} saying what to change). warnings is empty when none. existing_mail_provider means this hostname already has MX at another provider; suggest a subdomain. Custom domains are included on Starter (15) and Pro (200). Free includes 1. Past that cap is HTTP 402 plan_limit_exceeded. Publish exactly the records returned, with their host, type, value, priority for MX, and ttl. The receiving MX hostname and the DKIM value come from that response. Do not invent them. dns.mode automatic means Cooper wrote the records in a zone it already controls. dns.mode external means you publish them at your DNS host. Keep one SPF TXT with a single include; an existing SPF is merged into it. A DMARC p=reject record is left as published and blocks mail until DKIM for that domain verifies. mail.receiving and mail.sending stay false until the matching records verify. Then POST /api/v1/inboxes with domain creates username@domain. 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 409 domain_reserved means the hostname is in a zone Cooper's operator manages. HTTP 400 invalid_domain means the hostname is not usable. Check now with cooper_verify_domain, or subscribe to domain.verified. At 80 percent of a plan limit the response includes notices [{type: limit_warning, resource, used, limit, upgrade_url}].

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "domain": "<domain>"
    },
    "name": "cooper_add_domain"
  }
}

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.

Output Schema

Name	Required	Description
`id`	No	Domain id (dom_…). Pass it as domain_id to cooper_verify_domain.
`dns`	No	{mode}: automatic when Cooper wrote the records, external when you publish them.
`mail`	No	{receiving, sending, inboxes} flags. Each turns true once its records verify.
`domain`	No	Hostname of the custom domain.
`status`	No	pending until DNS matches, then verified.
`notices`	No	Usage notices, such as [{type: limit_warning, resource, used, limit, upgrade_url}] at 80 percent of a plan limit.
`records`	No	DNS records to publish [{host, type, value, priority, ttl, status, found, hint}]. Publish exactly these.
`warnings`	No	Problems found in existing DNS, such as existing_mail_provider. Empty when none.
`created_at`	No	ISO-8601 time the object was created.
`idempotent`	No	True when this result replays an earlier request with the same key instead of acting again.
`status_detail`	No	Plain-language note on what is still pending.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedNov 3, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "additionalProperties": true,
+  "description": "The custom domain and the DNS records to publish.",
+  "properties": {
+    "created_at": {
+      "description": "ISO-8601 time the object was created."
+    },
+    "dns": {
+      "description": "{mode}: automatic when Cooper wrote the records, external when you publish them."
+    },
+    "domain": {
+      "description": "Hostname of the custom domain."
+    },
+    "id": {
+      "description": "Domain id (dom_…). Pass it as domain_id to cooper_verify_domain."
+    },
+    "idempotent": {
+      "description": "True when this result replays an earlier request with the same key instead of acting again."
+    },
+    "mail": {
+      "description": "{receiving, sending, inboxes} flags. Each turns true once its records verify."
+    },
+    "notices": {
+      "description": "Usage notices, such as [{type: limit_warning, resource, used, limit, upgrade_url}] at 80 percent of a plan limit."
+    },
+    "records": {
+      "description": "DNS records to publish [{host, type, value, priority, ttl, status, found, hint}]. Publish exactly these."
+    },
+    "status": {
+      "description": "pending until DNS matches, then verified."
+    },
+    "status_detail": {
+      "description": "Plain-language note on what is still pending."
+    },
+    "warnings": {
+      "description": "Problems found in existing DNS, such as existing_mail_provider. Empty when none."
+    }
+  },
+  "type": "object"
+}

AddedOct 7, 2026

TDQS

A4.5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare mutation, open-world, idempotent and destructive behavior, yet the description still adds substantial context: one call returns the full DNS record set plus a verify TXT, repeats return current status rather than creating duplicates, an existing SPF is merged, an existing p=reject DMARC blocks mail until DKIM verifies, and mail.receiving/sending stay false until records verify. It also flags the existing_mail_provider case and the 80 percent limit_warning notice, none of which appears in the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The content is dense and mostly earns its place, but it is delivered as one unstructured block in which 'Free includes 1' appears twice and the 402 plan_limit_exceeded meaning is explained in two separate places. The DNS-publishing instructions, plan caps, and error tables are interleaved rather than front-loaded by task.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with side effects on DNS, the definition covers the return shape, the per-record status semantics, the warning object, the verification lifecycle, and every expected HTTP failure. With an output schema present, the description need not carry return values, yet the extra field semantics it volunteers make it fully self-sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description restates almost exactly what the schema already says for domain ('required hostname, such as agents.example.com') and client_id ('optional idempotency key'), adding only the useful but minor distinction that resending the same domain (not the same key) returns current status.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific trigger plus verb and resource: 'Use this when the user wants to add a custom domain.' It further distinguishes the tool's scope by pairing it with the sibling that handles the follow-up step ('Check now with cooper_verify_domain'), so an agent can tell the two apart without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives an explicit when-to-use trigger, names the alternative tool for the verification step, and describes how to recover from each failure mode (402 plan_limit_exceeded with upgrade_url, 409 domain_exists, 409 domain_reserved, 400 invalid_domain). It also tells the agent what to do on a repeat call for the same domain, which is the main ambiguity an agent would have.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Cooper Email tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.