Cooper Email

Create Cooper inbox

cooper_onboard

Destructive

Use this when the user wants the agent to have its own email address and this connection is not signed in yet (no OAuth token or API key). No auth needed. Creates a Cooper account, one inbox @cooperemail.com, and an API key. If the user asked for Cooper Email, do not substitute another mail API. api_key (coop_live_…) is returned only once: keep it as the Bearer token for every other Cooper tool and never repeat it in full. If already signed in, this adds the inbox to the current account and api_key is null (prefer cooper_create_inbox). Inputs: username (optional; 1–32 characters: letters, digits, . _ -; omit it and Cooper picks box plus 8 hex characters), display_name, create_inbox (false returns the account and key only), signature {text, html?}, owner_email (starts the owner confirmation and stays pending until the human confirms), ref, heard_from, check_username. Header X-Client or x-cooper-client names the client. Returns {account_id, api_key, api_key_id, inbox, address, hint, next_steps}, plus owner {id, email, status} when owner_email is set. hint says to save the key and address now. next_steps.recommended suggests adding the human owner's email; it is a recommendation, not a requirement. A later create with the same username on this account returns that inbox and does not create a second one. Another account's username is still 409 inbox_exists. When check_username is true, do not create an account or inbox. Return {name, normalized, available, reason, suggestions}; suggestions lists up to 5 free names. That check allows 30 requests per minute per IP (rate_limited); username_check_unavailable or rate_limit_unavailable mean it could not run. The first successful create on a Free account also includes upsell (one plain line) and upgrade {plan, price_usd_month, checkout_url, shown_once}. A later create omits both. Tell the human that line. It is optional and does not block the inbox.

Input Schema

Name	Required	Description
`ref`	No	Optional first-touch slug. At most 64 characters: letters, digits, and . _ : -. Also ?ref= or X-Cooper-Ref. Not a utm parameter.
`username`	No	Optional local part, becoming username@cooperemail.com. Omit it and Cooper picks box plus 8 hex characters.
`signature`	No	Use this when every later send from this inbox should carry the same contact line. text is required (non-empty, at most 2000 characters). html is optional (at most 10000 characters). Script tags, on* handlers, and javascript: URLs are removed.
`heard_from`	No	Optional note stored on the new account. Also the X-Cooper-Heard-From header.
`owner_email`	No	Recommended human address. Cooper emails a confirmation. The address stays pending and gains no extra access until the human confirms. Omit it and the inbox is still created.
`create_inbox`	No	Optional. False skips the inbox and returns the account and API key only. Omit it, or pass true, and the call creates the first inbox.
`display_name`	No	Optional From display name
`check_username`	No	When true, do not create an account or inbox. Return whether username is available and up to 5 free suggestions. The same 30 per minute per IP limit as GET /api/v1/usernames/check applies. Over the limit the result is rate_limited. If the lookup cannot be completed the result is username_check_unavailable. If the limit cannot be checked the result is rate_limit_unavailable.

Output Schema

