Connect Human Inbox

Human Surface Overview

The Human surface is designed for workflows that operate on real human-owned email accounts:

Account connection and confirmation
Managed sync of inbound/outbound mailbox state
Smart routing webhooks for human message events
Relationship and memory context retrieval

Base Path

Use the Human namespace base:

https://api.agentry.to/human/v0

1) Connect a Human Account (IMAP)

curl -X POST https://api.agentry.to/human/v0/auth/tokens \
  -H "Authorization: Bearer ag_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "human_user_id": "founder_1",
    "provider": "imap",
    "email_address": "founder@example.com",
    "imap": {
      "host": "imap.example.com",
      "port": 993,
      "secure": true,
      "username": "founder@example.com",
      "password": "imap_password"
    },
    "smtp": {
      "host": "smtp.example.com",
      "port": 465,
      "secure": true,
      "username": "founder@example.com",
      "password": "smtp_password"
    }
  }'

The account enters pending_confirmation until confirmed.

2) Create Smart Routing Subscription

curl -X POST https://api.agentry.to/human/v0/webhooks/subscriptions \
  -H "Authorization: Bearer ag_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "human_account_id": "ha_123",
    "target_url": "https://your-app.com/human-events",
    "event_types": ["message.received"]
  }'

3) Read Relationship Context

curl "https://api.agentry.to/human/v0/contacts/client%40example.com/relationship" \
  -H "Authorization: Bearer ag_your_key_here"

This returns VIP and reply-behavior signals for prioritization.

4) Trigger Sync

curl -X POST https://api.agentry.to/human/v0/accounts/ha_123/sync \
  -H "Authorization: Bearer ag_your_key_here"

Use this for operator-triggered refreshes in addition to background processing.