Skip to main content
Each workspace can receive an AgentMail address under the operator’s AgentMail organization. The operator supplies one organization-level AGENTMAIL_API_KEY; workspaces never receive that secret. Teams use the generated address when granting GA4 and Search Console access.

​
Provisioning

For each workspace, the application derives:
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 username_conflict.
The application does not take over an inbox with a different client ID.

​
Provisioning states

​
Backfill

The session-only backfill action requires workspaces:create 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.
AgentMail is operator infrastructure, not a workspace connection card. The generated email is the workspace identity that a customer invites to external properties.

​
Recovery

For username_conflict, 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.