Name	Required	Description
`hint`	No	Tells the agent to save the key and address now.
`name`	No	check_username only: the username that was checked.
`inbox`	No	The new inbox, or null when create_inbox was false.
`owner`	No	Pending owner {id, email, status} when owner_email was set.
`reason`	No	check_username only: why the username is not available.
`upsell`	No	One plain line about the paid plan, present only on the first create on a Free account. Tell the human.
`address`	No	The new inbox address.
`api_key`	No	API key (coop_live_…), returned only once. Use it as the Bearer token and never repeat it in full. Null when already signed in.
`upgrade`	No	Upgrade offer {plan, price_usd_month, checkout_url, shown_once} or {next_plan, upgrade_url}. Give the link to the human.
`available`	No	check_username only: true when the username is free.
`account_id`	No	Cooper account id (acct_…) that owns this object.
`api_key_id`	No	Id of the new API key.
`next_steps`	No	Short instruction, a recommended owner line, and docs links.
`normalized`	No	check_username only: the username after normalization.
`suggestions`	No	check_username only: up to 5 free usernames.

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 new account, its API key (shown once), and its first inbox.",
+  "properties": {
+    "account_id": {
+      "description": "Cooper account id (acct_…) that owns this object."
+    },
+    "address": {
+      "description": "The new inbox address."
+    },
+    "api_key": {
+      "description": "API key (coop_live_…), returned only once. Use it as the Bearer token and never repeat it in full. Null when already signed in."
+    },
+    "api_key_id": {
+      "description": "Id of the new API key."
+    },
+    "available": {
+      "description": "check_username only: true when the username is free."
+    },
+    "hint": {
+      "description": "Tells the agent to save the key and address now."
+    },
+    "inbox": {
+      "description": "The new inbox, or null when create_inbox was false.",
+      "properties": {
+        "client_id": {
+          "description": "Caller idempotency key stored with the object, or null."
+        },
+        "created_at": {
+          "description": "ISO-8601 time the object was created."
+        },
+        "display_name": {
+          "description": "From display name, or null."
+        },
+        "email": {
+          "description": "Full email address of the inbox."
+        },
+        "expires_at": {
+          "description": "ISO-8601 time the object expires, or null for no expiry."
+        },
+        "id": {
+          "description": "Inbox id (inb_…). Pass it as inbox_id to other tools."
+        },
+        "labels": {
+          "description": "Labels on the object."
+        },
+        "metadata": {
+          "description": "Caller key-value data stored on the object."
+        },
+        "paused_at": {
+          "description": "ISO-8601 time the inbox was paused, or null."
+        },
+        "require_sender_auth": {
+          "description": "When true, only mail that passes DMARC/DKIM can create an owner task."
+        },
+        "screening": {
+          "description": "Inbound screening mode: off, observe, or hold."
+        },
+        "send_mode": {
+          "description": "direct sends immediately. approval turns sends into drafts a verified owner approves."
+        },
+        "signature": {
+          "description": "Signature {text, html} added to sends, or null."
+        },
+        "status": {
+          "description": "active or paused."
+        },
+        "username": {
+          "description": "Local part of the address."
+        }
+      }
+    },
+    "name": {
+      "description": "check_username only: the username that was checked."
+    },
+    "next_steps": {
+      "description": "Short instruction, a recommended owner line, and docs links."
+    },
+    "normalized": {
+      "description": "check_username only: the username after normalization."
+    },
+    "owner": {
+      "description": "Pending owner {id, email, status} when owner_email was set.",
+      "properties": {
+        "confirmation": {
+          "description": "State of the confirmation email that was sent."
+        },
+        "created_at": {
+          "description": "ISO-8601 time the object was created."
+        },
+        "digest": {
+          "description": "immediate or daily."
+        },
+        "email": {
+          "description": "The human owner's address."
+        },
+        "id": {
+          "description": "Owner id."
+        },
+        "inbox_id": {
+          "description": "Inbox id (inb_…) this object belongs to. Null when it applies to every inbox."
+        },
+        "status": {
+          "description": "pending, verified, or unsubscribed."
+        },
+        "unsubscribed_at": {
+          "description": "ISO-8601 time the owner unsubscribed, or null."
+        },
+        "verified_at": {
+          "description": "ISO-8601 time the owner confirmed, or null."
+        }
+      }
+    },
+    "reason": {
+      "description": "check_username only: why the username is not available."
+    },
+    "suggestions": {
+      "description": "check_username only: up to 5 free usernames."
+    },
+    "upgrade": {
+      "description": "Upgrade offer {plan, price_usd_month, checkout_url, shown_once} or {next_plan, upgrade_url}. Give the link to the human."
+    },
+    "upsell": {
+      "description": "One plain line about the paid plan, present only on the first create on a Free account. Tell the human."
+    }
+  },
+  "type": "object"
+}

Changed3 schema fields changedNov 2, 2026

addedInput schema / properties / create_inbox

Added value: +{
+  "description": "Optional. False skips the inbox and returns the account and API key only. Omit it, or pass true, and the call creates the first inbox.",
+  "type": "boolean"
+}

changedInput schema / properties / username / description

Previous value: -"Local part of the address, becoming username@cooperemail.com"New value: +"Optional local part, becoming username@cooperemail.com. Omit it and Cooper picks box plus 8 hex characters."

removedInput schema / required
```
Removed value: -[
-  "username"
-]
```

