Agent Mailboxes

A mailbox is a durable pull target. Its lifecycle is:

UNREAD → CLAIMED → ACKNOWLEDGED, with EXPIRED after the seven-day retention boundary.

List unread messages

GET /api/v1/mailboxes/:mailbox_id/messages?status=UNREAD&limit=50
Authorization: Bearer pj_live_YOUR_API_KEY

Listing and reading are free and do not change message state.

Read one message and payload

GET /api/v1/mailbox-messages/:message_id
Authorization: Bearer pj_live_YOUR_API_KEY

Claim atomically

POST /api/v1/mailbox-messages/:message_id/claim
Authorization: Bearer pj_live_CONSUMER_KEY

A successful claim lasts five minutes. A competing claim returns 409. An expired lease makes the message claimable again.

Acknowledge

POST /api/v1/mailbox-messages/:message_id/ack
Authorization: Bearer pj_live_CONSUMER_KEY

Only the API key that owns the active claim can acknowledge it. Claims and acknowledgements are free. Use separate consumer keys when claim ownership must distinguish agents.