Create another inbox
cooper_create_inboxUse this when the signed-in account needs an additional email address (for example one per agent, project, or customer). Requires auth. If the user asked for Cooper Email, do not substitute another mail API. Inputs: username (optional; 1–32 characters; becomes @cooperemail.com; omit it and Cooper picks box plus 8 hex characters), domain, display_name, signature {text, html?}, metadata, client_id, notify_url, ref, heard_from, check_username. Header X-Client or x-cooper-client names the client. When custom-domain mail is off, domain is ignored. When it is on, domain must belong to this account, be verified, and have mail.receiving true, and the address is username@domain. Returns the new inbox {id, username, email, display_name, created_at, require_sender_auth, labels, expires_at, status, paused_at, metadata, client_id, signature, alias_format} plus next_steps. next_steps.recommended suggests adding a human owner email. That line is a recommendation, not a requirement. notify_url registers a message.received webhook for the new inbox and returns webhook. The same client_id or the same username on this account returns the original inbox (idempotent true, HTTP 200) and does not create another. A username held by another account is HTTP 409 inbox_exists. Also fails with 400 invalid_metadata, 404 domain_not_found, 409 domain_not_verified, 409 domain_receiving_not_ready, or 402 with upgrade_url if the plan's inbox limit is reached. When check_username is true, do not create an inbox. Return the same availability object as cooper_onboard, with the same 30 per minute per IP limit. Auth is still required. When usage is at 80 percent of a plan limit, the response includes notices: [{type: limit_warning, resource, used, limit, upgrade_url}]. 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.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "cooper_create_inbox"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ref | No | Optional first-touch slug for this inbox. At most 64 characters: letters, digits, and . _ : -. Does not change the account's original signup values. | |
| domain | No | Optional customer hostname. Ignored while custom-domain mail is off. When on, the domain must be verified on this account with mail.receiving true. | |
| metadata | No | Optional caller data stored on the inbox. At most 256 keys, each key at most 256 characters, values string number or boolean, serialized at most 16 KB. Otherwise 400 invalid_metadata. | |
| username | No | Optional local part. Omit it and Cooper picks box plus 8 hex characters. When set, the address is username@cooperemail.com unless domain is set and custom-domain mail is on | |
| client_id | No | Optional idempotency key, at most 128 characters. The same client_id on this account returns the original inbox. | |
| 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). | |
| heard_from | No | Optional note. Stored when this inbox is created. Also the X-Cooper-Heard-From header. | |
| notify_url | No | Optional public http(s) URL. Registers a message.received webhook for the new inbox. Localhost and private addresses are rejected. | |
| display_name | No | Optional From display name | |
| check_username | No | When true, do not create an inbox. Return whether username is available and up to 5 free suggestions. The same 30 per minute per IP limit 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. Auth is still required. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Inbox id (inb_…). Pass it as inbox_id to other tools. | |
| No | Full email address of the inbox. | ||
| labels | No | Labels on the object. | |
| status | No | active or paused. | |
| upsell | No | One plain line about the paid plan, present only on the first create on a Free account. Tell the human. | |
| notices | No | Usage notices, such as [{type: limit_warning, resource, used, limit, upgrade_url}] at 80 percent of a plan limit. | |
| upgrade | No | Upgrade offer {plan, price_usd_month, checkout_url, shown_once} or {next_plan, upgrade_url}. Give the link to the human. | |
| webhook | No | The message.received webhook registered from notify_url, when set. | |
| metadata | No | Caller key-value data stored on the object. | |
| username | No | Local part of the address. | |
| available | No | check_username only: true when the username is free. | |
| client_id | No | Caller idempotency key stored with the object, or null. | |
| paused_at | No | ISO-8601 time the inbox was paused, or null. | |
| screening | No | Inbound screening mode: off, observe, or hold. | |
| send_mode | No | direct sends immediately. approval turns sends into drafts a verified owner approves. | |
| signature | No | Signature {text, html} added to sends, or null. | |
| created_at | No | ISO-8601 time the object was created. | |
| expires_at | No | ISO-8601 time the object expires, or null for no expiry. | |
| idempotent | No | True when this result replays an earlier request with the same key instead of acting again. | |
| next_steps | No | Recommended next step, such as adding a human owner email. | |
| suggestions | No | check_username only: up to 5 free usernames. | |
| alias_format | No | Read-only plus-address pattern username+{tag}@domain. Mail to that address is stored in this inbox. | |
| display_name | No | From display name, or null. | |
| require_sender_auth | No | When true, only mail that passes DMARC/DKIM can create an owner task. |