---
title: "Self-register a zero-signup agent API key"
method: POST
path: "/agents/register"
tags: ["agents"]
---

# Self-register a zero-signup agent API key

`POST /agents/register`

## Request

- Base URL: `https://dash.mailsocket.app/api/v1`
- URL: `https://dash.mailsocket.app/api/v1/agents/register`
- Auth: none required

UNauthenticated on purpose. An agent (or a dev) posts an optional
`name` and gets back a working API key plus a ready-to-use inbox in
one call; no email, no human confirmation. The plaintext key is
returned ONCE and never retrievable again. IP-rate-limited AND
globally rate-limited (a fixed hourly cap across all sources), and
the resulting account is Free-plan, subject to a shared reduced
wait-capacity pool and idle-account garbage collection.
`Idempotency-Key` is not supported here: there is no account to
scope the key to, so the header is ignored and every call mints a
new key.

## Request body

- object
  - `name` string: Optional label for the minted key. A string longer than 60 characters is `422 validation_error` with `fields.name` (nothing is minted); a non-string value is ignored.

## Response `201`

Agent account, API key, and first inbox created.

- object
  - `data` object, required
    - `api_key` string, required: The plaintext key. Shown once; store it securely.
    - `key_prefix` string, required
    - `plan` 'free', required
    - `message` string, required
    - `inbox` Inbox
      - `id` string, required: The inbox public ID.
      - `label` string, required
      - `address` string, required: The full inbound email address.
      - `is_enabled` boolean, required
      - `created_at` string, date-time, required
      - `updated_at` string, date-time, required
      - `metadata` object, required: Your correlation metadata, `{}` when unset. Never returned by unauthenticated endpoints.

## Other responses

- `415`: Request media type is not supported.
- `422`: The body is not valid JSON (`validation_error`, `fields.body: ["Malformed JSON body."]`), or `name` is longer than 60 characters (`validation_error`, `fields.name`). Send `application/json` with an object such as `{"name": "my-agent"}`, or no body at all.
- `429`: Per-IP or global agent-registration rate limit exceeded.

---

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