Skip to main content
Glama
Sign In

Cooper Email

by com.cooperemail
OverviewDiscussionsAdmin

Update an inbox

cooper_update_inbox
DestructiveIdempotent

Use this when an inbox should pause (stop sending and accepting new mail without deleting the address, threads, or history) or resume, or when you need to change its display name, metadata, signature, inbound screening, sender authentication, or send_mode. Requires auth. Inputs: inbox_id (required; inbox id, username, or email) and at least one of status (active or paused), require_sender_auth, display_name (null clears it), metadata (merged; a null value removes that key), screening (off, observe, or hold), send_mode (direct or approval), signature ({text, html?}, or null to remove it). Bad values return HTTP 400 invalid_metadata, invalid_screening, or invalid_send_mode. send_mode approval applies immediately when a verified owner exists: sends, replies, and forwards become pending drafts and those owners are emailed. No verified owner returns HTTP 409 owner_required and leaves send_mode unchanged. Back to direct is immediate only when the inbox never had a verified owner. Otherwise the owners are emailed and the change waits until they confirm. Opening the confirm link does not change the inbox, and an API key cannot submit it. Screening never drops mail. observe, the default, adds the suspicious label at a heuristic score of 40 or higher. hold stores suspicious mail with the held label, fires message.held instead of message.received, and creates no task. off skips scoring (reason screening_off). Pausing sets paused_at; resuming clears it. A paused inbox still counts toward the plan inbox limit, existing messages stay readable, and sends return HTTP 403 inbox_paused until status is active. Returns the inbox {id, username, email, display_name, created_at, require_sender_auth, labels, expires_at, status, paused_at, metadata, client_id, screening, send_mode, signature}.

Input Schema

NameRequiredDescriptionDefault
statusNopaused stops new sends and drops new inbound mail. active resumes the inbox.
inbox_idYesInbox id (inb_…), username, or full email address owned by this key
metadataNoMerged into the current metadata. A null value removes that key. At most 256 keys, keys at most 256 characters, values string number or boolean, serialized at most 16 KB. Otherwise 400 invalid_metadata.
screeningNoInbound prompt-injection screen. off skips scoring and records why. observe labels suspicious mail. hold stores suspicious mail for review and fires message.held. Anything else is 400 invalid_screening.
send_modeNoEntering approval applies immediately when a verified owner exists and holds POST /messages, reply, reply-all, and forward until that owner approves the current content. No verified owner returns HTTP 409 owner_required. An inbox already in approval can return to direct only when it has never had a verified owner. An unsubscribed owner still blocks that switch. Leaving approval for direct emails verified owners and waits for confirmation. Anything else is 400 invalid_send_mode.
signatureNoUse this when the inbox signature should change. Pass {text, html?} to set or replace it. text is required, non-empty, and at most 2000 characters. html is optional and at most 10000 characters. Pass null to remove it. Omit it to leave the stored signature unchanged.
display_nameNoFrom display name. Send null to clear it. A blank string also clears it.
require_sender_authNoWhen true, owner or allowlist mail becomes a task only if DMARC passes or DKIM passes and aligns with From.

Output Schema

