Configure Agent Email

Sending and Agent Email configuration

Agent Email uses Cloudflare Email Routing and an inbound Worker to reach the Product API, then Cloudflare Email Sending for replies. Enabling outbound transactional email alone does not complete Agent Email setup.

Configure CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_API_TOKEN, and SENDER_EMAIL for sending, then AGENT_EMAIL_DOMAIN and EMAIL_INBOUND_SECRET for Agent Email. The Email plugin refuses new Connections until the required environment configuration is available. The sending API token and the Worker deployment token have different responsibilities.

Set up inbound routing

Onboard the Agent email subdomain for both Email Routing and Email Sending. Enable subaddressing so addresses such as agent+<local-part>@agents.example.com match the base mailbox rule. The default base mailbox is agent, controlled by AGENT_EMAIL_MAILBOX.

Deploy the inbound Worker with INBOUND_URL pointing to the publicly reachable /communications/v1/webhooks/email/inbound endpoint for the intended environment. Configure the Worker's EMAIL_INBOUND_SECRET to match the gateway's value. Use distinct inbound secrets for staging and production.

Once the Worker exists, configure the base-address routing rule to target it. Worker deployment does not create or repoint that routing rule. When replacing a tunnel-era or differently named Worker, deploy the replacement, repoint the rule, and only then remove the old Worker.

Deployment workflows

The application repository's k3s deploy workflow invokes Worker publication after the cluster deployment when Worker paths change or manual dispatch selects every component. Its Worker workflow requires CLOUDFLARE_WORKERS_TOKEN for script deployment, separately from the sending token. Staging uses STAGING_AGENT_EMAIL_DOMAIN and STAGING_EMAIL_INBOUND_SECRET; production uses the unprefixed counterparts.

The configured Worker names are agentbarn-email-inbound-staging for staging and agentbarn-email-inbound for production. Their endpoint configuration must match the installation being operated. The public-tag cluster deployment does not itself publish this Worker; do not assume a successful cluster release has completed Email setup.

Troubleshooting

A subaddress bounce before an activity entry can indicate disabled subaddressing or an unmatched rule. Inbound success with failed replies can indicate incomplete sending-domain setup. An unauthorized gateway response can indicate mismatched inbound secrets. A rule still pointing to a local tunnel Worker continues using that target after a different Worker is deployed.

Local k3d is not publicly reachable from Cloudflare by default. A local Email path requires an intentionally configured reachable endpoint. Agent replies share the account's sending quota with transactional email.

Rotate the inbound secret across both deployments

The inbound Worker presents EMAIL_INBOUND_SECRET to the Product API. Both sides must use the same value for that environment. Staging and production use distinct inbound secrets.

For the application repository's AAI Labs k3s workflow:

1. Update the intended environment's GitHub secret: STAGING_EMAIL_INBOUND_SECRET for staging, or EMAIL_INBOUND_SECRET for main's k3s environment. Preserve distinct values between environments.
2. Manually dispatch Deploy to k3s (deploy.yml) from the intended staging or main branch. At this baseline, manual dispatch selects every component, including the Worker. Changing a GitHub secret alone does not trigger a workflow, and an ordinary push without Worker changes may leave Worker publication unselected.
3. Follow the cluster deployment and the subsequent Worker publication. Confirm that the Product API workload has picked up the new environment and that the intended Worker received its matching value. Do not treat a cluster-only success as completed rotation.
4. After both updates complete, use the deployment's normal Email canary to check ingress and the reply path. Do not expose or paste secret values into logs or support records.

These steps describe the k3s workflow, not the public-tag deployment. The public-tag workflow does not publish the inbound Worker. For an independent installation, coordinate your own gateway rollout and Worker secret publication, preserving the same one-secret limitation. Reversing the order does not remove it.

If rotation leaves Email unavailable

A Worker-to-gateway 401 can indicate that one side still has the previous secret. Check the environment and the result of both deployment steps. If Worker publication failed after the cluster changed, the service's successful rollout alone has not completed rotation. Restore agreement through the installation's deployment/recovery process. Do not assume a later unrelated push will select the Worker, or that rejected mail will automatically be replayed.

Worker publication and routing-rule cutover are separate operations. Updating an existing Worker's secret does not repoint an Email Routing rule to another Worker.

Related documentation

Continue with Connect an Agent to Email, Self-host Communications, and Configure production.