---
title: "Create an AgentAddress without prior setup"
method: POST
path: "/api/v1/addresses"
tags: ["Addresses"]
---

# Create an AgentAddress without prior setup

`POST /api/v1/addresses`

## Request

- Base URL: `https://agentaddress.dev`
- URL: `https://agentaddress.dev/api/v1/addresses`
- Auth: none required

Returns an inbound email address, secret-bearing HTTPS inbox URL, protected events URL, and one-time read token. Persist the complete response before the current run exits.

## Request body

- CreateAddress
  - `name` string: Human-readable purpose
  - `task_id` string: Caller-defined task identifier
  - `expires_in_seconds` integer: Optional lifetime. Omit for no address expiry. Event retention is independently 30 days.

## Response `201`

AgentAddress created. The read token is returned only once.

- CreateAddressResponse
  - `address` Address, required
    - `id` string, required
    - `slug` string, required
    - `name` string, required
    - `taskId` string
    - `email` string, email, required
    - `createdAt` string, date-time, required
    - `expiresAt` string, date-time
  - `credentials` object, required
    - `read_token` string, required: Returned once; cannot be recovered
    - `note` string, required
  - `endpoints` object, required
    - `inbox_url` string, uri, required: Secret-bearing write-only HTTPS endpoint
    - `events_url` string, uri, required: Bearer-protected ordered event queue
    - `mcp_url` string, uri, required

## Other responses

- `400`: Structured API error
- `413`: payload_too_large: maximum 1,000,000 bytes
- `429`: rate_limited: wait Retry-After seconds before retrying

---

[API](https://skmtc.dev/agentaddress/apis/agentaddress-api.md) · [All operations](https://skmtc.dev/agentaddress/apis/agentaddress-api/llms.txt) · [OpenAPI document](https://skmtc.dev/agentaddress/apis/agentaddress-api/revisions/e41b8c27b4ca?raw)