NameRequiredDescriptionDefault
idNoInbox id (inb_…). Pass it as inbox_id to other tools.
emailNoFull email address of the inbox.
labelsNoLabels on the object.
statusNoactive or paused.
metadataNoCaller key-value data stored on the object.
usernameNoLocal part of the address.
client_idNoCaller idempotency key stored with the object, or null.
paused_atNoISO-8601 time the inbox was paused, or null.
screeningNoInbound screening mode: off, observe, or hold.
send_modeNodirect sends immediately. approval turns sends into drafts a verified owner approves.
signatureNoSignature {text, html} added to sends, or null.
created_atNoISO-8601 time the object was created.
expires_atNoISO-8601 time the object expires, or null for no expiry.
display_nameNoFrom display name, or null.
require_sender_authNoWhen true, only mail that passes DMARC/DKIM can create an owner task.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "additionalProperties": true,
+  "description": "The inbox after the update.",
+  "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."
+    }
+  },
+  "type": "object"
+}
  2. Changed1 schema field changed
    • addedInput schema / properties / signature
      Added value: +{
+  "description": "Use this when the inbox signature should change. Pass {text, html?} to set or replace it. text is required, non-empty, and at most 2000 characters. html is optional and at most 10000 characters. Pass null to remove it. Omit it to leave the stored signature unchanged."
+}
  3. Changed1 schema field changed
    • changedInput schema / properties / send_mode / description
      Previous value: -"Entering approval applies immediately and holds POST /messages, reply, reply-all, and forward until a verified owner approves the current content. Leaving approval for direct emails verified owners and waits for confirmation. Anything else is 400 invalid_send_mode."New value: +"Entering approval applies immediately when a verified owner exists and holds POST /messages, reply, reply-all, and forward until that owner approves the current content. No verified owner returns HTTP 409 owner_required. An inbox already in approval can return to direct only when it has never had a verified owner. An unsubscribed owner still blocks that switch. Leaving approval for direct emails verified owners and waits for confirmation. Anything else is 400 invalid_send_mode."
  4. Changed1 schema field changed
    • addedInput schema / properties / send_mode
      Added value: +{
+  "description": "Entering approval applies immediately and holds POST /messages, reply, reply-all, and forward until a verified owner approves the current content. Leaving approval for direct emails verified owners and waits for confirmation. Anything else is 400 invalid_send_mode.",
+  "enum": [
+    "direct",
+    "approval"
+  ],
+  "type": "string"
+}
  5. Changed1 schema field changed
    • addedInput schema / properties / screening
      Added value: +{
+  "description": "Inbound prompt-injection screen. off skips scoring and records why. observe labels suspicious mail. hold stores suspicious mail for review and fires message.held. Anything else is 400 invalid_screening.",
+  "enum": [
+    "off",
+    "observe",
+    "hold"
+  ],
+  "type": "string"
+}
  6. Changed2 schema fields changed
    • addedInput schema / properties / display_name
      Added value: +{
+  "description": "From display name. Send null to clear it. A blank string also clears it.",
+  "type": "string"
+}
    • addedInput schema / properties / metadata
      Added value: +{
+  "description": "Merged into the current metadata. A null value removes that key. At most 256 keys, keys at most 256 characters, values string number or boolean, serialized at most 16 KB. Otherwise 400 invalid_metadata.",
+  "type": "object"
+}
  7. Added

TDQS

A4.3/5.0
Behavior5/5

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

Goes far beyond the annotations, which only say readOnly=false, destructive=true, idempotent=true, openWorld=true. The description discloses the async approval handshake for send_mode (owners are emailed, change waits for confirmation, confirm link alone cannot apply it, API keys cannot submit it), the 409 owner_required path, the 403 inbox_paused behavior on sends, the fact that pausing preserves threads/history and still consumes a plan inbox slot, and that screening never drops mail. That is exactly the destroyed/changed/blocked information an agent needs and cannot get from the hints.

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?

Front-loaded correctly with the when-to-use clause, but it then becomes a single dense block that re-explains screening modes, send_mode transitions, and pause side effects already spelled out in the schema. Much of it earns its place, yet the run-on packaging and repetition of schema content make it harder to scan than it needs to be.

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 eight-parameter, multi-mode mutation tool with nested objects and irreversible-ish transitions, the description covers preconditions, failure codes, asynchronous confirmation flows, and edge cases. The trailing return-shape listing is redundant given the output schema but harmless, and no behavior an agent needs before calling is absent.

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 all eight parameters are already documented with enums and nested shapes, which sets the baseline at 3. The description mostly restates those semantics (null clears display_name and signature, metadata merges with null-key removal, screening modes) rather than adding new meaning; the marginal additions are the HTTP error codes (invalid_metadata, invalid_screening, invalid_send_mode, owner_required).

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?

Opens with a specific verb-plus-resource statement ('Update an inbox') and immediately enumerates every mutable facet (pause/resume, display name, metadata, signature, screening, sender auth, send_mode). That enumeration makes it trivially distinguishable from cooper_get_inbox, cooper_create_inbox, and cooper_delete_inbox.

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

Usage Guidelines4/5

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

Explicitly frames the when: 'Use this when an inbox should pause... or resume, or when you need to change its display name, metadata, signature, inbound screening, sender authentication, or send_mode.' It also states 'Requires auth' and 'at least one of...' as a precondition. It does not name a sibling alternative or an explicit when-not (e.g., delete via cooper_delete_inbox), so it stops short of full routing guidance.

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

All Cooper Email toolsInspect
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.

Resources