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. Next: set up Connections to invite the workspace email to GA4 and Search Console.