A return address for AI agents.

Need a callback URL or somewhere a person can reply after this run ends?

Create one address now. Its write-only HTTPS inbox and inbound email address feed a private, ordered queue you can read in a later run—without running a server yourself.

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.

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.

Create an AgentAddress with one API call

No account or API key is required for V1 provisioning.

For agent workflows, start with the installable skill and CLI helper. It saves the one-time read token in owner-only task storage, outside model context. The REST example below shows the underlying contract for clients that manage secrets themselves.

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?

Save credentials.read_token and endpoints.events_url before the current run ends.
Hand off endpoints.inbox_url as the callback URL, or give address.email to the responder.
Exit safely. The AgentAddress continues receiving callbacks (HTTP events and email) without your process running.
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.

What a later run finds

One ordered feed holds an email reply and an HTTPS callback. A person with the saved read token can inspect the same events in the inbox viewer.

Example inboxSample data · one address

Inbound email · event 2

Review complete

From: person@example.com
To: task@inbox.example
Status: Waiting to be handled

I looked over the draft. You can move ahead with the next step.

View event data

{
  "sequence": 2,
  "type": "email.received",
  "source": "resend",
  "ingress_surface": "resend",
  "data": {
    "from": "person@example.com",
    "subject": "Review complete",
    "text": "I looked over the draft. You can move ahead with the next step."
  }
}

Run a concrete example

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

Keep task context between runs

Save small JSON values behind the same read token. State updates join the activity feed; values remain until replaced, deleted, or the address expires. Use the CLI helper or state API for up to 32 keys and 65,536 bytes per address.

For authorized email tasks, send plain text or reply to verified contacts when sending is configured. Replies return to the address's inbox.

Free today. A $17/month paid tier is coming, with allowances still being finalized. Pricing and limits →

To learn more, read from the links below:

HTTP, email, and state changes share an ordered activity feed. General file storage is still planned.

Machine entry points

Start with the contract.

No dashboard is required to understand or provision the service.

GET Homepage as Markdown: /index.md →
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 →