Skip to main content
The key you get at signup reaches every inbox on your account. An agent runs untrusted input all day, so never hand it that key. Give it the narrowest scope that fits and keep the account-wide key on your side.

​
Pick the scope

An inbox-scoped key can read and send from its one inbox and nothing else. It cannot see other inboxes, create or delete inboxes, mint keys, or read the sender rules that apply to it. If an email tricks the agent, the damage stops at that inbox.

​
Mint one

Minting needs an account-wide key, or a pod key for the inbox’s pod. Run it from your own shell or backend, never from the agent’s. The token is shown once.
Put the returned token in the agent’s OPENMAIL_API_KEY.

​
Plugins do this for you

Both plugins swap an account key for a pod-scoped key during setup and store only that. The account key never touches disk. A pod key still lets the agent create inboxes in its pod, which is what lets one account grow into several inboxes later without a new key from the console.
  • OpenClaw: channels add
  • Hermes Agent: hermes openmail setup
Pass an inbox-scoped key instead if you want the agent confined to one inbox; both plugins store it as-is.

​
Rotate and revoke

Each inbox and pod holds up to 20 active keys. To rotate, mint a new key, switch the agent over, then revoke the old one; it gets 401 immediately. Deleting an inbox revokes its keys with it.