diff --git a/chatkit.mdx b/chatkit.mdx
index cda4a04..5fa22cf 100644
--- a/chatkit.mdx
+++ b/chatkit.mdx
@@ -83,6 +83,8 @@ Signal providers and rules use the same two planes. Visibility controls discover
 
   <Step title="Connect a channel and test">
     Go to **ChatKit** → **Configure Chat Providers** and choose where people will talk to the agent. Link the provider to your registered agent, then open [Mission Control](https://api.trytilde.ai/mission-control) to start a test session.
+
+    For **AgentMail**, create the inbox in AgentMail first and create an inbox-scoped API key with message and thread read/write permissions. Enter the inbox ID in Tilde. Tilde then shows the exact tenant-scoped webhook URL to register in AgentMail. Create an AgentMail webhook that points directly to that URL, restrict it to the inbox, and subscribe to `message.received`, `message.received.spam`, `message.received.blocked`, and `message.received.unauthenticated`. Resume setup with the inbox API key and the webhook's `whsec_...` signing secret. Each AgentMail email thread becomes one ChatKit session, and agent responses reply to the same email thread. ChatKit uses extracted plain text and retains HTML/attachment metadata; automatic replies are plain text. Use AgentMail's MCP tools for attachment download or file-bearing sends.
   </Step>
 </Steps>
 
diff --git a/llms/chatkit.md b/llms/chatkit.md
index 9190008..34f5811 100644
--- a/llms/chatkit.md
+++ b/llms/chatkit.md
@@ -50,6 +50,8 @@ Bound tenant, target-agent, and ingress-channel fields are supplied by Tilde and
 1. Call `tilde_search_available_capabilities` with `kinds: ["chatkit_provider"]` and `include_schemas: true`.
 2. Select the provider ID from the results.
 3. Call `tilde_configure_chatkit_provider` with `provider_id`, `display_name`, the registered agent inbox ID, and any provider-specific configuration from the returned schema.
+
+For AgentMail, select `chatkit.chat_channel.agentmail` / `chatkit.channel.agentmail` and the self-managed API-key auth method. The user must create the AgentMail inbox and an inbox-scoped API key first. Start setup with `inbox_id`; Tilde returns a direct webhook URL and a resume form. In AgentMail, create an inbox-filtered webhook for all four `message.received*` events at that exact URL, then resume with `api_key` and the returned `whsec_...` `webhook_secret`. Never request or configure a Tilde-managed AgentMail account. One AgentMail `thread_id` maps to one ChatKit session. ChatKit prefers extracted plain text, records HTML and attachment metadata, and sends automatic replies as plain text; use the AgentMail MCP provider for file transfer.
 4. If setup requires human authorization, present the returned approval URL and wait with the returned continuation tool.
 5. Call `tilde_search_enabled_capabilities` with `kinds: ["chatkit_channel", "chatkit_agent"]` to verify both resources.
 
@@ -80,6 +82,8 @@ Provider/rule visibility controls discovery and delivery reads. Ownership contro
 3. Call `tilde_create_signal_rule` with a `body` that selects the event type, target agent, action, and stable session-key mapping.
 4. Use one stable session key when related events should continue the same body of work, such as all updates to one Sentry issue or GitHub pull request.
 5. Call `tilde_trigger_fake_signal` to test routing where the provider supports it.
+
+The `agentmail` Signals provider supports `domain.verified`, message delivery/lifecycle events, all four received-message variants, and the three Agent Armor security metadata events. Configure the generated Tilde webhook URL directly in AgentMail and paste the endpoint's `whsec_...` signing secret into Tilde. Keys used to configure spam, blocked, or unauthenticated event subscriptions need the corresponding label-read permissions. Do not add an intermediary webhook relay.
 6. Inspect execution with `tilde_list_signal_deliveries`. Use `tilde_retry_signal_delivery` only for a failed delivery that is safe to repeat.
 
 Use `tilde_list_signal_provider_instances` and `tilde_list_signal_rules` before updating or deleting resources. Their mutation functions are `tilde_update_signal_provider`, `tilde_delete_signal_provider`, `tilde_update_signal_rule`, and `tilde_delete_signal_rule`.
diff --git a/llms/state.md b/llms/state.md
index 382f7c7..f07b749 100644
--- a/llms/state.md
+++ b/llms/state.md
@@ -35,3 +35,11 @@ For custom deployed agents, compare the state file and implementation with the [
 Never call import as a substitute for plan. Use the same exact state and variables for validation, planning, and application.
 
 See the [human portable state guide](https://trytilde.ai/docs/terraform) for dashboard, CLI, multi-environment, and Deploy with Tilde workflows.
+
+## AgentMail state
+
+AgentMail state is portable across environments without exporting plaintext
+secrets. ChatKit exports `agentmailInboxId` and credential/MCP references, then
+derives the webhook URL in the target environment. AgentMail Signals exports an
+`AGENTMAIL_WEBHOOK_SECRET_*` string variable; obtain the target endpoint's
+`whsec_...` value from AgentMail and provide it only as an import variable.
diff --git a/llms/tools.md b/llms/tools.md
index 5d2e5c2..f87a2b0 100644
--- a/llms/tools.md
+++ b/llms/tools.md
@@ -72,6 +72,8 @@ Use `tilde_connect_proxied_mcp_server` for an existing Streamable HTTP MCP URL.
 
 For the server-authored hosted-provider catalog, direct the user to **Tools** → **Proxied MCP servers** → **Browse provider catalog**. Every published entry exposes reviewed tool definitions before credentials are supplied; providers without a validated snapshot are not published as connectable. Tilde records whether each snapshot is an exact public `tools/list` result or was inferred from official source or documentation; an authenticated `tools/list` response replaces the snapshot after connection.
 
+AgentMail is the `agentmail` catalog entry at `https://mcp.agentmail.to/mcp`. It is self-managed only: use an inbox-scoped AgentMail API key in the `x-api-key` header. The checked-in official manifest exposes inbox, thread, message, draft, attachment, and auth tools. The AgentMail Reverse Proxy uses `https://api.agentmail.to/v0` and injects the same API key as a bearer token.
+
 Do not ask the user to paste provider secrets into chat or into MCP arguments. OAuth client secrets, API keys, and bearer tokens must be entered through Tilde's credential setup. Dynamic OAuth client registrations are environment-specific and require authorization again after state import; pre-registered manual OAuth configurations remain declarative and their user credential is reconnected separately.
 
 Use `tilde_register_custom_tool_backend` for a signed discovery endpoint created with Harness SDK `toolEndpoint`. Save the one-time signing key in the tool server, then call `tilde_refresh_custom_tool_backend` after its manifest changes.
diff --git a/terraform.mdx b/terraform.mdx
index fde117c..7b5dac3 100644
--- a/terraform.mdx
+++ b/terraform.mdx
@@ -80,3 +80,13 @@ Keep one reviewed state file as the shared baseline. Use variables for environme
 <Warning>
   State imports can update or replace existing configuration. Review conflicts, destructive changes, requested variables, and pending credentials before applying a plan.
 </Warning>
+
+### AgentMail portability
+
+AgentMail provider bundles export without plaintext credentials. The ChatKit
+provider keeps its inbox ID plus references to the AgentMail API-key,
+webhook-secret, and hosted MCP resources; the target environment regenerates
+the direct webhook URL. AgentMail Signals exports an
+`AGENTMAIL_WEBHOOK_SECRET_*` deploy variable because AgentMail creates a new
+`whsec_...` secret for the target webhook endpoint. Supply that variable during
+import, then configure AgentMail to send directly to the imported endpoint.
diff --git a/tools.mdx b/tools.mdx
index bf79b3d..cad693b 100644
--- a/tools.mdx
+++ b/tools.mdx
@@ -122,7 +122,7 @@ Pass the previous session ID to `message` to continue a child conversation. The
 
 ## Connect a hosted MCP provider
 
-Open **Tools** → **Proxied MCP servers** → **Browse provider catalog** to connect a hosted MCP provider. The catalog includes ready-to-configure providers such as Notion, Granola, Browserbase, Parallel, Intercom, Zoom, Salesforce, Clay, Apollo, and HubSpot, alongside public documentation MCP servers.
+Open **Tools** → **Proxied MCP servers** → **Browse provider catalog** to connect a hosted MCP provider. The catalog includes ready-to-configure providers such as AgentMail, Notion, Granola, Browserbase, Parallel, Intercom, Zoom, Salesforce, Clay, Apollo, and HubSpot, alongside public documentation MCP servers.
 
 Tilde loads a reviewed tool-definition snapshot before you connect credentials, so the provider's tools can be inspected and selected in the same way as managed provider tools. After authentication, Tilde calls the upstream server's `tools/list` method and reconciles the deployed definitions with the live catalog. Providers are published in the connectable catalog only after a validated snapshot exists.
 
@@ -133,6 +133,8 @@ Authentication follows the upstream server:
 - OAuth providers use PKCE and published authorization metadata. Providers that support dynamic client registration create a new client for the current Tilde environment.
 - Manual OAuth providers ask for the provider's registered client ID and client secret.
 - API-key and bearer-token providers ask for the secret and the header or query-string placement required by the server.
+
+AgentMail uses `https://mcp.agentmail.to/mcp` with an inbox-scoped API key in the `x-api-key` header. Tilde also offers an AgentMail Reverse Proxy profile for `https://api.agentmail.to/v0`, where the same key is injected as `Authorization: Bearer ...`.
 - Public documentation servers connect without credentials.
 
 OAuth tokens, client secrets, API keys, and bearer tokens are encrypted by Tilde's credential system. They are never stored in a tool definition or exported as plaintext state.