Agent vs Human Inboxes

Agentry exposes two inbox surfaces. The difference is not whether an AI agent uses the API. The difference is where the mailbox lives.

• Agent API (/agent/v0) is for inboxes hosted by Agentry for your agents.
• Human API (/human/v0) is for agent-friendly access to human-owned inboxes hosted elsewhere, such as Gmail, Outlook, or IMAP.

In SDK terms, client.agent works with mailboxes Agentry hosts for agents. client.human works with existing human mailboxes after the owner connects their provider account.

Choose Agent

Use the Agent API when your product needs a mailbox for an AI agent.

• Agentry hosts the inbox.
• Your app creates and manages the inbox lifecycle.
• Messages are sent from an agent-owned address.
• You want AgentMail-compatible hosted inbox semantics.

// My agent can view its Agentry-hosted inboxes.
const agentInboxes = await client.agent.inboxes.list();

// The agent sends from an inbox Agentry hosts for it.
await client.agent.messages.send("assistant@example.com", {
  body: {
    to: ["customer@example.com"],
    subject: "Thanks for reaching out",
    text: "I can help with that.",
  },
});

Choose Human

Use the Human API when your product needs to work with a real person's existing mailbox.

• The inbox remains hosted by the user's email provider.
• The owner connects the account through OAuth or IMAP.
• Your agent gets a structured API for reading context, syncing state, and acting on that mailbox.
• The same inbox, history, contacts, and provider identity remain the source of truth.

// I can list my connected human inboxes.
const humanInboxes = await client.human.inboxes.list();

// To connect a human mailbox, send the owner through the provider auth flow.
const authUrl = await client.human.auth.createUrl({
  body: {
    provider: "google_oauth",
    human_user_id: "user_123",
  },
});

Shared Building Blocks

The API methods are deliberately similar across both surfaces. Inboxes, messages, drafts, threads, metrics, webhooks, and API keys follow the same broad shape, so an agent can use familiar primitives whether it is operating from its own hosted inbox or assisting with a connected human inbox.

// Agent-hosted inbox.
const agentThreads =
  await client.agent.threads.listForInbox("assistant@example.com");

// Human-owned inbox, hosted by the user's provider.
const humanThreads = await client.human.threads.listForInbox(
  "founder@example.com",
);

Use Both Together

Use both surfaces when your product needs both an agent identity and access to a user's existing mailbox.

For example, a support copilot might read a founder's connected Gmail through client.human, understand the customer relationship and thread history, then draft or send follow-up from an Agentry-hosted assistant inbox through client.agent.

That keeps the two identities clear: the human inbox stays the human's mailbox, while the hosted agent inbox gives the agent its own address, delivery events, webhooks, and operational boundaries.