AgentAddress

Persistent webhooks, callback queues, and an email inbox for AI agents that outlive the run. Agents create a task-scoped HTTPS inbox + email + ordered event queue with one POST; a future run polls and acks events. Hosted remote MCP endpoint: https://agentaddress.dev/api/mcp

View on agentaddress.devTry this MCPSponsored

Hosted MCP Server

npx add-mcp 'https://agentaddress.dev/api/mcp'

Installs into Claude Code, Codex, Cursor and more

Documentation

Persistent webhooks, HTTP callback queues, and an email inbox for AI agents.

Designed for AI agents.

Return later and retrieve everything from one durable queue, without running a server yourself.

Use AgentAddress when

  • An API requires a webhook or callback URL and you do not have a public server.
  • 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.

What is an AgentAddress?

An AgentAddress is one task-scoped resource that remains available after the agent process that created it has exited.

HTTPS inbox

A public, write-only URL where software can send webhooks and callbacks.

Email address

A public address where humans, services, or other agents can reply.

Event queue

A private, ordered feed containing everything received through HTTP and email.

Read token

The credential a future agent run uses to retrieve and acknowledge events.

Create an AgentAddress with one API call

No account or API key is required for V1 provisioning.

curl -X POST "https://agentaddress.dev/api/v1/addresses" \
  -H "content-type: application/json" \
  -d '{"task_id":"my_async_task"}'

Save the response

Persist the entire response with the task. The read token is shown once and cannot be recovered.

{
  "address": {
    "id": "addr_...",
    "email": "...@inbox.agentaddress.dev"
  },
  "credentials": {
    "read_token": "aa_read_..."
  },
  "endpoints": {
    "inbox_url": "https://.../api/v1/inbox/addr_.../secret",
    "events_url": "https://.../api/v1/addresses/addr_.../events",
    "mcp_url": "https://.../api/mcp"
  }
}

What happens next?

  1. Save credentials.read_token and endpoints.events_url before the current run ends.
  2. Hand off endpoints.inbox_url as the callback URL, or give address.email to the responder.
  3. Exit safely. The AgentAddress continues receiving HTTP events and email without your process running.
  4. Return later and poll the event queue with the saved read token.

Poll for events

GET {endpoints.events_url}?after=0&wait=25
Authorization: Bearer {credentials.read_token}

Response

{
  "events": [{
    "id": "evt_...",
    "address_id": "addr_...",
    "sequence": 1,
    "type": "quote.ready",
    "source": "vendor",
    "data": { "total": 4200, "currency": "USD" },
    "created_at": "..."
  }],
  "next_cursor": 1,
  "has_more": false
}

Process events in sequence order. Save next_cursor and use it as the next after value.

After handling an event, acknowledge it with POST {endpoints.events_url}/{event.id}/ack using the same Authorization header.

Run a concrete example

Five public examples show separate processes creating a return path, exiting, receiving a later response, and resuming safely.

HTTP and email already arrive as the same ordered event shape. State changes and file activity will join this feed only when those surfaces ship.

Machine entry points

Start with the contract.

No dashboard is required to understand or provision the service.

GET Agent-readable index

/llms.txt →

GET Complete agent guide

/llms-full.txt →

GET Installable Agent Skill

/skill.md →

GET Capability discovery

/.well-known/agentaddress.json →

GET OpenAPI 3.1 contract

/openapi.json →

POST MCP endpoint

/api/mcp →

GET Markdown documentation

/docs.md →