Create an AgentMail.to inbox and restrict the agent key

AgentMail provides API-first inboxes for software. Provision an inbox for the agent’s task, then limit its runtime access; do not give a classifier the organization’s unrestricted provisioning key simply because it was convenient in a quickstart.

Provision once with a stable operation identity

Use an existing approved account and securely supply its provisioning key. Install agentmail with npm install agentmail. This Node.js example creates a real inbox but sends no email:

import { AgentMailClient } from "agentmail";
for (const key of ["AGENTMAIL_PROVISIONING_KEY", "AGENTMAIL_INBOX_CLIENT_ID"]) {
  if (!process.env[key]) throw new Error(`Missing ${key}`);
}
const client = new AgentMailClient({
  apiKey: process.env.AGENTMAIL_PROVISIONING_KEY,
});
const inbox = await client.inboxes.create({
  clientId: process.env.AGENTMAIL_INBOX_CLIENT_ID,
});
console.log({ inboxId: inbox.inboxId });

Choose AGENTMAIL_INBOX_CLIENT_ID once per logical inbox and persist it before provisioning. Reuse it only for retries of that same operation; AgentMail’s idempotency guide distinguishes create-resource IDs from send idempotency. Use its documented character rules, not an email address containing @.

The quickstart documents hosted-domain inboxes and custom-domain onboarding. Do not move employee mailbox MX to AgentMail just to create a test inbox. Account verification, plan, region, and custom-domain requirements still apply.

Replace provisioning access with runtime permissions

Use an inbox-scoped key with an explicit permissions whitelist. For a draft-producing agent, select only the needed inbox/message reads and draft operations; omit message_send and draft_send from its grant. Keep provisioning/key-management permissions in a separate trusted service.

AgentMail’s permission reference says omitted permissions are denied when a permissions object is supplied; leaving the entire object absent is not a read-only default. Scope and permissions intersect. API JSON uses snake_case names while the JavaScript SDK uses its documented camelCase fields.

Verify a permitted read and a denied send against the intended scope using safe tests. Preserve the inbox identity and revoke unused provisioning credentials according to your operations policy. Never log the full API key or embed it into mail sent to the agent.