reserved_address
HTTP 422 retryable: false REST and MCP
The local part you asked for is on the platform's reserved list, or that exact address is already bound, so it cannot be allocated to this inbox.
Why it happens
Two separate rules produce this. The first is a policy list of reserved local parts on the shared platform domain, checked before any provisioning starts and bypassed only for explicitly allowlisted internal workspaces. These are names that carry institutional meaning in email, and letting a tenant claim one on a domain other tenants also use would let them receive mail intended for the platform. The second is a uniqueness constraint: the exact address, or the provider inbox behind it, is already bound to something else. In the second case no new provider inbox is requested, so nothing is left dangling.
Every condition below was read in the implementation at the file and line given. They are the branches that raise this code, not a summary of what the name suggests.
- The requested local part is on the reserved platform list and the workspace is not on the reserved-workspace allowlist.
packages/domain/src/platform-address-policy.ts:43 - A unique violation (SQLSTATE 23505) on the address reservation. No new provider inbox was requested.
packages/domain/src/platform-inboxes.ts:126 - An existing binding names a different provider inbox id or a different canonical address for this receive address.
packages/domain/src/services.ts:2359 - Provider creation could not be confirmed and the provider reported the address as unavailable. The address stays reserved and the inbox stays paused.
packages/domain/src/platform-inboxes.ts:181
How to fix it
- Choose a different local part. Names that read as platform or administrative roles are the ones on the list.
- Use your own domain if you need a specific institutional name. The reservation applies to the shared platform domain, where the name would otherwise collide across tenants.
- If the message says the address is reserved and paused because provider creation could not be confirmed, contact support with the request id rather than retrying. Retrying cannot resolve an ambiguous outcome and may compound it.
- Do not retry the same name on a loop. This is not retryable.
Why it works this way
Holding the reservation when a provider call fails ambiguously is deliberate. Releasing it would let a second tenant claim an address the provider may already have created, which is the one outcome that cannot be undone from this side.
Messages you will see
The message field is written for a human reading a log and is not a contract
value. Branch on code instead. These are the exact strings this code is sent
with today, listed so that a search for one of them lands here.
This address name is reserved on the platform domain. Choose another name or use your own domain.That exact address is already reserved. No new provider inbox was requested.That receive address or Resend inbox is already bound.The exact address is reserved and paused because provider creation could not be confirmed. Contact support with this request ID before retrying.
Where it appears
These are the documented surfaces that raise it. The REST base is https://api.emailforagents.ai/v1, and the remote MCP endpoint is https://mcp.emailforagents.ai/mcp.
POST /projects/{project_id}/inboxes
The response
Read request_id off the body or the x-request-id header before
doing anything else. It is the only handle on one specific attempt, and for a 503 it is
the only handle at all, because the underlying detail stays server-side.
HTTP/1.1 422
content-type: application/json
x-request-id: req_...
{
"error": {
"code": "reserved_address",
"message": "This address name is reserved on the platform domain. Choose another name or use your own domain.",
"request_id": "req_...",
"retryable": false
}
}
Verified against packages/domain/src/platform-address-policy.ts:43. The status comes from ERROR_STATUS in packages/contracts/src/errors.ts, which is the one
place a code is mapped to a status.