Mailzero documentation

List the standing delegations

The owner's standing delegation rules in order: name, the match predicate, the assignee (an agent identity or a workspace member), the autonomy level, how often each matched. Requires assistant:read; an agent token is refused.

Create a standing delegation

Hand a kind of matter to an agent or a person once. match is an explicit predicate, never a model call: any of senderAddress, senderDomain, organisation, workKeyPrefix, senderKind, mailboxIds, labels, subjectPattern (anchored, case-insensitive), minOccurrences, minConfidence (the calibrated classifier's probability on a category: label, 0.5 to 1); every stated condition must hold. Rules are ordered and the first match wins; the level is observe unless said otherwise. A matching rule hands the next matching item to the assignee, tells it through the delegation notice, and Today shows why. Requires assistant:write; an agent token is refused.

Change a standing delegation

Rename, enable or disable, reorder, change the match, the assignee, the level or the grants. Lowering the level to observe is the one-click kill switch of a rule. Requires assistant:write; an agent token is refused.

Delete a standing delegation

Removes the rule; the items it handed over come back to the owner, the receipts of what the assignee did stay. Requires assistant:write; an agent token is refused.

Try the standing delegations on sample facts

A dry run: which rule would take a matter with these facts (mailbox, key, sender, subject, labels, occurrences), and why. Nothing changes. Requires assistant:write; an agent token is refused.

Try an effect against a standing delegation's level and grants

A dry run of the validation order for an effect requested under the rule today: the level allows the kind; the grants allow the recipients, the volume (today's executed effects count), the schedule, the spend, the risk classes read off the matter; the required approver approved. Answers the status a plan would take (proposed, approved, escalated or rejected) with every check and why. Nothing changes. Requires assistant:write; an agent token is refused.

Read the task metrics

The seven numbers of the task layer on a rolling window (thirty days by default, window_days from 1 to 90), for the account and for each standing delegation: matters closed without the owner, the time from arrival to done, the plans executed as proposed, edited and rejected, the escalations per matter, the corrections after execution, the collisions, the model cost per matter. Read from the receipts, the plans, the escalations and the ledger; nothing is estimated. Requires assistant:read.

List the approvals queue

The plans waiting for the owner (proposed at draft, or held by a grant) and the questions the assignees asked, across the matters the reader may see. Answer through the work item's interactions: approve or reject a plan, choose an option or instruct on a question. Requires assistant:read. A matter made from authentication mail before such mail was kept out of the assistant is shown with its title, summary, ask and plan effects withheld from a reader without email:auth_secrets.

List the delegation suggestions

The standing delegations the assistant proposes: a matter that recurred at least three times in ninety days (the same organisation or sender) and was handled the same way every time (ignored, answered, closed, handed to one agent), with the rule prefilled. Open ones by default. Nothing is created until the owner accepts. Requires assistant:read; an agent token is refused.

Accept or dismiss a delegation suggestion

Accept: the suggestion closes and the prefilled rule comes back for the client to create (POST /api/assistant/rules). Dismiss: it closes and never comes back for the same matters and handling. Requires assistant:write; an agent token is refused.

List the grants attached to assignees

The grants attached to the owner's agents and members, on top of every rule that hands them matters; the stricter of the rule's and the assignee's applies. Requires assistant:read; an agent token is refused.

Set the grants of an assignee

Attach grants to an agent identity or a workspace member; they replace the assignee's previous grants and cap every rule that hands them matters. Requires assistant:write; an agent token is refused.

Remove the grants of an assignee

The assignee keeps only what each rule grants. Requires assistant:write; an agent token is refused.

Read a task envelope

The matter handed over, as the assignee needs it: the brief with the evidence, the facts, the delegation (assignee, rule, level, the effect kinds allowed, the effective grants), the plans open and recent, the lease. An agent token reads the matters handed to it and those of the mailboxes it operates; the owner reads their own. Requires assistant:read. A matter made from authentication mail before such mail was kept out of the assistant is shown with its title, summary, ask and plan effects withheld from a reader without email:auth_secrets.

Take or renew the lease on a task

Two assignees never work one matter: the lease names who works it until when (fifteen minutes by default, up to an hour). Taking it again renews it; another holder is refused with TASK_LEASED until the expiry. An effects request takes the lease on its own. Requires assistant:write.

Give the lease back

Releases the lease the caller holds; a lease held by another assignee is left alone. Requires assistant:write.

Ask for effects on a task

The assignee asks for one or more effects (reply, forward, label, snooze, resolve, note, request). The delegation's level decides the kinds allowed and the grants cap them: inside the grants at guarded_send or operate (and the inward kinds at triage) the effects run at once with their receipts; at draft they wait for the owner's approval; a failed grant escalates to the owner; a kind the level does not allow is refused. The owner's own request runs at once. The same idempotency key answers the first plan again. Requires assistant:write.

Stop and ask the owner

The assignee asks a question with the evidence and, when useful, the options it sees. The owner answers with the ordinary choose or instruct interactions on the decision this creates; the matter shows in Today as needing the owner, the lease is released, the task waits. Requires assistant:write.

Report on a task

What the assignee did and how it ended: done (the matter resolves, or waits when an answer is still expected), blocked (the owner is asked), or handed back (the owner takes over and the rule stays off this matter). Claims are reconciled with the receipts the platform wrote: a claim without a receipt is recorded as a claim, never as a fact. The lease is released. Requires assistant:write.

Read what the assistant established about a message

The knowledge the analyses of this message produced: claims (subject, predicate, value with type and currency, basis, confidence, validity, evidence), entities, commitments and expectations. Nothing is computed on the way: a message the pipeline never analysed answers analysed: false with reason (not_enabled when the mailbox is not in the assistant, not_analysed when the analysis has not happened yet). Requires assistant:read.

Extract the fields you need from a message with your own schema

One model call on the message text (subject, sender, body) with a caller JSON schema of objects and primitives (up to 8 KB, no references): answers data in that shape, confidence (0 to 1) and evidence_quotes (verbatim excerpts). Cached by (message, schema, instructions) so the same question costs one call (cached: true after). Gated by the account's model budget (429 when spent, 503 when the model route is off). Sign-in code mails answer 403 AUTH_MESSAGE. Bodies over 60,000 characters answer 413.

Get Mailzero assistant settings

Returns the assistant opt-in state, shadow/pause flags, consent version, privacy route, mailbox scope, and every mailbox you own. Requires the assistant:read scope.

{
  "enabled": false,
  "shadow_enabled": true,
  "paused": false,
  "mailbox_ids": [
    "mbx_123"
  ],
  "history_window_days": 30,
  "privacy_route": "private_cloud",
  "attachment_vision": false,
  "pipeline_version": "communication-analysis.v1",
  "consent": {
    "required_version": "mailzero-personal-ai.v1",
    "accepted_version": "mailzero-personal-ai.v1",
    "accepted_at": "2026-09-02T09:12:00.000Z"
  },
  "mailboxes": [
    {
      "id": "mbx_123",
      "slug": "hello",
      "domain": "example.com",
      "name": "Hello",
      "kind": "api",
      "address": "hello@example.com"
    }
  ]
}

Update Mailzero assistant settings

Explicitly enables, pauses, resumes, or scopes assistant processing. Sending mailbox_ids: [] disables every mailbox and cancels a running history import. Resuming requires the current consent version. Mail receipt remains independent. Requires the assistant:write scope.

{
  "ok": true,
  "enabled": true,
  "shadow_enabled": true,
  "paused": false,
  "mailbox_ids": [
    "mbx_123"
  ]
}

Consent to and start a background history import

Records the current explicit AI consent, enables shadow processing on the selected user-owned mailboxes, and creates a resumable background import of recent history. The client may close immediately and poll GET /api/assistant/backfill. Requires the assistant:write scope.

{
  "ok": true,
  "preview": {
    "mailbox_ids": [
      "mbx_123"
    ],
    "history_window_days": 30,
    "scanned": 0,
    "enqueued": 0,
    "capped": false,
    "background": true,
    "backfill_id": "bf_456"
  }
}

Get background history-import progress

Returns scanning/analysis phase, processed and total messages, percentage, adaptive ETA, pause state, and whether the app may close. Requires the assistant:read scope.

{
  "backfill": {
    "id": "bf_456",
    "status": "processing",
    "phase": "analysis",
    "paused": false,
    "processed": 12,
    "total": 40,
    "failed": 0,
    "percent": 30,
    "estimated_seconds_remaining": 240,
    "estimated_completion_at": "2026-09-02T09:20:00.000Z",
    "can_close_app": true,
    "started_at": "2026-09-02T09:12:00.000Z",
    "completed_at": null
  }
}

Retry failed history-import messages

Requeues terminal failures from the latest import for mailboxes that remain AI-enabled. Automatic retries have already been exhausted before a message appears here. Requires the assistant:write scope.

{
  "ok": true,
  "retried": 2
}

Get the grounded Today decision queue

Returns the versioned Now, Needs you, Waiting, Upcoming, and recent Handled projections with as_of, lag, coverage, and warnings. Every item links to its source message; nothing here sends mail. Requires the assistant:read scope. Authentication mail (sign-in codes, password resets, magic links) never becomes a matter and never reaches a model. A matter made from authentication mail before such mail was kept out of the assistant is shown with its title, summary, ask and plan effects withheld from a reader without email:auth_secrets.

{
  "type": "today",
  "as_of": "2026-09-02T09:15:00.000Z",
  "projection_lag_ms": 4200,
  "category": null,
  "categories": {
    "partner_inquiry": 1
  },
  "tag": null,
  "tags": {
    "lumenworks": 1
  },
  "sections": {
    "now": [
      {
        "id": "wi_789",
        "version": 3,
        "status": "needs_judgment",
        "title": "Investor update",
        "summary": "Paul needs the August metrics before his 16:00 partner call.",
        "category": "partner_inquiry",
        "tags": [
          "lumenworks"
        ],
        "proposed_tags": [],
        "mailbox": {
          "id": "mbx_123",
          "address": "hello@example.com",
          "name": "Hello"
        },
        "source": {
          "type": "domani-postgres",
          "conversation_id": "conv_1",
          "event_id": "msg_1",
          "revision": 1
        },
        "attention": {
          "level": "now",
          "reason": "Deadline today from a known investor",
          "confidence": "high",
          "deadline": "2026-09-02T16:00:00.000Z"
        },
        "decision": {
          "id": "dec_1",
          "version": 1,
          "status": "open",
          "question": "How do you want to answer Paul?",
          "options": [
            {
              "id": "opt_send",
              "label": "Send current metrics",
              "recommended": true
            },
            {
              "id": "opt_tomorrow",
              "label": "Ask for tomorrow"
            }
          ]
        }
      }
    ],
    "needs_you": [],
    "waiting": [],
    "upcoming": [],
    "handled": []
  }
}

Get one assistant Work item and exact current plan

Returns the grounded Work item, its open Decision and options, the exact current Action plan, open commitments and expectations, interactions, and receipts. Requires the assistant:read scope. A matter made from authentication mail before such mail was kept out of the assistant is shown with its title, summary, ask and plan effects withheld from a reader without email:auth_secrets.

Read the situation brief of a Work item

One document an agent reads before acting: the situation (status, attention, recurrence, sender), the story so far (every mail of it, analysed or not), the facts the analyses established (claims with value, basis and validity, and the entities), the open commitments and expectations with what is awaited from whom and since when, what already settled (closed loops and receipts), the current Decision with its options, a suggested next step (the Decision's recommended option when there is one, otherwise a rule: an overdue promise, an overdue expectation to chase, the sender's ask to answer), and the evidence messages. Deterministic and cheap: no model call. Agent tokens read the items of the mailboxes they operate and the items handed to them.

Read the situation brief for a correspondent

What to know before answering a person: the brief of their most recent active Work item across the mailboxes you may read (or one mailbox), the other items they are behind, and their last ten mails. brief is null when nothing was analysed from them yet.

Read the facts behind a Work item

The claims and entities merged from every analysis of the item (newest first wins), plus its stored commitments and expectations with their status. Agent tokens read the items of the mailboxes they operate and the items handed to them.

Mark a Work item as opened

Records that the owner opened this Work item at its current version, which clears its unread marker until the item changes again. Requires the assistant:write scope.

What the assistant learned about you

The quiet rules the assistant proposes after the same sender or organisation was ignored every time it came back, the mutes in force (a sender, a domain or a situation the assistant keeps out of Today), each with why it was set, and the tags confirmed once, each applied to the next matter of the same project without a question. Accept a quiet rule through the suggestions endpoint; forget a mute with the mutes endpoint, a tag with the tags endpoint.

Forget a mute

The next mail of that sender, domain or situation becomes an item again.

Forget a tag

Nothing is applied without a question any more: the next matter of that project proposes the tag again. The matters that carry it keep it.

Investigate a matter: what the registry and the links say

Reads, at that instant, the facts public infrastructure holds about the sender's domain (its registration date and registrar, its SPF and DMARC posture, whether it receives mail), where every link of the source message really goes (the redirects followed one hop at a time, the final host and its domain's facts), and what each attachment really is (its first bytes against the name and the declared type). Answers the dossier with the signals the facts add (a domain registered days ago, a link that lands elsewhere, a sender's domain that protects nothing, a program named as a document). No vendor, no account, nothing stored; a lookup that fails is a fact of its own.

Who is behind a matter: the organisation, the people involved, the history

Answers the sender card of a matter: the sender's organisation as the stored domain profile knows it (name, legal name, category, website, registration date, mail posture; null for a shared mail domain such as gmail.com or a domain never analysed, and never a live analysis), the people the story's messages carry in from, to and cc with their roles and whether they belong to the same organisation (the reader's own mailboxes left out), and the relationship: how much mail came from this address across the reader's mailboxes (counted up to 50), when first and last, the sender's other matters and the matters raised by colleagues at the same domain. Requires the assistant:read scope.

Record a fenced human Decision

Choose an option, give an instruction, take over, snooze, ignore, correct, report the trust verdict (phishing or legitimate), or approve or reject a waiting plan (an approved plan executes at once, with its receipts in the answer). The call is fenced by work_item_version and replayed idempotently by idempotency_key. Choosing or instructing prepares an exact draft that still goes through the normal reply flow; this endpoint never sends mail. Requires the assistant:write scope.

Get the exact action preview by opaque ID

Returns the exact reply identity, recipients, body, commitments, and side effects of a prepared Action plan, plus its expiry and source revision, so a client can show what will happen before the user sends through the existing reply endpoint with assistant_plan_id. Requires the assistant:read scope.

Get content-minimized assistant Activity

Lists recent interactions and receipts attributed to the caller without message bodies. Requires the assistant:read scope.

Export derived assistant data

Exports analyses, accepted claims, Decisions, interactions, receipts, and model usage as a JSON attachment. It never includes source email bodies or attachment bytes. Requires the assistant:write scope. It also needs email:auth_secrets (403 INSUFFICIENT_SCOPE otherwise): the derived state can hold what the assistant drew from authentication mail before such mail was kept out of it.

Delete assistant-derived data

Idempotently deletes derived intelligence, jobs, model usage, devices, imports, and settings while preserving source mail. Requires the assistant:write scope.

{
  "ok": true,
  "deleted": {
    "work_items": 12,
    "claims": 40,
    "entities": 9,
    "jobs": 52
  },
  "source_mail_deleted": false
}

Register a device for redacted Now alerts

Registers or rotates an encrypted push token for one app installation and environment. Only the native app calls this; it requires an active assistant and the assistant:write scope.

Revoke a device registration

Revokes every push registration of one installation, for example on sign-out. Requires the assistant:write scope.

Check email DNS health (MX, SPF, DMARC, DKIM)

Checks email DNS configuration for a domain: MX records, SPF, DMARC, and DKIM. Auto-detects the email provider from MX records (Google Workspace, Proton, Fastmail).

{
  "domain": "mysite.com",
  "provider": "google-workspace",
  "mx": {
    "configured": true,
    "records": [
      "1 aspmx.l.google.com",
      "5 alt1.aspmx.l.google.com"
    ]
  },
  "spf": {
    "configured": true,
    "value": "v=spf1 include:_spf.google.com ~all"
  },
  "dmarc": {
    "configured": true,
    "value": "v=DMARC1; p=quarantine; rua=mailto:dmarc@mysite.com"
  },
  "dkim": {
    "configured": true,
    "selectors": [
      "google"
    ]
  }
}

curl https://domani.run/api/domains/mysite.com/email/check \
  -H "Authorization: Bearer domani_sk_xxx"

Get owner-scoped email deliverability health

Separates deterministic authentication readiness, 30-day recipient-weighted delivery outcomes, account safety state, and measured provider placement. The readiness score is not an Inbox probability, and unmeasured placement is returned as not_tested.

curl https://domani.run/api/domains/mysite.com/email/deliverability \
  -H "Authorization: Bearer domani_sk_xxx"

Set up email on a domain

Pre-configure email DNS on a domain (optional). This is called automatically by create_mailbox when needed. Pass force=true to override existing email provider (Google Workspace, Fastmail, Proton).

Remove email from a domain

Remove email from a domain, delete all mailboxes and messages, and set emailEnabled to false. It changes mail for the whole domain, so a mailbox-confined token gets 403 MAILBOX_CONFINED.

Check email DNS status

Check email DNS verification status for a domain. Returns whether the domain is verified and ready, DNS record details, and mailbox count.

Create a mailbox on domani.run

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.

List all mailboxes

List every mailbox the acting principal can access across all domains, including workspace grants.

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.

List all mailboxes

List every mailbox the acting principal can access, including workspace grants. Same as GET /api/email.

Get mailbox details

Get details for a specific mailbox by its full email address (URL-encoded, e.g. hello%40mysite.com).

Update mailbox

Update a mailbox's display name, webhook URL, or forward-to email address by its full email address. Set to null to disable/clear.

Delete a mailbox

Delete a mailbox by its full email address. Requires confirm=true in body. Without confirm, returns a preview with message_count.

Send an email

Send an email from a mailbox identified by its full email address. The server runs a mandatory versioned policy first: objective safety failures are denied while reputation and content-quality findings are returned as warnings. For a collaborative threaded reply, pass the compose lease, observed reply_version, and a stable idempotency key; the server atomically rejects stale or double replies immediately before sending. Maximum 20 unique recipients per message. Rate limit: 100 recipients per hour per mailbox.

Preflight an outbound email

Run the exact versioned server-side policy used by the send endpoint without sending or consuming email quota. Public HTTPS authentication links on third-party domains are allowed with a reputation warning. Local/private URLs, non-HTTPS authentication links and executable attachments are blocked; bodies above 102 KB produce a clipping warning.

List emails

List emails in a canonical folder or virtual view. Defaults to Inbox. Folder location is independent from message direction and spam verdict. Authentication mail (OTPs / verification codes, password resets, magic links) is tagged security: "auth". Tokens without the email:auth_secrets scope see those messages with subject and body REDACTED (redacted: true) - metadata (from, date) stays visible. The subject, q and attachments filters match what the caller may read: without the scope such a message matches only on its redacted subject and body, so a query for a code it holds finds nothing.

Search mail by meaning and by words

Searches the mailboxes you may read, or one mailbox with mailbox. Hybrid by default: the message embedding (pgvector, cosine) and the weighted words index are fused by reciprocal rank with a small recency boost, in one statement; why tells which branch matched. Gmail operators in q: from: to: cc: subject: label: filename: mailbox: is:unread|read|starred|unstarred has:attachment in:inbox|archive|sent|spam|trash|anywhere after:2026/08/01 before: newer_than:7d older_than:2w (h/d/w/m/y), "a phrase", -word or -from: to exclude, a OR b. A query made of operators alone lists the matching messages newest first (why: filter). Sign-in codes and links, spam and system mail are never indexed; mailboxes listed in the assistant's search_opt_out_mailbox_ids are searched by words only. A token bound to an agent identity searches only the mailboxes its agent operates. Requires email:read. Without email:auth_secrets, inbound authentication mail is left out before ranking: no word, operator or filter matches it, so a search for a sign-in code finds nothing.

curl "https://domani.run/api/emails/search?q=facture+tucows+ao%C3%BBt&limit=5" \
  -H "Authorization: Bearer domani_sk_xxx"

Start connecting a Gmail inbox

Returns the Google consent URL bound to your account and to the import bound. Open it in a browser; after consent the inbox becomes a connected mailbox at its own address, the mail received after the bound is imported (default: the last 24 hours), and new mail follows as it arrives. Never the whole inbox: widen later with POST /api/emails/{address}/import. Requires email:write. Google OAuth must be configured on the server.

Start connecting an Outlook inbox

Returns the Microsoft consent URL bound to your account and to the import bound. Open it in a browser; after consent the inbox becomes a connected mailbox at its own address, the mail received after the bound is imported (default: the last 24 hours), and new mail follows as it arrives. Never the whole inbox: widen later with POST /api/emails/{address}/import. Requires email:write. Microsoft OAuth must be configured on the server.

List the ways an inbox can be connected

One row per provider (Gmail, Outlook, any inbox by forwarding, an address hosted here): how the connection starts (a consent screen, a forwarding rule, an address created), what the connection can do (read, or read and write), whether it imports older mail, and whether this server is set up for it. Show a connect button only when configured is true; reason names the missing variable for the operator. Requires email:read.

Connect an inbox by forwarding

Creates a connected mailbox at the inbox's own address and answers with a forwarding address on the platform's forwarding domain, with the steps for Gmail, Outlook and other providers. Add a forwarding rule at the provider; what arrives at that address is unwrapped (original sender, date, subject) and stored under the connected mailbox. Gmail asks the forwarding address to confirm: the code and the link appear on the connection. The first mail that comes back, or a probe (POST /api/emails/{address}/connector/verify), makes the connection active. Only new mail arrives this way; older mail cannot be imported. Requires email:write. The forwarding domain must be configured on the server.

Send a probe through the forwarding rule

Sends a mail to the connected inbox; when the forwarding rule brings it back to the forwarding address, the connection becomes active. Only for a connection by forwarding. Requires email:write.

Read the connection of a connected mailbox

Kind, status, the import bound, the sync phase (the import scan, then history), the import progress (scanned, copied, to analyse, analysed), the last sync and the last error. Requires email:read. The forwarding confirmation (Gmail's code and link) is authentication mail: without email:auth_secrets its code and url are null and it carries redacted: true. A mailbox-confined token finds only its own mailboxes (404 otherwise).

Disconnect a connected mailbox

Removes the person's own copies (messages, attachments, search rows, pending jobs) and the credential; keeps the mailbox row, the link marked disconnected, and what agents did (receipts). Only a connected mailbox can be disconnected. Requires email:write.

Import older mail of a connected mailbox

Widens the import to an earlier date: a new import run copies the mail between the new bound and the current one, in arrival order, under its own cost cap. Refused while an import scan is still running. Requires email:write.

Search one mailbox by meaning and by words

The same search as GET /api/emails/search, restricted to this mailbox. Requires email:read. Without email:auth_secrets, inbound authentication mail is left out before ranking: no word, operator or filter matches it, so a search for a sign-in code finds nothing.

List the conversations of a mailbox

Messages grouped the way mail clients group them: a reply joins the thread of the message it answers (In-Reply-To, then the References chain), mail without usable headers joins the most recent thread with the same subject and a correspondent in common within thirty days, everything else starts a thread whose id is its first message's id. Threads are ordered by last activity; trash and spam never take part unless named as the folder. folder=inbox|archive|sent keeps the threads that have a message there but still counts the whole conversation.

Read one conversation, oldest message first

Every message of the thread (trash included, so nothing is missing from the story) with its text, oldest first, plus the participants and the unread count. Auth mail is redacted the way message reads are.

Stream mailbox events (server-sent events)

Answers text/event-stream. Without a cursor the stream starts at the present; with since (a cursor from /api/email/changes or the id of any earlier event) it first replays every change after that point, then follows the mailbox journal live: each frame carries the change's type as the event name (message.received, message.updated, message.deleted, message.moved, message.status, mailbox.resync_required, assistant.item.delegated, assistant.item.recalled, ...), the change as JSON data with its resumable cursor, and that same cursor as the frame id. The first frame is ready with the cursor to resume from; a keep-alive comment arrives every 20 seconds; the connection closes after about 5 minutes with a close frame and a retry: hint. Reconnect with Last-Event-ID (or since) to resume with no gap and no duplicate. Agent tokens are confined to the mailboxes the agent operates. An entry about a work item made from authentication mail carries its title and ask redacted for a token without email:auth_secrets.

List email folders and counts

Return server-derived counts for system folders and virtual views, plus lifecycle capabilities for the mailbox backend.

Apply a lifecycle action to messages

Move, restore, mark read, star, or permanently delete up to 100 explicit message IDs. Moving to Trash is reversible. Permanent deletion requires email:delete and only accepts messages already in Trash. Every response is a durable operation receipt with one result per requested ID. Supply a stable key in the standard Idempotency-Key header or legacy idempotency_key JSON field and reuse it after timeouts; an exact retry returns the stored receipt without another mutation. If both forms are supplied, they must match. Reusing a key with a different request returns 409. When omitted, the server creates a key and returns it in the body and Idempotency-Key header. Returns 207 when only part of the batch succeeds.

Mark messages as read or unread

Compatibility endpoint for retry-safe read-state updates. Returns the canonical durable per-item operation receipt plus the legacy count. Supply and reuse the Idempotency-Key header or compatibility idempotency_key field after timeouts.

Bulk delete messages

Compatibility endpoint that retry-safely moves messages to Trash. Returns the canonical durable per-item operation receipt plus the legacy count. Supply and reuse the Idempotency-Key header or compatibility idempotency_key field after timeouts.

Get a message

Fetch a single message by ID from a mailbox identified by its full email address. Messages classified as authentication mail (OTP, password reset, magic link) come back with subject/body redacted unless the token has the email:auth_secrets scope.

Delete a message

Move a message to Trash. This is reversible. Use the lifecycle action with delete_permanently and an email:delete token to erase a message already in Trash.

Reply to a message

Reply to a message in a mailbox identified by its full email address. Threading headers are auto-populated, and the original is quoted under the reply as mail clients do (attribution line in the account's language, > lines in text, a gmail_quote block in HTML) unless quote is false. Collaborative clients should pass the compose lease, observed reply_version, and a stable idempotency key; the server atomically rejects a stale/double reply immediately before sending.

Forward a message

Forward a message from a mailbox identified by its full email address to another recipient. Forwarding authentication mail (OTP, password reset, magic link) requires the email:auth_secrets scope - it would exfiltrate the secret.

Get mailbox avatar info

Returns the Gravatar URL (if set) and signup link for a mailbox identified by its full email address.

Get mailbox webhook config

Returns the webhook URL, signing secret, configured auth header names, and status for a mailbox. Header values are never returned.

Set mailbox webhook

Configure the HTTPS destination for HMAC-signed mailbox events: inbound mail by default, plus (opt-in via events) the delivery verdict on mail sent FROM the mailbox - a bounce reaches the sender seconds after the send was accepted, instead of living only in the message trail. Live inbound deliveries are stored durably, attempted immediately, and retried up to three times. Each attempt includes X-Domani-Delivery-Attempt starting at 1. Optional Authorization or X-API-Key values are encrypted and never returned; human operators should submit them outside model context through the CLI environment-variable options.

curl -X PUT https://domani.run/api/emails/agent%40example.com/webhook \
  -H "Authorization: Bearer domani_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://agent.example/webhook","events":["email.received","email.bounced","email.delivered"]}'

Remove mailbox webhook

Remove the webhook URL and signing secret from a mailbox. Inbound emails will only be stored.

Rotate webhook signing secret

Regenerate the HMAC-SHA256 signing secret for a mailbox webhook. The old secret is immediately invalidated.

Test mailbox webhook

Send one signed test payload to the mailbox webhook URL. Returns HTTP status and whether delivery succeeded. Tests are not retried; live inbound deliveries are retried up to three times.

List mailbox aliases

List all alias addresses that deliver into a mailbox. Aliases let several addresses (sales@, hello@, contact@) share one inbox without using a mailbox slot.

Add a mailbox alias

Add an alias address that delivers into this mailbox, without using a mailbox slot. The alias must be on the same domain as the mailbox. Provide a bare slug ("sales") or a full address ("sales@mysite.com").

Remove a mailbox alias

Remove an alias from a mailbox. Email to that address stops being delivered.

Get mail client settings (hosted)

Get IMAP/SMTP connection settings for a hosted mailbox, to configure Apple Mail, Thunderbird, or any mail client. Username is the full address; the password is an app password (create one with POST /api/emails/{address}/credentials). Hosted mailboxes only.

List app passwords (hosted)

List the app passwords for a hosted mailbox. Secrets are shown only once at creation; this returns labels and metadata only. Hosted mailboxes only.

Create an app password (hosted)

Create an app password for a hosted mailbox, used as the password in a mail client (IMAP/SMTP). The secret is returned once - store it now. Hosted mailboxes only.

Revoke an app password (hosted)

Revoke an app password. Any mail client using it stops connecting immediately. Hosted mailboxes only.

Flag a message for a human

Escalate a message to the account's human (or clear the flag with clear=true). Sets needs_human on the message, holds its conversation in status needs_human, and fires the email.escalated webhook + in-app notification. The product primitive behind 'answer the easy ones, stop on the one the human must decide'.

Set a follow-up reminder

Set (or clear with clear=true) a one-shot follow-up reminder on a message. When remind_at arrives and the message is still unanswered (inbound: no reply sent; outbound: no inbound reply received), email.reminder_due fires as a webhook + in-app notification and the reminder clears itself.

List contacts

The account's address book, auto-fed by mail traffic: correspondents, message counts, last activity, and notes. Most recently active first by default (order=recent), for display: a contact that gets new mail during a paged scan moves ahead of the cursor, so that scan can skip it. To sync the whole book, pass order=created: oldest first by creation time then id, a key that never changes, so every contact that exists for the whole scan comes back exactly once and contacts created meanwhile come at the end. A cursor only continues the order it came from (400 INVALID_CURSOR otherwise). Aggregates data from every mailbox, so mailbox-confined tokens are denied (400 MAILBOX_CONFINED).

Create or update a contact

Save a contact: set a display name and attach notes ('prefers short emails', 'decision maker at Acme'). Mail traffic keeps feeding message counts either way.

Delete a contact

Remove a contact from the address book. Mail traffic will recreate it as an auto contact if they write again.

List inbound mail rules

List a mailbox's inbound filtering rules, in the priority order they are applied (first match wins).

Add an inbound mail rule

Add a rule that runs on inbound messages matching a field (from/to/subject/body). Actions: drop, mark_read, forward (action_arg = address), webhook_only (skip forward-to), label (action_arg = label). Rules apply in priority order (lower first); first match wins.

Remove an inbound mail rule

Remove an inbound filtering rule from a mailbox.

Set domain catch-all

Route every email sent to an unmatched address on the domain into a designated mailbox. Anything that does not match a mailbox, subaddress, or alias lands in the catch-all. The mailbox must already exist on the domain. It changes mail for the whole domain, so a mailbox-confined token gets 403 MAILBOX_CONFINED.

Clear domain catch-all

Remove the catch-all on a domain. Email to unmatched addresses will be dropped again. It changes mail for the whole domain, so a mailbox-confined token gets 403 MAILBOX_CONFINED.

Incrementally synchronize one mailbox

Call without a cursor to capture a baseline before a bounded full snapshot. Then pass next_cursor to replay mutations that happened during and after that snapshot. Cursors are opaque, signed, mailbox-bound, and expire after 30 days. Push notifications are only invalidation hints; this journal is the durable recovery source. An entry about a work item made from authentication mail carries its title and ask redacted for a token without email:auth_secrets.

List suppressed addresses

List addresses on your suppression list - hard bounces and complaints (ingested automatically from delivery events) plus manual entries. Sends to these addresses are skipped. Cursor-paginated.

Add a suppression

Manually add an address to your suppression list so future sends skip it. Hard bounces and complaints are added automatically; use this for addresses you want to stop emailing. Idempotent.

Remove a suppression

Remove an address from your suppression list so you can email it again (e.g. after the recipient fixed their mailbox).

Request a workspace ownership transfer

Owner-only. Sends a 48-hour acceptance link to an existing member. Nothing moves until that authenticated member accepts.

Revoke a pending ownership transfer

Accept workspace ownership

Target-only. Atomically transfers the workspace, scoped domains and mailboxes; the previous owner becomes an admin and the existing payer remains unchanged.

Create a new account

Starts creating a new account (or signs an existing one in) by emailing a sign-in link; no API key is returned here. A person clicking that link in a browser lands on the dashboard already signed in. A CLI or agent without a browser session should use the device-login flow instead (POST /api/auth/cli then poll GET /api/auth/cli/poll), which emails the same approval and hands back an API key once approved - the response's next_steps says so. Pass a ref code to permanently link the new user to a referrer - the referrer earns a commission on all future domain purchases by this user.

{
  "ok": true,
  "verification_required": true,
  "message": "Check your email for a sign-in link to finish creating your account.",
  "hint": "A human must open that email and click the link in a browser to finish verification; no API key is issued yet.",
  "next_steps": [
    "If a person can click the email link, nothing else to do: they land on the dashboard already signed in.",
    "If you are a CLI or agent without a browser session, start a device-login flow instead: POST /api/auth/cli, then poll GET /api/auth/cli/poll?code=... until status is \"complete\" - the same email approves it and hands back an API key, no browser needed on your side."
  ]
}

curl -X POST https://domani.run/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "dev@example.com"}'

Send a magic link sign-in email

Sends a sign-in link to the provided email. If the user doesn't exist, creates an account first. The magic link redirects to the dashboard with auth credentials. For programmatic API access, use POST /api/auth/register to get an API key directly.

{
  "ok": true,
  "message": "Check your email for a sign-in link."
}

curl -X POST https://domani.run/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "dev@example.com"}'

Verify a magic link token

Validates the magic link token and redirects to the dashboard with auth credentials. Used by the magic link email - not typically called by agents directly. Agents should use POST /api/auth/register instead.

Mint a one-time cross-host sign-in code

Browser-only: lets a signed-in person on domani.run or mailzero.run resume their session on the other host without a second magic link. Returns a URL whose fragment carries a 60-second, single-use, host-bound code; the code is never logged or sent in a query string. Not useful outside a browser session, so it is not exposed as an agent tool.

{
  "url": "https://mailzero.run/auth/handoff#code=xxx&next=%2Finbox"
}

Redeem a one-time cross-host sign-in code

Browser-only: called by the /auth/handoff page on the target host to exchange the code from the URL fragment for a session, exactly like GET /api/auth/verify does for a magic link. The code must match the Host this request arrived on. Not an agent tool.

{
  "ok": true,
  "next": "/inbox"
}

Get current account details

Returns the authenticated user's account information including email, payment status, contact info status, referral code, and usage counts. Agents should call this after authentication to check has_payment_method and has_contact before attempting purchases.

{
  "id": "cm5abc123",
  "email": "dev@example.com",
  "plan": "agent",
  "workspace_plans": [
    "mail_pro"
  ],
  "has_payment_method": true,
  "has_contact": true,
  "referral_code": "x7k9m2",
  "referral_rate": 20,
  "domain_count": 3,
  "token_count": 2,
  "created_at": "2025-01-15T10:30:00.000Z"
}

curl https://domani.run/api/me \
  -H "Authorization: Bearer domani_sk_xxx"

Update account preferences

Update the authenticated user's preferred payment method and/or BCP 47 locale. API responses remain structured and are not translated.

Delete account (blocked while domains are held)

Permanently delete the authenticated user's account, tokens, webhooks, mailboxes, and other application data. Registered domains are NOT deleted with the account: the request fails with 409 HAS_DOMAINS until every domain is transferred out. This action cannot be undone.

Get truthful activation state and recommended next actions

Returns server-derived product milestones and capability-aware next actions. Token creation, token use, page views, and client checklist state are deliberately excluded.

curl https://domani.run/api/me/activation \
  -H "Authorization: Bearer domani_sk_xxx"

Dismiss or restore first-run guidance

Stores presentation preference only. It cannot complete a product milestone.

Get registrant contact info

Returns the authenticated user's WHOIS registrant contact information. Optional for purchases (until it is set, Domani's contact holds new domains on the user's behalf), required before transferring a domain in.

{
  "has_contact": true,
  "contact": {
    "first_name": "Jane",
    "last_name": "Doe",
    "address1": "123 Main St",
    "city": "New York",
    "state": "NY",
    "postal_code": "10001",
    "country": "US",
    "phone": "+1.2125551234",
    "email": "jane@example.com"
  }
}

curl https://domani.run/api/me/contact \
  -H "Authorization: Bearer domani_sk_xxx"

Set registrant contact info

Set or update your WHOIS registrant contact information. Optional for purchases, required before transferring a domain in. It becomes the registrant and billing contact of your domains: until it is set, Domani's contact holds them on your behalf. When updated, the new contact is pushed to all your active domains at registrars that support contact updates, which makes you their registrant; the registrar may email you to confirm it within 15 days.

curl -X PUT https://domani.run/api/me/contact \
  -H "Authorization: Bearer domani_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"first_name":"Jane","last_name":"Doe","address1":"123 Main St","city":"New York","state":"NY","postal_code":"10001","country":"US","phone":"+1.2125551234","email":"jane@example.com"}'

Resend contact email verification

Resend the verification email for the account's contact email address. Rate limited to once per 15 minutes per email.

List signed-in devices

Every browser, mobile app and terminal signed in to the account, the caller's own session first (current). Each sign-in opens its own session, so signing in on a new device never signs another one out. Location is where the device signed in from (country and city from its IP), absent when unknown. API keys are not sessions: list them with GET /api/tokens.

{
  "sessions": [
    {
      "id": "cm5ses123",
      "current": true,
      "kind": "web",
      "product": "domani",
      "device": {
        "type": "desktop",
        "os": "macOS",
        "browser": "Chrome"
      },
      "location": {
        "country": "FR",
        "city": "Paris"
      },
      "signed_in_at": "2026-10-01T10:00:00.000Z",
      "last_active_at": "2026-10-18T09:12:00.000Z"
    },
    {
      "id": "cm5ses456",
      "current": false,
      "kind": "mobile",
      "product": null,
      "device": {
        "type": "mobile",
        "os": "iOS",
        "browser": null
      },
      "location": {
        "country": "FR",
        "city": "Lyon"
      },
      "signed_in_at": "2026-09-20T18:30:00.000Z",
      "last_active_at": "2026-10-17T21:04:00.000Z"
    }
  ],
  "hint": "Sign a device out with DELETE /api/sessions/{id}, or every device but this one with DELETE /api/sessions."
}

curl https://domani.run/api/sessions \
  -H "Authorization: Bearer domani_sk_xxx"

Sign out every other device

Signs out every session of the account except the one making the request. Those devices are asked to sign in again on their next request. API keys are unchanged.

{
  "revoked": 2,
  "hint": "Every other device is signed out. API keys are unchanged."
}

curl -X DELETE https://domani.run/api/sessions \
  -H "Authorization: Bearer domani_sk_xxx"

Sign out a device

Signs one session out. current names the session making the request (signing out needs no scope); any other session needs tokens:write.

{
  "success": true,
  "current": false,
  "hint": "That device is signed out and will be asked to sign in again."
}

curl -X DELETE https://domani.run/api/sessions/cm5ses456 \
  -H "Authorization: Bearer domani_sk_xxx"

List the API tokens of an agent identity

The tokens bound to this agent identity (masked keys, scopes, mailbox confinement, last use). An agent-bound token is that agent's view on every assistant and mail surface.

Give an agent its own API key in one call

Creates a token bound to this agent identity, confined to the mailboxes the agent operates, with the minimal scopes an agent needs (assistant:read, assistant:write, email:read, email:write). With that key the agent reads only its own Today, its mailboxes and the items handed to it; naming another agent answers 403 and owner-only routes (settings, backfill, export) refuse it. The full key is returned only in this response. Requires tokens:write. An agent that operates no mailbox gets no mail scopes by default, and asking for them answers 400 AGENT_MAILBOXES_REQUIRED: a key with no mailboxes would reach every mailbox of the account.

curl -X POST https://domani.run/api/agents/identity/dave/tokens \
  -H "Authorization: Bearer domani_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "Dave on the laptop"}'

Revoke an agent's API token

Revokes a token bound to this agent identity. It stops working immediately. Requires tokens:write.

List your API tokens

Returns all API tokens for the authenticated user. Keys are masked for security (first 12 + last 4 characters visible). Use this to audit active tokens.

{
  "tokens": [
    {
      "id": "cm5abc123",
      "name": "Default",
      "key": "domani_sk_a...wxyz",
      "lastUsed": "2025-02-18T10:30:00.000Z",
      "expiresAt": null,
      "expired": false,
      "scopes": [
        "*"
      ],
      "createdAt": "2025-01-15T10:30:00.000Z",
      "max_per_tx": null,
      "max_per_month": null,
      "spent_this_month": 0,
      "parent_token_id": null,
      "agent_identity": null
    },
    {
      "id": "cm5def456",
      "name": "CI/CD",
      "key": "domani_sk_b...vwxy",
      "lastUsed": null,
      "expiresAt": "2025-05-01T14:00:00.000Z",
      "expired": false,
      "scopes": [
        "domains:read",
        "domains:write"
      ],
      "createdAt": "2025-02-01T14:00:00.000Z"
    }
  ]
}

curl https://domani.run/api/tokens \
  -H "Authorization: Bearer domani_sk_xxx"

Create a new API token

Creates a new API token. The full key is returned only in this response - store it securely. You can create multiple tokens to separate access for different applications.

{
  "id": "cm5ghi789",
  "name": "CI/CD Pipeline",
  "key": "domani_sk_x1Y2z3A4b5C6d7E8f9G0hIjK",
  "expiresAt": "2025-03-20T10:30:00.000Z",
  "scopes": [
    "domains:read",
    "domains:write"
  ],
  "createdAt": "2025-02-18T10:30:00.000Z",
  "max_per_tx": 25,
  "max_per_month": 100,
  "mailbox_ids": [],
  "http_route_policy": null
}

curl -X POST https://domani.run/api/tokens \
  -H "Authorization: Bearer domani_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "CI/CD Pipeline"}'

Revoke an API token

Permanently revokes an API token. Any applications using this token will immediately lose access. This action cannot be undone.

{
  "success": true
}

curl -X DELETE https://domani.run/api/tokens/cm5abc123 \
  -H "Authorization: Bearer domani_sk_xxx"

List security audit events

Returns the account's security audit trail, newest first: token lifecycle (created, revoked, escalation attempts), spend-cap and max_price denials, charges, payout requests, and blocked account deletions. Use it to monitor what your agents' tokens are doing.

{
  "events": [
    {
      "id": "evt1",
      "tokenId": "cm5abc123",
      "type": "purchase.charged",
      "targetType": "domain",
      "targetId": "mysite.com",
      "metadata": {
        "amountCents": 1450,
        "operation": "buy",
        "method": "card"
      },
      "createdAt": "2026-07-11T10:00:00.000Z"
    },
    {
      "id": "evt2",
      "tokenId": "cm5abc123",
      "type": "purchase.denied_cap",
      "targetType": "domain",
      "targetId": "expensive.ai",
      "metadata": {
        "amountCents": 8470
      },
      "createdAt": "2026-07-11T09:58:00.000Z"
    }
  ],
  "next_cursor": null,
  "hint": "Security-relevant events for this account."
}

curl "https://domani.run/api/audit?limit=50" \
  -H "Authorization: Bearer domani_sk_xxx"

List webhooks

List all webhook endpoints configured for your account. Returns URL, subscribed events, and active status for each webhook. Secrets are never returned after creation. A mailbox-confined token sees only the webhooks confined to its own mailboxes.

{
  "webhooks": [
    {
      "id": "cm5wh001",
      "url": "https://example.com/webhooks/domani",
      "events": [
        "domain.purchased",
        "dns.updated"
      ],
      "active": true,
      "created_at": "2026-02-25T10:00:00.000Z"
    }
  ],
  "hint": "1 webhook(s)."
}

curl https://domani.run/api/webhooks \
  -H "Authorization: Bearer domani_sk_xxx"

Create webhook

Register a new HTTPS webhook endpoint. Optional Authorization or X-API-Key values are encrypted at rest and included in every delivery. The signing secret is returned only once. Maximum 5 webhooks per account. A webhook created by a mailbox-confined token is confined to the same mailboxes: it receives no mail event from any other mailbox.

{
  "id": "cm5wh001",
  "url": "https://example.com/webhooks/domani",
  "events": [
    "domain.purchased",
    "dns.updated"
  ],
  "secret": "whsec_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345",
  "active": true,
  "created_at": "2026-02-25T10:00:00.000Z",
  "hint": "Webhook created. Save the secret - it won't be shown again. Use it to verify incoming payloads with HMAC-SHA256."
}

curl -X POST https://domani.run/api/webhooks \
  -H "Authorization: Bearer domani_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hook","events":["domain.purchased","dns.updated"],"headers":{"Authorization":"Bearer sender_key_xxx"}}'

Update webhook

Update a webhook's URL, subscribed events, active status, or encrypted auth headers. Send only the fields you want to change. A mailbox-confined token reaches only the webhooks confined to its own mailboxes (404 otherwise).

Delete webhook

Delete a webhook endpoint. All pending deliveries will be cancelled. This cannot be undone. A mailbox-confined token reaches only the webhooks confined to its own mailboxes (404 otherwise).

List webhook deliveries

Get recent delivery attempts for a webhook. Shows event type, HTTP status, number of attempts, and any errors. Useful for debugging failed deliveries. A mailbox-confined token reaches only the webhooks confined to its own mailboxes (404 otherwise).

{
  "deliveries": [
    {
      "id": "cm5del001",
      "replay_of_id": null,
      "event_type": "domain.purchased",
      "status": "delivered",
      "http_status": 200,
      "attempts": 1,
      "last_error": null,
      "created_at": "2026-02-25T10:05:00.000Z"
    }
  ],
  "hint": "1 delivery(ies) for this webhook."
}

Replay a webhook delivery

Clone and immediately redeliver an immutable webhook event. The event payload and event ID stay identical; the HMAC signature receives a fresh timestamp. A required idempotency key guarantees caller retries never send twice. A mailbox-confined token reaches only the webhooks confined to its own mailboxes (404 otherwise). One exception to an identical payload: a subject copied from authentication mail is sent redacted, since the webhook's URL may have changed since the first delivery.

List webhook event types

List all available webhook event types with descriptions. No authentication required.

{
  "events": [
    {
      "type": "domain.purchased",
      "description": "A new domain was successfully registered"
    },
    {
      "type": "dns.updated",
      "description": "DNS records were changed for a domain"
    },
    {
      "type": "transfer.completed",
      "description": "A domain transfer completed successfully"
    }
  ]
}

curl https://domani.run/api/webhooks/events

List notifications

List your in-app notifications with cursor-based pagination. Includes deal events, listing updates, and system alerts. Requires notifications:read scope. A notification written before mail subjects were redacted at write time reads with the subject of authentication mail redacted, in body and data.subject, for a token without email:auth_secrets.

Get unread notification count

Lightweight endpoint for polling unread notification count. Requires notifications:read scope.

{
  "unread_count": 3
}

Mark notification as read

Mark a single notification as read. Requires notifications:read scope.

Mark all notifications as read

Mark all unread notifications as read. Requires notifications:read scope.

Get notification preferences

Returns the user's notification preferences for each category and channel (in_app, email). Missing preferences default to enabled. Requires notifications:read scope.

Update notification preferences

Update notification preferences for specific categories and channels. Requires notifications:read scope.