Create a mailbox

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.

post/api/emails

Request

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

Request body

addressstring required

Full email address, e.g. hello@mysite.com

namestring

Display name for outbound emails (e.g. "John Doe")

forceboolean

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_idstring

Workspace to own the mailbox. Only the workspace owner can adopt resources.

Response

Mailbox created

idstring required

addressstring required

namestring nullable

domainstring

slugstring

kindstring required

workspace_idstring nullable required

access_role'viewer' | 'responder' | 'manager'

effective_capabilitiesstring[]

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_enabledboolean

sharedboolean

Whether at least one principal other than the caller can read this mailbox

message_countinteger

webhook_urlstring nullable

header_namesstring[]

Configured webhook authentication header names; values are never returned

forward_tostring nullable

signing_secretstring nullable

HMAC secret for verifying inbound webhook payloads (shown once at creation)

host_idstring

Mail-host principal id for a hosted mailbox

dns_status'published' | 'manual'

receiving_status'pending'

sending_status'pending' | 'unavailable'

client_settingsobject

storage_quota_bytesinteger

created_atstring date-time

hintstring required

Example response

{
  "dns_records": [
    {
      "name": "@",
      "value": "76.76.21.21",
      "ttl": 3600
    }
  ]
}

Changes

No recorded changes to this operation across all 2 revisions of this API.