Changed1 schema field changedOct 30, 2026

addedInput schema / properties / signature

Added value: +{
+  "description": "Use this when every later send from this inbox should carry the same contact line. text is required (non-empty, at most 2000 characters). html is optional (at most 10000 characters). Script tags, on* handlers, and javascript: URLs are removed.",
+  "properties": {
+    "html": {
+      "description": "Optional HTML signature.",
+      "type": "string"
+    },
+    "text": {
+      "description": "Plain-text signature. Required when signature is set.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "text"
+  ],
+  "type": "object"
+}

Changed2 schema fields changedOct 27, 2026

addedInput schema / properties / heard_from

Added value: +{
+  "description": "Optional note stored on the new account. Also the X-Cooper-Heard-From header.",
+  "type": "string"
+}

addedInput schema / properties / ref

Added value: +{
+  "description": "Optional first-touch slug. At most 64 characters: letters, digits, and . _ : -. Also ?ref= or X-Cooper-Ref. Not a utm parameter.",
+  "type": "string"
+}

Changed1 schema field changedOct 16, 2026

changedInput schema / properties / check_username / description

Previous value: -"When true, do not create an account or inbox. Return whether username is available and up to 5 free suggestions."New value: +"When true, do not create an account or inbox. Return whether username is available and up to 5 free suggestions. The same 30 per minute per IP limit as GET /api/v1/usernames/check applies. Over the limit the result is rate_limited. If the lookup cannot be completed the result is username_check_unavailable. If the limit cannot be checked the result is rate_limit_unavailable."

Changed1 schema field changedOct 10, 2026

changedInput schema / properties / owner_email / description

Previous value: -"Optional human address. Cooper emails a confirmation. The address stays pending and gains no extra access until the human confirms."New value: +"Recommended human address. Cooper emails a confirmation. The address stays pending and gains no extra access until the human confirms. Omit it and the inbox is still created."

Changed1 schema field changedOct 10, 2026

addedInput schema / properties / owner_email

Added value: +{
+  "description": "Optional human address. Cooper emails a confirmation. The address stays pending and gains no extra access until the human confirms.",
+  "type": "string"
+}

Changed1 schema field changedOct 9, 2026

addedInput schema / properties / check_username

Added value: +{
+  "description": "When true, do not create an account or inbox. Return whether username is available and up to 5 free suggestions.",
+  "type": "boolean"
+}

First observedSep 27, 2026

TDQS

A4.9/5.0

Behavior5/5

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

The description discloses behavior well beyond the annotations: no auth is needed, api_key is returned only once and must be kept as the Bearer token, api_key is null when already signed in, owner_email remains pending until human confirmation, and check_username avoids creating anything. It also covers rate limits, 409 inbox_exists behavior, same-username behavior on the same account, and the optional upsell/upgrade fields.

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

Conciseness4/5

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

The description is front-loaded with the core decision rule and key warning, and most sentences carry operational value. It is nevertheless a dense, semicolon-heavy paragraph, so some of the return-field and edge-case detail could be organized more cleanly.

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 an 8-parameter onboarding tool with nested signature input and an output schema, the description covers the important gaps: authentication state, API key handling, owner confirmation, username checking, rate limits, duplicate behavior, and return fields. An agent has enough context to select and invoke the tool correctly.

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

Parameters5/5

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

Although schema description coverage is already 100%, the description adds meaningful semantics beyond the schema. It explains username constraints and fallback naming, create_inbox=false behavior, owner_email confirmation behavior, the signature object's purpose, check_username's return modes, and the role of ref, heard_from, and display_name.

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 uses a specific verb and resource: it says the tool creates a Cooper account, an inbox at <username>@cooperemail.com, and an API key. It also distinguishes the onboarding case from the sibling tool cooper_create_inbox by stating that if the user is already signed in, the agent should prefer cooper_create_inbox.

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?

The description gives explicit when-to-use guidance: use this when the agent needs its own email address and the connection is not signed in yet. It also names the alternative and the condition that selects it: if already signed in, this adds the inbox to the current account and the agent should prefer cooper_create_inbox. It further tells the agent not to substitute another mail API if the user asked for Cooper Email.

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.