# AgentAddress

> Webhook inboxes and persistent callback URLs for AI agents. Receive asynchronous HTTP events and email after the current agent run exits, without running a server.

Use AgentAddress when:
- An API requires a webhook or callback URL you do not have.
- A response may arrive after the current agent run exits.
- A human or service needs an email address for a later reply.
- A future run needs an ordered record of what happened.
- You need to receive an asynchronous result without running a server.

## Start here
- [Full agent guide](https://agentaddress.dev/llms-full.txt)
- [Protocol documentation](https://agentaddress.dev/docs.md)
- [OpenAPI 3.1](https://agentaddress.dev/openapi.json)
- [Capability discovery](https://agentaddress.dev/.well-known/agentaddress.json)
- [MCP endpoint](https://agentaddress.dev/api/mcp)
- [Installable Agent Skill](https://agentaddress.dev/skill.md)

## Intent-specific guides
- [Webhook inbox for AI agents](https://agentaddress.dev/webhooks.md)
- [Persistent callback URLs for AI agents](https://agentaddress.dev/callbacks.md)
- [Email inbox for AI agents](https://agentaddress.dev/email.md)
- [Persistent return paths for asynchronous agents](https://agentaddress.dev/async-agents.md)

## Current scope
HTTP ingress and inbound email are normalized into one durable, ordered event queue. General state and file storage are planned but are not currently available.

## Provision an address

POST https://agentaddress.dev/api/v1/addresses
Content-Type: application/json

{"task_id":"quote_7f2","expires_in_seconds":86400}

No account or API key is required for MVP provisioning. Expiry may be set from 60 seconds to one year.

The 201 response contains:
- address.email: public inbound email address
- endpoints.inbox_url: secret-bearing, write-only HTTPS ingress URL
- endpoints.events_url: bearer-protected ordered event queue
- credentials.read_token: read credential returned exactly once

Persist the entire creation response with the task. The read token cannot be recovered.

## Deliver an HTTP event

POST the responder's JSON to endpoints.inbox_url. Provide an Idempotency-Key header when retries are possible.

Example body:
{"type":"quote.ready","source":"vendor","data":{"total":4200,"currency":"USD"}}

## Poll after the original run ends

GET endpoints.events_url?after=0&wait=25
Authorization: Bearer <read_token>

Events are ordered by sequence. Save next_cursor and use it as the next after value. Acknowledge handled events with POST endpoints.events_url/<event_id>/ack using the same bearer token.

## Delivery semantics
- Delivery: at least once
- Ordering: stable within one address
- Long polling: up to 25 seconds
- Event retention: 30 days
- Address expiry: 60 seconds to one year
- Reads: bearer protected
- HTTPS ingress: write only through a secret-bearing URL

## Product boundary
AgentAddress is a persistence and reachability primitive, not a workflow engine, outbound email provider, or identity system. Email is one inbound surface. General JSON state and file storage are future product surfaces and must not be assumed to exist in V1.