---
title: "Create a mailbox"
method: POST
path: "/api/emails"
tags: ["Email"]
---

# Create a mailbox

`POST /api/emails`

## Request

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

Create an email address (mailbox). Provide a full address like "hello@mysite.com". Email DNS is auto-configured on first use. Pass force=true to override an existing email provider. Custom-domain mailbox capacity is determined by the active account or workspace plan. Every account can create one free @domani.run mailbox separately with POST /api/email.

Pass workspace_id to create the mailbox inside a workspace you own. For a custom domain, this explicitly and atomically adopts the domain and all its unscoped sibling mailboxes into that workspace; a domain can never be split across workspaces.

Pass kind="hosted" to create a real IMAP/SMTP mailbox on your own domain (connect Apple Mail, Thunderbird, or any client) instead of the default API mailbox (send/receive via API + webhooks). Hosted mailboxes return DNS records to publish, mail client settings, and a one-time app password. Requires a domain you own.

## Request body

- object
  - `address` string, required: Full email address, e.g. hello@mysite.com
  - `name` string: Display name for outbound emails (e.g. "John Doe")
  - `force` boolean: Override existing MX records. Default: false
  - `kind` 'api' | 'hosted': "api" (default: send/receive via API + webhooks) or "hosted" (real IMAP/SMTP mailbox on your domain)
  - `workspace_id` string: Workspace to own the mailbox. Only the workspace owner can adopt resources.

## Response `201`

Mailbox created

- object
  - `id` string, required
  - `address` string, required
  - `name` string, nullable
  - `domain` string
  - `slug` string
  - `kind` string, required
  - `workspace_id` string, nullable, required
  - `access_role` 'viewer' | 'responder' | 'manager'
  - `effective_capabilities` string[]: 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
  - `shared` boolean: Whether at least one principal other than the caller can read this mailbox
  - `message_count` integer
  - `webhook_url` string, nullable
  - `header_names` string[]: Configured webhook authentication header names; values are never returned
  - `forward_to` string, nullable
  - `signing_secret` string, nullable: HMAC secret for verifying inbound webhook payloads (shown once at creation)
  - `host_id` string: Mail-host principal id for a hosted mailbox
  - `dns_records` DnsRecord[]
    - `type` 'A' | 'AAAA' | 'CNAME' | 'MX' | 'TXT' | 'NS' | 'SRV' | 'CAA' | 'TLSA', required: DNS record type. TLSA publishes a DANE record; its value is the rdata 'usage selector matching-type hex-data'.
    - `name` string, required: Record name (@ for root, or subdomain, e.g. _443._tcp for TLSA)
    - `value` string, required: Record value (IP address, hostname, or TLSA rdata like '3 1 1 abc123...')
    - `ttl` integer, required: Time to live in seconds
    - `priority` integer: Priority value (required for MX records)
    - `required` boolean: False when the zone Domani manages for the domain cannot hold the record (a TXT longer than the registrar accepts); such a record is shown but not needed for mail to work. Absent on plain zone records.
  - `dns_status` 'published' | 'manual'
  - `receiving_status` 'pending'
  - `sending_status` 'pending' | 'unavailable'
  - `sending_error` object
    - `code` 'MAIL_DOMAIN_CAPACITY_EXHAUSTED' | 'MAIL_PROVIDER_ERROR'
    - `retryable` boolean
  - `client_settings` object
  - `credential` object
    - `id` string
    - `label` string
    - `password` string: One-time app password; never returned again
  - `storage_quota_bytes` integer
  - `created_at` string, date-time
  - `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)