> ## Documentation Index
> Fetch the complete documentation index at: https://docs.noisemaker.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspace email

> Provision and recover AgentMail inboxes used for third-party property access.

Each workspace can receive an AgentMail address under the operator's AgentMail organization. The operator supplies one organization-level <code>AGENTMAIL\_API\_KEY</code>; workspaces never receive that secret. Teams use the generated address when granting GA4 and Search Console access.

## Provisioning

For each workspace, the application derives:

```text theme={null}
username: gp-<normalized-workspace-slug>
client ID: geo-workspace-<workspace-slug>-inbox-v1
```

The username is limited to 64 characters. The client ID is stored in AgentMail metadata so a retry can identify ownership.

The creation service waits for the provisioning attempt, which has an eight-second request timeout. Workspace creation does not fail when AgentMail is unconfigured or unavailable. It records the state and returns the workspace.

## Idempotency and conflicts

If AgentMail returns a conflict, the application checks the existing inbox:

* The same client ID means this is the workspace's inbox and it can be reused.
* A different client ID means the username belongs to another owner and the state becomes <code>username\_conflict</code>.

The application does not take over an inbox with a different client ID.

## Provisioning states

| State                           | Meaning                                                    |
| ------------------------------- | ---------------------------------------------------------- |
| Provisioned                     | Inbox exists and its email is stored in workspace metadata |
| Unconfigured                    | Operator AgentMail key is absent                           |
| Failed                          | Provider request or ownership check failed                 |
| <code>username\_conflict</code> | Derived username belongs to another client identity        |

## Backfill

The session-only backfill action requires <code>workspaces:create</code> permission. It scans accessible workspaces and attempts provisioning only where needed. The response counts total, provisioned, unconfigured, and failed workspaces. A username conflict is counted as failed.

Already provisioned workspaces are not recreated.

<Note>
  AgentMail is operator infrastructure, not a workspace connection card. The generated email is the workspace identity that a customer invites to external properties.
</Note>

## Recovery

For <code>username\_conflict</code>, inspect the existing AgentMail inbox metadata. Resolve the conflicting account or slug outside the automated backfill, then retry. Do not delete or reassign an inbox until its ownership is confirmed.