---
title: "Create inbox"
method: POST
path: "/v1/inboxes"
tags: ["Inboxes"]
---

# Create inbox

`POST /v1/inboxes`

## Request

- Base URL: `https://api.deadsimple.email`
- URL: `https://api.deadsimple.email/v1/inboxes`
- Auth: HTTP bearer

## Headers

- `X-Workspace-Id` string, uuid

## Request body

- object
  - `display_name` string
  - `domain` string
  - `local_part` string
  - `tags` string[]

## Response `201`

Inbox created with email address. When paid per request, the response also carries a payment header and, on a payer's first inbox, `credentials`.

- object
  - `data` InboxCreated
    - `inbox_id` string, uuid
    - `workspace_id` string, uuid
    - `email` string, email
    - `local_part` string
    - `domain` string
    - `display_name` string
    - `tags` string[]
    - `status` 'active' | 'paused'
    - `message_count` integer
    - `created_at` string, date-time
    - `updated_at` string, date-time
    - `credentials` PaymentCredentials: Issued once, on a payer's first paid inbox. The API key belongs to the Pay as you go account keyed on the wallet (or created for this card purchase) and has the same scoped permissions as an agent-signup key.
      - `api_key` string: Shown once.
      - `key_id` string
      - `account_id` string
      - `note` string
      - `warning` string
    - `payment` PaymentSettlement: How the call was paid. x402 gives {transaction, network, payer}; MPP gives {reference, method}.
      - `transaction` string: On-chain transaction (x402).
      - `network` string: CAIP-2 network (x402).
      - `payer` string: Payer wallet address (x402).
      - `reference` string: Stripe PaymentIntent id (MPP).
      - `method` string: Payment method (MPP).

## Other responses

- `402`: Payment required. The request had no API key and this route can be paid per call. The x402 requirements are in the PAYMENT-REQUIRED header and repeated in the body; routes priced at or above $0.50 (inbox creation) also carry a Stripe MPP challenge in WWW-Authenticate. A rejected or mismatched payment gets this same response again with error.reason explaining why. Responses are Cache-Control no-store and expose the payment headers to browsers.

---

[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)