Agent vs Human Inboxes

When to use each API surface and how they work together.

View as Markdown

Agentry exposes two distinct API surfaces:

  • Agent API (/agent/v0) for AgentMail-compatible mailbox workflows.
  • Human API (/human/v0) for connected human account workflows.

Decision Framework

Use Agent API when:

  • You need drop-in AgentMail semantics and SDK compatibility.
  • You are creating/managing hosted inboxes and agent-originated messages.
  • You rely on agent events like message.received and message.delivered.

Use Human API when:

  • You need to connect real human-owned mailboxes (OAuth or IMAP).
  • You need smart routing and relationship-aware context.
  • You need deep memory/context operations tied to human account activity.

Namespace Summary

SurfaceBase URLPrimary use case
Agenthttps://api.agentry.to/agent/v0Hosted inbox and AgentMail parity workflows
Humanhttps://api.agentry.to/human/v0Connected human accounts and context workflows

Shared Building Blocks

Both surfaces share core product infrastructure:

  • Authentication and permission boundaries
  • Durable webhook delivery and retry behavior
  • Realtime fanout model and delivery filtering
  • Audit logging and usage accounting

Combined Pattern

Many products use both surfaces together:

  1. Receive and classify intent via Human smart routing.
  2. Pull relationship/context from Human endpoints.
  3. Generate/send operational responses via Agent hosted inboxes.

This keeps customer communication grounded in human context while preserving strict agent operation boundaries.