---
title: "Self-serve signup for autonomous agents"
method: POST
path: "/v1/auth/agent-signup"
tags: ["Auth"]
---

# Self-serve signup for autonomous agents

`POST /v1/auth/agent-signup`

## Request

- Base URL: `https://api.deadsimple.email`
- URL: `https://api.deadsimple.email/v1/auth/agent-signup`
- Auth: none required

Provisions an account, an API key, and a live inbox in a single unauthenticated call, so an agent can get an email identity with no human in the loop. The ordinary signup flow needs a mailbox to receive a verification code, which a brand-new agent does not have.

The resulting account is on the `trial` plan: 1 inbox, 10 sends/hour, 25 sends/day, no custom domains. The key it returns is scoped — it cannot buy domains, change billing, create further API keys, manage the team, or create workspaces.

Signups are limited per client IP (3/hour, 10/day) and by a platform-wide hourly ceiling; when that ceiling is hit the endpoint returns `503 signup_capacity_reached`.

Call `POST /v1/auth/claim` to attach a verified email and move to the Free plan, which lifts the trial send limits.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `label` string: Optional name for the agent, used on the inbox and API key.
  - `ref` string: Optional affiliate referral code. Invalid or unknown codes are ignored — they never fail signup.

## Response `201`

Account, API key, and inbox provisioned.

- object
  - `account_id` string
  - `api_key` string: Shown once. Send as `Authorization: Bearer <api_key>`.
  - `key_id` string
  - `inbox` object
    - `inbox_id` string
    - `email` string
  - `plan` object
  - `next_steps` object

## Other responses

- `400`: Idempotency-Key supplied but too short
- `429`: Per-IP signup limit reached
- `503`: Platform-wide signup capacity reached; retry shortly

---

[API](https://skmtc.dev/deadsimple/apis/dead-simple-email-api.md) · [All operations](https://skmtc.dev/deadsimple/apis/dead-simple-email-api/llms.txt) · [OpenAPI document](https://skmtc.dev/deadsimple/apis/dead-simple-email-api/revisions/c697881be131?raw)