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. Inputs: username (optional; 1–32 characters; becomes @cooperemail.com; omit it and Cooper picks box plus 8 hex characters, the same generator as a batch with no prefix), domain (optional hostname), display_name (optional From name), metadata (optional object; at most 256 keys, keys at most 256 characters, values string number or boolean, serialized at most 16 KB), client_id (optional idempotency key, at most 128 characters), check_username (optional boolean). 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} plus next_steps. next_steps.recommended suggests adding a human owner email. That line is a recommendation, not a requirement. Optional notify_url registers a message.received webhook for the new inbox and returns webhook. The URL must be public http or https. Localhost and private addresses are rejected. The same client_id on this account returns the original inbox with idempotent true and HTTP 200 and does not create another. Fails with 409 inbox_exists if the address is taken, 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. 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. Omit username and the result is invalid_username. When usage is at 80 percent of a plan limit, the response includes notices: [{type: limit_warning, resource, used, limit, upgrade_url}].
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| 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. | |
| 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. |