---
title: "Create a mailbox on domani.run"
method: POST
path: "/api/email"
tags: ["Email"]
---

# Create a mailbox on domani.run

`POST /api/email`

## Request

- Base URL: `https://domani.run`
- URL: `https://domani.run/api/email`
- Auth: HTTP bearer

Create a free email address on domani.run (e.g. hello@domani.run). No domain ownership required. Limited to 1 free @domani.run mailbox per user. Many common slugs are reserved.

## Request body

- object
  - `slug` string, required: Local part of the email address (e.g. 'hello' for hello@domani.run)
  - `name` string: Display name (defaults to capitalized slug)

## Response `201`

Mailbox created

- object
  - `id` string, required
  - `address` string, required
  - `name` string, nullable, required
  - `slug` string, required
  - `domain` string, required
  - `kind` string, required
  - `workspace_id` string, nullable, required
  - `access_role` 'viewer' | 'responder' | 'manager', required
  - `effective_capabilities` string[], required: Concrete permissions already intersected with mailbox role, workspace entitlement, and token scopes. Clients should render from these values instead of inferring behavior from access_role.
  - `collaboration_enabled` boolean, required
  - `shared` boolean, required: Whether at least one principal other than the caller can read this mailbox
  - `message_count` integer, required
  - `webhook_url` string, nullable, required
  - `header_names` string[], required: Configured webhook authentication header names; values are never returned
  - `forward_to` string, nullable, required
  - `signing_secret` string, nullable
  - `created_at` string, date-time, required
  - `hint` string, required

---

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