run.domani/domani

Official119 toolsLive

by gwendall · TypeScript

Internet identity for AI agents: register or broker domains, email, DNS - pay by card or USDC.

run.domani/domani — Model Context Protocol (MCP) Server

The run.domani/domani MCP server provides internet identity capabilities for AI agents, covering domain registration and brokering, email mailbox creation, DNS management, and email send/receive. It supports multiple access paths, including a web dashboard and terminal/CLI workflows, and supports payment by card or USDC.

🛠️ Key Features

Register or broker domains
Manage DNS
Create mailboxes
Send and receive email
Access via Web (dashboard with inbox and DNS editor) and CLI/terminal
Payment options: card or USDC

🚀 Use Cases

Domain and DNS provisioning for humans and AI agents
Email setup and administration for agent-driven workflows
Using a dashboard or terminal to compose, reply, manage threads, and operate DNS

⚡ Developer Benefits

One account with multiple interfaces (web and CLI/terminal)
Tooling available from your terminal or an agent, and via the web UI

Captured live from the server via tools/list.

get_account

Get your account details, payment status, contact info status (has_contact), and referral code. Contact info must be set before purchasing domains.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {}
}

search

Check availability and price for one or more domains. Pass full domain names (e.g. mysite.com). For bulk TLD search, pass an array like ["myapp.com", "myapp.io", "myapp.dev"]. Uses RDAP + retail pricing.

Parameters5

domains	array	required	Full domain names to check, e.g. ["myapp.com", "myapp.io"]
max_price	number	optional	Maximum price in USD to filter results
sort	string	optional	Sort results by price or TLD name (default: price)
order	string	optional	Sort order (default: asc)
source	string	optional	Filter results: 'all' (default), 'primary' (new registrations only), 'secondary' (marketplace listings only). Use source='secondary' with domains=['*'] to browse all marketplace listings.

Raw schema

{
  "type": "object",
  "properties": {
    "domains": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Full domain names to check, e.g. [\"myapp.com\", \"myapp.io\"]"
    },
    "max_price": {
      "description": "Maximum price in USD to filter results",
      "type": "number"
    },
    "sort": {
      "description": "Sort results by price or TLD name (default: price)",
      "type": "string",
      "enum": [
        "price",
        "tld"
      ]
    },
    "order": {
      "description": "Sort order (default: asc)",
      "type": "string",
      "enum": [
        "asc",
        "desc"
      ]
    },
    "source": {
      "description": "Filter results: 'all' (default), 'primary' (new registrations only), 'secondary' (marketplace listings only). Use source='secondary' with domains=['*'] to browse all marketplace listings.",
      "type": "string",
      "enum": [
        "all",
        "primary",
        "secondary"
      ]
    }
  },
  "required": [
    "domains"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

suggest_domains

AI-powered domain suggestions. Given a project description, generates full domain names with creative TLDs (e.g. codebuddy.dev, wavify.fm), checks availability, and returns only available domains with pricing.

Parameters6

prompt	string	required	Project description or keywords, e.g. 'AI coding assistant'
count	number	optional	Number of suggestions to return (default 10)
exclude	array	optional	Domains to exclude from suggestions (e.g. from previous calls)
tlds	array	optional	Preferred TLDs without dots (e.g. ['com', 'dev']). Results will prioritize these.
style	string	optional	Name style: 'single' (one word), 'creative' (evocative/metaphorical single word), 'short' (3-6 chars), 'brandable' (invented names), 'keyword' (descriptive)
lang	string	optional	Language/cultural inspiration: names will draw from this language's words, aesthetics, and culture

Raw schema

{
  "type": "object",
  "properties": {
    "prompt": {
      "type": "string",
      "minLength": 3,
      "description": "Project description or keywords, e.g. 'AI coding assistant'"
    },
    "count": {
      "description": "Number of suggestions to return (default 10)",
      "type": "number",
      "minimum": 1,
      "maximum": 20
    },
    "exclude": {
      "description": "Domains to exclude from suggestions (e.g. from previous calls)",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "tlds": {
      "description": "Preferred TLDs without dots (e.g. ['com', 'dev']). Results will prioritize these.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "style": {
      "description": "Name style: 'single' (one word), 'creative' (evocative/metaphorical single word), 'short' (3-6 chars), 'brandable' (invented names), 'keyword' (descriptive)",
      "type": "string",
      "enum": [
        "single",
        "creative",
        "short",
        "brandable",
        "keyword"
      ]
    },
    "lang": {
      "description": "Language/cultural inspiration: names will draw from this language's words, aesthetics, and culture",
      "type": "string",
      "enum": [
        "japanese",
        "spanish",
        "french",
        "italian",
        "latin",
        "nordic",
        "arabic",
        "sanskrit"
      ]
    }
  },
  "required": [
    "prompt"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

list_tlds

List all available TLDs with registration and renewal pricing

Parameters7

max_price	number	optional	Maximum registration price in USD
min_price	number	optional	Minimum registration price in USD
sort	string	optional	Sort field. Defaults to tld
order	string	optional	Sort order (default: asc)
search	string	optional	Filter TLDs containing this string
limit	number	optional	Max results to return
offset	number	optional	Pagination offset

Raw schema

{
  "type": "object",
  "properties": {
    "max_price": {
      "description": "Maximum registration price in USD",
      "type": "number"
    },
    "min_price": {
      "description": "Minimum registration price in USD",
      "type": "number"
    },
    "sort": {
      "description": "Sort field. Defaults to tld",
      "type": "string",
      "enum": [
        "tld",
        "price",
        "renewal"
      ]
    },
    "order": {
      "description": "Sort order (default: asc)",
      "type": "string",
      "enum": [
        "asc",
        "desc"
      ]
    },
    "search": {
      "description": "Filter TLDs containing this string",
      "type": "string"
    },
    "limit": {
      "description": "Max results to return",
      "type": "number"
    },
    "offset": {
      "description": "Pagination offset",
      "type": "number"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

dns_check

Fast DNS-based domain existence check. Tests if a name is taken across many TLDs at once (faster than search, no pricing). Returns 'taken' (definitely registered) and 'candidates' (potentially available). Use this to narrow down before calling search for pricing. Use preset: 'extended' to check 30+ creative/exotic TLDs when basic ones are all taken.

Parameters3

name	string	required	Domain name without TLD, e.g. 'myapp'
tlds	array	optional	TLDs to check, e.g. ['com', 'dev', 'ai', 'io']. Optional if preset is provided.
preset	string	optional	Use a curated TLD preset: 'basic' (10 common TLDs) or 'extended' (30+ including creative/exotic TLDs). Merged with explicit tlds if both provided. Defaults to 'basic' when tlds is omitted.

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "description": "Domain name without TLD, e.g. 'myapp'"
    },
    "tlds": {
      "description": "TLDs to check, e.g. ['com', 'dev', 'ai', 'io']. Optional if preset is provided.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "preset": {
      "description": "Use a curated TLD preset: 'basic' (10 common TLDs) or 'extended' (30+ including creative/exotic TLDs). Merged with explicit tlds if both provided. Defaults to 'basic' when tlds is omitted.",
      "type": "string",
      "enum": [
        "basic",
        "extended"
      ]
    }
  },
  "required": [
    "name"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

buy_domain

Purchase one or more domains. Always confirm with the user before calling. Accepts a single domain or an array of up to 10 (card only for bulk). If the user wants to pay with crypto/USDC: call with payment_method: 'usdc' - you'll get a 402 with a wallet address and amount. Tell the user to send that amount in USDC, then once they give you the tx hash, retry with payment_tx and payment_chain. Don't explain protocol details to the user - just tell them the address, amount, and chain.

Parameters7

domain	string	optional	Single domain to purchase, e.g. mysite.com
domains	array	optional	Array of domains to purchase, e.g. ["a.com", "b.dev"]. Max 10.
payment_method	string	optional	Payment method: 'card' to charge card on file, 'usdc' to pay with USDC. Overrides the user's default preference for this request.
payment_tx	string	optional	Transaction hash of a USDC payment already sent on-chain. Required for step 2 of USDC flow.
payment_chain	string	optional	Chain the USDC payment was sent on. Required with payment_tx.
years	integer	optional	Number of years to register (1-10, default 1). Price is multiplied by years.
max_price	number	optional	Ceiling in USD for the total charge. If the real price is above it, the purchase fails with PRICE_ABOVE_MAX and nothing is charged. Set it from the price the user approved.

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "description": "Single domain to purchase, e.g. mysite.com",
      "type": "string"
    },
    "domains": {
      "description": "Array of domains to purchase, e.g. [\"a.com\", \"b.dev\"]. Max 10.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "payment_method": {
      "description": "Payment method: 'card' to charge card on file, 'usdc' to pay with USDC. Overrides the user's default preference for this request.",
      "type": "string",
      "enum": [
        "card",
        "usdc"
      ]
    },
    "payment_tx": {
      "description": "Transaction hash of a USDC payment already sent on-chain. Required for step 2 of USDC flow.",
      "type": "string"
    },
    "payment_chain": {
      "description": "Chain the USDC payment was sent on. Required with payment_tx.",
      "type": "string",
      "enum": [
        "base",
        "ethereum"
      ]
    },
    "years": {
      "description": "Number of years to register (1-10, default 1). Price is multiplied by years.",
      "type": "integer",
      "minimum": 1,
      "maximum": 10
    },
    "max_price": {
      "description": "Ceiling in USD for the total charge. If the real price is above it, the purchase fails with PRICE_ABOVE_MAX and nothing is charged. Set it from the price the user approved.",
      "type": "number",
      "exclusiveMinimum": 0
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

buy_aftermarket

Buy a taken domain that's listed for sale on an aftermarket (Afternic/Sedo) at its buy-now price, natively - no external site. Use when search shows a domain with for_sale.buyable = true. Always confirm the price with the user first. Pass max_price to cap it. If the listing is make-offer only (not buyable), use acquire_domain (broker) to negotiate instead. Crypto/USDC works like buy_domain (402 -> pay -> retry with payment_tx).

Parameters5

domain	string	required	The taken, for-sale domain to buy, e.g. kami.world
max_price	number	optional	Hard ceiling in USD. Defaults to the listing's buy-now price. The purchase is rejected if the live price is above this.
payment_method	string	optional	'card' to charge the card on file, 'usdc' to pay with crypto.
payment_tx	string	optional	Tx hash of a USDC payment already sent on-chain (step 2 of the USDC flow).
payment_chain	string	optional	Chain the USDC payment was sent on. Required with payment_tx.

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "The taken, for-sale domain to buy, e.g. kami.world"
    },
    "max_price": {
      "description": "Hard ceiling in USD. Defaults to the listing's buy-now price. The purchase is rejected if the live price is above this.",
      "type": "number",
      "exclusiveMinimum": 0
    },
    "payment_method": {
      "description": "'card' to charge the card on file, 'usdc' to pay with crypto.",
      "type": "string",
      "enum": [
        "card",
        "usdc"
      ]
    },
    "payment_tx": {
      "description": "Tx hash of a USDC payment already sent on-chain (step 2 of the USDC flow).",
      "type": "string"
    },
    "payment_chain": {
      "description": "Chain the USDC payment was sent on. Required with payment_tx.",
      "type": "string",
      "enum": [
        "base",
        "ethereum"
      ]
    }
  },
  "required": [
    "domain"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

provision_agent

Give an AI agent a complete internet identity in one call: buy a domain, set up email, create a mailbox, and (optionally) register a webhook for inbound email. Use this when someone wants to 'give my agent a domain and email' or 'set up an agent from scratch'. Confirm the domain and price with the user first (it charges for the domain). The domain purchase is the only step that can fail the call; mailbox/webhook are best-effort and report warnings.

Parameters6

domain	string	required	Domain to give the agent, e.g. myagent.run. Bought if not already owned.
slug	string	optional	Mailbox local part, e.g. 'hi' for hi@domain. Default 'hi'.
name	string	optional	Display name for outbound email.
webhook_url	string	optional	Optional HTTPS URL to receive inbound email + domain events.
payment_method	string	optional	How to pay for the domain: card, usdc, or balance (marketplace credit).
years	integer	optional	Registration years (1-10, default 1).

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Domain to give the agent, e.g. myagent.run. Bought if not already owned."
    },
    "slug": {
      "description": "Mailbox local part, e.g. 'hi' for hi@domain. Default 'hi'.",
      "type": "string"
    },
    "name": {
      "description": "Display name for outbound email.",
      "type": "string"
    },
    "webhook_url": {
      "description": "Optional HTTPS URL to receive inbound email + domain events.",
      "type": "string"
    },
    "payment_method": {
      "description": "How to pay for the domain: card, usdc, or balance (marketplace credit).",
      "type": "string",
      "enum": [
        "card",
        "usdc",
        "balance"
      ]
    },
    "years": {
      "description": "Registration years (1-10, default 1).",
      "type": "integer",
      "minimum": 1,
      "maximum": 10
    }
  },
  "required": [
    "domain"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

list_domains

List all domains you own

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {}
}

get_dns

Get DNS records for a domain you own. Returns each record with a stable id, plus a zone_version token - pass it to set_dns to detect concurrent zone changes.

Parameters1

domain

string

required

Domain name to get DNS records for

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Domain name to get DNS records for"
    }
  },
  "required": [
    "domain"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

set_dns

Upsert DNS records for a domain you own, at the rrset level: records at a (type, name) you send replace that rrset; rrsets you don't mention are preserved (NS never touched). An automatic zone backup is taken before every write. Best practice: call get_dns first and pass its zone_version so a concurrent change fails with DNS_VERSION_CONFLICT instead of being clobbered. Common patterns: Vercel (A @ 76.76.21.21), GitHub Pages (CNAME @ user.github.io), Cloudflare Pages (CNAME @ project.pages.dev)

Parameters3

domain	string	required	Domain name to set DNS records for
records	array	required	Array of DNS records to set
zone_version	string	optional	The zone_version from get_dns - rejects the write with DNS_VERSION_CONFLICT if the zone changed since

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Domain name to set DNS records for"
    },
    "records": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "A",
              "AAAA",
              "CNAME",
              "MX",
              "TXT",
              "NS",
              "TLSA"
            ],
            "description": "DNS record type (TLSA for DANE)"
          },
          "name": {
            "type": "string",
            "description": "Record name, e.g. @ or subdomain (e.g. _443._tcp for TLSA)"
          },
          "value": {
            "type": "string",
            "description": "Record value: IP/hostname, or TLSA rdata like '3 1 1 abc123...'"
          },
          "ttl": {
            "type": "number",
            "description": "Time to live in seconds, e.g. 3600"
          },
          "priority": {
            "description": "Priority for MX records",
            "type": "number"
          }
        },
        "required": [
          "type",
          "name",
          "value",
          "ttl"
        ]
      },
      "description": "Array of DNS records to set"
    },
    "zone_version": {
      "description": "The zone_version from get_dns - rejects the write with DNS_VERSION_CONFLICT if the zone changed since",
      "type": "string"
    }
  },
  "required": [
    "domain",
    "records"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

snapshot_dns

Capture all DNS records for a domain via public DNS lookups. Discovers subdomains from CT logs, SPF, and common names. Stores a server-side backup. Use before migrations or transfers.

Parameters2

domain	string	required	Domain name to snapshot
extra_subdomains	array	optional	Additional subdomains to include

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Domain name to snapshot"
    },
    "extra_subdomains": {
      "description": "Additional subdomains to include",
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "domain"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

restore_dns

Restore DNS records from the server-side backup (created by snapshot_dns or during transfers). Uses diff to avoid duplicates. Call snapshot_dns first to create a backup. Pass dry_run to preview what would be applied without writing.

Parameters2

domain	string	required	Domain name to restore DNS for
dry_run	boolean	optional	Preview only - returns would_apply without writing anything

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Domain name to restore DNS for"
    },
    "dry_run": {
      "description": "Preview only - returns would_apply without writing anything",
      "type": "boolean"
    }
  },
  "required": [
    "domain"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

clone_dns

Copy the DNS setup of one domain you own onto another (e.g. brand.com → brand.dev with the same A/CNAME/MX). Merges by default (source wins on collisions, keeps the target's other records); set replace=true for an exact mirror.

Parameters3

to_domain	string	required	Target domain to write the DNS onto (must be yours)
from_domain	string	required	Source domain to copy DNS from (must be yours)
replace	boolean	optional	Exact mirror - drop target records the source doesn't have. Default: merge

Raw schema

{
  "type": "object",
  "properties": {
    "to_domain": {
      "type": "string",
      "description": "Target domain to write the DNS onto (must be yours)"
    },
    "from_domain": {
      "type": "string",
      "description": "Source domain to copy DNS from (must be yours)"
    },
    "replace": {
      "description": "Exact mirror - drop target records the source doesn't have. Default: merge",
      "type": "boolean"
    }
  },
  "required": [
    "to_domain",
    "from_domain"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

claim_identity

Give your agent a free identity at <handle>.domani.run - a live profile page, no domain purchase, instantly. The frictionless way to start; upgrade to your own real domain later. Optional name/bio/emoji/email/links.

Parameters6

slug	string	required	The handle - becomes <slug>.domani.run (lowercase letters, numbers, hyphens)
name	string	optional	Display name
bio	string	optional	Short description (<= 280 chars)
emoji	string	optional	Avatar emoji
email	string	optional	Public contact email (e.g. your free @domani.run inbox)
links	array	optional	Up to 6 links

Raw schema

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string",
      "description": "The handle - becomes <slug>.domani.run (lowercase letters, numbers, hyphens)"
    },
    "name": {
      "description": "Display name",
      "type": "string"
    },
    "bio": {
      "description": "Short description (<= 280 chars)",
      "type": "string"
    },
    "emoji": {
      "description": "Avatar emoji",
      "type": "string"
    },
    "email": {
      "description": "Public contact email (e.g. your free @domani.run inbox)",
      "type": "string"
    },
    "links": {
      "description": "Up to 6 links",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "label": {
            "type": "string"
          },
          "url": {
            "type": "string"
          }
        },
        "required": [
          "label",
          "url"
        ]
      }
    }
  },
  "required": [
    "slug"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

list_identities

List the free agent identities (<handle>.domani.run) you've claimed.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

update_identity

Update a free identity's name/bio/emoji/email/links.

Parameters6

slug	string	required	The handle to update
name	string	optional
bio	string	optional
emoji	string	optional
email	string	optional
links	array	optional

Raw schema

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string",
      "description": "The handle to update"
    },
    "name": {
      "type": "string"
    },
    "bio": {
      "type": "string"
    },
    "emoji": {
      "type": "string"
    },
    "email": {
      "type": "string"
    },
    "links": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "label": {
            "type": "string"
          },
          "url": {
            "type": "string"
          }
        },
        "required": [
          "label",
          "url"
        ]
      }
    }
  },
  "required": [
    "slug"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

release_identity

Release a free identity handle so it's available again.

Parameters1

slug

string

required

The handle to release

Raw schema

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string",
      "description": "The handle to release"
    }
  },
  "required": [
    "slug"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_dnssec

List the DNSSEC delegation-signer (DS) records for a domain you own, and whether DNSSEC is enabled. Pair with TLSA records (via set_dns) for DANE.

Parameters1

domain

string

required

Domain name to inspect

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Domain name to inspect"
    }
  },
  "required": [
    "domain"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

add_dnssec

Publish a DNSSEC delegation-signer (DS) record at the registry to enable DNSSEC. Get the DS values from your zone provider after signing the zone.

Parameters7

domain	string	required	Domain name to enable DNSSEC for
keyTag	string	required	Key tag, e.g. 12345
algorithm	string	required	DNSSEC algorithm number, e.g. 13 (ECDSAP256SHA256)
digestType	string	required	Digest type number, e.g. 2 (SHA-256)
digest	string	required	Hex digest of the DNSKEY
maxSigLife	string	optional	Optional max signature life in seconds
flags	string	optional	Optional DNSKEY flags, e.g. 257 (KSK)

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Domain name to enable DNSSEC for"
    },
    "keyTag": {
      "type": "string",
      "description": "Key tag, e.g. 12345"
    },
    "algorithm": {
      "type": "string",
      "description": "DNSSEC algorithm number, e.g. 13 (ECDSAP256SHA256)"
    },
    "digestType": {
      "type": "string",
      "description": "Digest type number, e.g. 2 (SHA-256)"
    },
    "digest": {
      "type": "string",
      "description": "Hex digest of the DNSKEY"
    },
    "maxSigLife": {
      "description": "Optional max signature life in seconds",
      "type": "string"
    },
    "flags": {
      "description": "Optional DNSKEY flags, e.g. 257 (KSK)",
      "type": "string"
    }
  },
  "required": [
    "domain",
    "keyTag",
    "algorithm",
    "digestType",
    "digest"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

delete_dnssec

Remove a DNSSEC delegation-signer (DS) record at the registry by its key tag. Removing all DS records disables DNSSEC.

Parameters2

domain	string	required	Domain name
keyTag	string	required	Key tag of the DS record to remove

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Domain name"
    },
    "keyTag": {
      "type": "string",
      "description": "Key tag of the DS record to remove"
    }
  },
  "required": [
    "domain",
    "keyTag"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_nameservers

Get the authoritative nameservers configured for a domain you own. If empty, DNS operations (parking, email, connect) will fail.

Parameters1

domain

string

required

Domain name to get nameservers for

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Domain name to get nameservers for"
    }
  },
  "required": [
    "domain"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

set_nameservers

Replace the nameservers for a domain you own. Requires 2–13 valid hostnames. Common values: OpenSRS DNS (ns1.systemdns.com, ns2.systemdns.com, ns3.systemdns.com), Cloudflare (assigned per account), custom NS.

Parameters2

domain	string	required	Domain name to set nameservers for
nameservers	array	required	Array of nameserver hostnames, e.g. ['ns1.systemdns.com', 'ns2.systemdns.com']

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Domain name to set nameservers for"
    },
    "nameservers": {
      "minItems": 2,
      "maxItems": 13,
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Array of nameserver hostnames, e.g. ['ns1.systemdns.com', 'ns2.systemdns.com']"
    }
  },
  "required": [
    "domain",
    "nameservers"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

setup_billing

Get a checkout URL for the user to add a payment card. Returns a URL - tell the user to open it in their browser. After they complete the form, call get_account to verify has_payment_method is true. Only needed for card payments - agents with crypto wallets can skip this and pay with USDC on Base via x402 protocol.

Parameters1

mode

string

optional

'checkout' (default) returns a URL for the user to open in browser. 'setup_intent' returns a client_secret for Stripe.js integration.

Raw schema

{
  "type": "object",
  "properties": {
    "mode": {
      "description": "'checkout' (default) returns a URL for the user to open in browser. 'setup_intent' returns a client_secret for Stripe.js integration.",
      "type": "string",
      "enum": [
        "checkout",
        "setup_intent"
      ]
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

upgrade_plan

Get a Stripe checkout URL to upgrade the user to the Pro plan ($9/month). Returns a URL. Tell the user to open it in their browser to complete the upgrade. Pro includes 10,000 emails/month, unlimited mailboxes on custom domains, API/MCP/CLI access, webhooks, and forwarding. Use this when the user hits the free plan monthly send limit (MONTHLY_LIMIT_EXCEEDED error).

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

cancel_plan

Cancel the user's Pro subscription. The subscription remains active until the end of the current billing period, then reverts to the free plan. Returns the cancellation date.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

list_invoices

List the user's payment invoices. Returns invoice number, amount, date, and links to view/download the PDF. Each invoice is generated by Stripe when a domain is purchased, renewed, or transferred.

Parameters1

limit

integer

optional

Max invoices to return (default 20, max 100)

Raw schema

{
  "type": "object",
  "properties": {
    "limit": {
      "description": "Max invoices to return (default 20, max 100)",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

list_tokens

List all API tokens for your account. Shows token name, masked key, creation date, last used, and expiration status. Expired tokens are marked.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {}
}

create_token

Create a new API token with optional scoped permissions and spend caps. The full key is returned only once - save it immediately. A token can only grant scopes it already has (scope attenuation) and spend caps at or below its own. Scopes: domains:read (GET /api/domains, GET /api/domains/{domain}, GET /api/domains/{domain}/dns, /dnssec, /status, /email/check, /auth-code, /transfer-away, /transfer-status, /analytics), domains:write (PUT /api/domains/{domain}/dns, POST/DELETE /api/domains/{domain}/dnssec, POST /connect, POST /verify, PUT /settings, PUT /parking, PUT/DELETE /api/domains/{domain}/for-sale, POST /api/domains/import, POST /import/verify), domains:transfer (POST /api/domains/buy, POST /transfer, POST /renew (involves payment, includes marketplace purchases)), tokens:read (GET /api/tokens), tokens:write (POST /api/tokens, DELETE /api/tokens/{id}), webhooks:read (GET /api/webhooks, GET /api/webhooks/{id}/deliveries), webhooks:write (POST /api/webhooks, PATCH /api/webhooks/{id}, DELETE /api/webhooks/{id}), email:read (GET /api/emails, /api/emails/{address}, /api/emails/{address}/messages, /api/emails/{address}/aliases, /api/domains/{domain}/email/status, /api/domains/{domain}/email/deliverability, /api/suppressions), email:write (POST /api/emails, POST /api/emails/{address}/send, POST /api/domains/{domain}/email/setup, aliases + catch-all, POST/DELETE /api/suppressions), email:delete (Permanently delete messages already in Trash. Moving messages to Trash only requires email:write. Grant this scope only to agents allowed to irreversibly erase email content), email:auth_secrets (Read messages classified as authentication mail (OTP / verification codes, password resets, magic links). Without it, email:read still lists them but subject and body come back redacted - so a stolen agent token can't harvest 2FA codes. Grant it only to agents that genuinely need to complete logins), account:read (GET /api/me, GET /api/agents/identity), account:write (DELETE /api/me, POST /api/billing/setup, POST /api/billing/subscribe, POST /api/billing/cancel, POST /api/me/resend-verification, POST/PATCH/DELETE /api/agents/identity), billing:read (GET /api/billing/invoices), search (GET /api/domains/search, /suggest, /whois, /dns-check, GET /api/tlds), deals:read (GET /api/deals, GET /api/deals/{id}), deals:write (POST /api/domains/sell, PATCH /api/deals/{id}), notifications:read (GET /api/notifications, GET /api/notifications/count), backorders:read (GET /api/backorders, GET /api/backorders/{id}), backorders:write (POST /api/backorders, DELETE /api/backorders/{id}). Use ['*'] for full access (default). When minting a token for a sub-agent that can buy, ALWAYS set max_per_tx/max_per_month.

Parameters7

name	string	optional	Human-readable label, e.g. 'CI/CD', 'Sub-Agent'. Defaults to 'CLI'
scopes	array	optional	Permission scopes for this token. Defaults to parent token's scopes. Use ['*'] for full access
expires_in	integer	optional	Token lifetime in seconds (min 3600 = 1h, max 31536000 = 1y). Omit for no expiration
expires_at	string	optional	Absolute expiration date (ISO 8601). Alternative to expires_in
max_per_tx	number	optional	Per-transaction spend cap in USD - any single charge above it is rejected server-side (SPEND_CAP_EXCEEDED)
max_per_month	number	optional	Rolling calendar-month spend cap in USD for all paid operations with this token
agent_identity_id	string	optional	Optional owned AgentIdentity id. Mail actions made with this token are attributed to that agent

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "description": "Human-readable label, e.g. 'CI/CD', 'Sub-Agent'. Defaults to 'CLI'",
      "type": "string"
    },
    "scopes": {
      "description": "Permission scopes for this token. Defaults to parent token's scopes. Use ['*'] for full access",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "expires_in": {
      "description": "Token lifetime in seconds (min 3600 = 1h, max 31536000 = 1y). Omit for no expiration",
      "type": "integer",
      "minimum": 3600,
      "maximum": 31536000
    },
    "expires_at": {
      "description": "Absolute expiration date (ISO 8601). Alternative to expires_in",
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
    },
    "max_per_tx": {
      "description": "Per-transaction spend cap in USD - any single charge above it is rejected server-side (SPEND_CAP_EXCEEDED)",
      "type": "number",
      "exclusiveMinimum": 0
    },
    "max_per_month": {
      "description": "Rolling calendar-month spend cap in USD for all paid operations with this token",
      "type": "number",
      "exclusiveMinimum": 0
    },
    "agent_identity_id": {
      "description": "Optional owned AgentIdentity id. Mail actions made with this token are attributed to that agent",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

list_audit_events

The account's security audit trail, newest first: token lifecycle (created/revoked/escalation attempts), spend-cap and max_price denials, charges, payout requests. Use it to review what the account's tokens have been doing.

Parameters2

limit	integer	optional	Events to return (default 50)
type	string	optional	Filter by event type, e.g. purchase.denied_cap, token.created

Raw schema

{
  "type": "object",
  "properties": {
    "limit": {
      "description": "Events to return (default 50)",
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    },
    "type": {
      "description": "Filter by event type, e.g. purchase.denied_cap, token.created",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

revoke_token

Revoke an API token immediately. The token will stop working. Use list_tokens to find token IDs.

Parameters1

token_id

string

required

ID of the token to revoke (from list_tokens)

Raw schema

{
  "type": "object",
  "properties": {
    "token_id": {
      "type": "string",
      "description": "ID of the token to revoke (from list_tokens)"
    }
  },
  "required": [
    "token_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

connect_domain

Connect a domain to a hosting or email provider. Auto-detects provider from target, or accepts explicit provider name. For domains bought through the platform, DNS records are set automatically (status: dns_set). For imported domains (external registrar), returns the records as instructions to add manually (status: manual_setup_required). If the connect would REPLACE existing MX records pointing at another provider, it fails with MX_REPLACEMENT_REQUIRES_CONFIRMATION - preview with dry_run, confirm with the user, then retry with confirm_replace_mx. The response includes a next_steps array with provider-specific actions. Supported hosting: vercel, netlify, cloudflare-pages, github-pages, railway, fly. Email: google-workspace, fastmail, proton.

Parameters6

domain	string	required	Domain to connect, e.g. mysite.com
target	string	optional	Target URL for auto-detection, e.g. my-app.vercel.app
provider	string	optional	Explicit provider name, e.g. vercel, google-workspace
method	string	optional	Connection method if provider has multiple, e.g. cname-only
dry_run	boolean	optional	Preview only - returns the diff (create/replace/keep) without writing
confirm_replace_mx	boolean	optional	Confirm replacing existing MX records that point at another provider (moves the domain's email)

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Domain to connect, e.g. mysite.com"
    },
    "target": {
      "description": "Target URL for auto-detection, e.g. my-app.vercel.app",
      "type": "string"
    },
    "provider": {
      "description": "Explicit provider name, e.g. vercel, google-workspace",
      "type": "string"
    },
    "method": {
      "description": "Connection method if provider has multiple, e.g. cname-only",
      "type": "string"
    },
    "dry_run": {
      "description": "Preview only - returns the diff (create/replace/keep) without writing",
      "type": "boolean"
    },
    "confirm_replace_mx": {
      "description": "Confirm replacing existing MX records that point at another provider (moves the domain's email)",
      "type": "boolean"
    }
  },
  "required": [
    "domain"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

domain_status

Check domain health: DNS propagation, SSL status, email (MX) configuration, and expiry date

Parameters1

domain

string

required

Domain to check status for

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Domain to check status for"
    }
  },
  "required": [
    "domain"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

verify_connection

Verify that a provider connection is working by checking DNS propagation. Use after connect_domain to confirm records are live.

Parameters4

domain	string	required	Domain to verify
target	string	optional	Target for auto-detection, e.g. my-app.vercel.app
provider	string	optional	Provider name, e.g. vercel
method	string	optional	Method name if applicable

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Domain to verify"
    },
    "target": {
      "description": "Target for auto-detection, e.g. my-app.vercel.app",
      "type": "string"
    },
    "provider": {
      "description": "Provider name, e.g. vercel",
      "type": "string"
    },
    "method": {
      "description": "Method name if applicable",
      "type": "string"
    }
  },
  "required": [
    "domain"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

verify_service

Add DNS records to verify domain ownership for a third-party service (Stripe, Google Search Console, AWS SES, Postmark, Resend, Facebook, HubSpot, Microsoft 365). Unknown services fall back to a generic TXT record.

Parameters3

domain	string	required	Domain name
service	string	required	Service name (e.g. stripe, google-search-console, aws-ses, postmark, resend, facebook, hubspot, microsoft-365)
token	string	required	Verification token provided by the service

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Domain name"
    },
    "service": {
      "type": "string",
      "description": "Service name (e.g. stripe, google-search-console, aws-ses, postmark, resend, facebook, hubspot, microsoft-365)"
    },
    "token": {
      "type": "string",
      "description": "Verification token provided by the service"
    }
  },
  "required": [
    "domain",
    "service",
    "token"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

list_services

List all supported services for domain verification (Stripe, Google Search Console, etc.)

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

whois_lookup

Look up domain registration data via RDAP (modern WHOIS). Returns registrar, dates, status, nameservers, DNSSEC, and contact information (registrant, admin, tech, billing - often redacted for privacy). Works for any domain - no ownership required.

Parameters1

domain

string

required

Domain to look up, e.g. example.com

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Domain to look up, e.g. example.com"
    }
  },
  "required": [
    "domain"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_domain_preview

Get website preview metadata (title, description, image, favicon) for any domain. Useful for understanding what a taken domain is currently used for. Data is cached for 7 days.

Parameters1

domain

string

required

Domain to preview, e.g. google.com

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Domain to preview, e.g. google.com"
    }
  },
  "required": [
    "domain"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

set_auto_renew

Enable or disable auto-renew for a domain you own. When enabled, the domain will be renewed automatically before expiry.

Parameters2

domain	string	required	Domain name to configure
enabled	boolean	required	true to enable auto-renew, false to disable

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Domain name to configure"
    },
    "enabled": {
      "type": "boolean",
      "description": "true to enable auto-renew, false to disable"
    }
  },
  "required": [
    "domain",
    "enabled"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

set_whois_privacy

Enable or disable WHOIS privacy for a domain you own. When enabled, your personal contact information is hidden from public WHOIS lookups.

Parameters2

domain	string	required	Domain name to configure
enabled	boolean	required	true to enable WHOIS privacy, false to disable

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Domain name to configure"
    },
    "enabled": {
      "type": "boolean",
      "description": "true to enable WHOIS privacy, false to disable"
    }
  },
  "required": [
    "domain",
    "enabled"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

set_security_lock

Lock or unlock a domain's transfer lock (clientTransferProhibited). When locked, transfer requests are rejected. Unlock before transferring to another registrar.

Parameters2

domain	string	required	Domain name to configure
locked	boolean	required	true to lock (prevent transfers), false to unlock

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Domain name to configure"
    },
    "locked": {
      "type": "boolean",
      "description": "true to lock (prevent transfers), false to unlock"
    }
  },
  "required": [
    "domain",
    "locked"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

set_domain_redirect

Forward a domain you own to another URL (e.g. brand.com -> brand.dev). The domain must point at domani's nameservers/parking IP. Permanent (308) by default, or temporary (307). Send an empty url to stop forwarding.

Parameters3

domain	string	required	The domain to forward (must be one you own)
url	string	required	Target URL to forward to, e.g. https://brand.dev. Empty string clears the redirect.
permanent	boolean	optional	true = permanent redirect (default), false = temporary

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "The domain to forward (must be one you own)"
    },
    "url": {
      "type": "string",
      "description": "Target URL to forward to, e.g. https://brand.dev. Empty string clears the redirect."
    },
    "permanent": {
      "description": "true = permanent redirect (default), false = temporary",
      "type": "boolean"
    }
  },
  "required": [
    "domain",
    "url"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_auth_code

Get the EPP/auth code needed to transfer a domain to another registrar. Automatically unlocks the domain if it's locked. Give this code to the new registrar to initiate the transfer.

Parameters1

domain

string

required

Domain to get auth code for

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Domain to get auth code for"
    }
  },
  "required": [
    "domain"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_transfer_away

Check the status of an outbound domain transfer. Use after getting an auth code and initiating the transfer at the new registrar.

Parameters1

domain

string

required

Domain to check transfer status for

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Domain to check transfer status for"
    }
  },
  "required": [
    "domain"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

check_transfer_status

Check the status of an inbound domain transfer. Returns detailed status (pending_owner, pending_admin, pending_registry, completed, cancelled) with actionable hints.

Parameters1

domain

string

required

Domain to check transfer status for

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Domain to check transfer status for"
    }
  },
  "required": [
    "domain"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

set_contact

Set your WHOIS contact information (recommended for ICANN compliance, required before transfers). You can purchase domains without setting contact info first - a default contact is used until you set your own.

Parameters11

first_name	string	required	First name
last_name	string	required	Last name
org_name	string	optional	Organization name (optional)
address1	string	required	Street address line 1
address2	string	optional	Street address line 2 (optional)
city	string	required	City
state	string	required	State or province
postal_code	string	required	Postal/ZIP code
country	string	required	ISO 3166-1 alpha-2 country code, e.g. US, GB, FR
phone	string	required	Phone in +CC.NUMBER format, e.g. +1.5551234567
email	string	required	Contact email address

Raw schema

{
  "type": "object",
  "properties": {
    "first_name": {
      "type": "string",
      "description": "First name"
    },
    "last_name": {
      "type": "string",
      "description": "Last name"
    },
    "org_name": {
      "description": "Organization name (optional)",
      "type": "string"
    },
    "address1": {
      "type": "string",
      "description": "Street address line 1"
    },
    "address2": {
      "description": "Street address line 2 (optional)",
      "type": "string"
    },
    "city": {
      "type": "string",
      "description": "City"
    },
    "state": {
      "type": "string",
      "description": "State or province"
    },
    "postal_code": {
      "type": "string",
      "description": "Postal/ZIP code"
    },
    "country": {
      "type": "string",
      "description": "ISO 3166-1 alpha-2 country code, e.g. US, GB, FR"
    },
    "phone": {
      "type": "string",
      "description": "Phone in +CC.NUMBER format, e.g. +1.5551234567"
    },
    "email": {
      "type": "string",
      "description": "Contact email address"
    }
  },
  "required": [
    "first_name",
    "last_name",
    "address1",
    "city",
    "state",
    "postal_code",
    "country",
    "phone",
    "email"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

resend_email_verification

Resend a verification email for your WHOIS contact email. If the contact email matches your login email, it's already verified. Rate limited to once per 15 minutes.

Parameters1

string

optional

Email to verify (defaults to your contact email)

Raw schema

{
  "type": "object",
  "properties": {
    "email": {
      "description": "Email to verify (defaults to your contact email)",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_domain_info

Get detailed information about a domain you own, including auto-renew status, security lock, WHOIS privacy, and provider data.

Parameters1

domain

string

required

Domain name to get info for

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Domain name to get info for"
    }
  },
  "required": [
    "domain"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

plan_domain_adoption

Read-only planner for an existing domain. Inspects registrar, nameservers, DNS provider, DNSSEC, account state, transfer eligibility, and price. Returns safe next actions. Call this before asking for an EPP code. Connecting is free and leaves registrar and DNS unchanged. Transferring preserves nameservers and never migrates DNS implicitly.

Parameters1

domain

string

required

Existing domain to inspect, e.g. mysite.com

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Existing domain to inspect, e.g. mysite.com"
    }
  },
  "required": [
    "domain"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

check_transfer_eligibility

Pre-check whether a domain can be transferred. Returns transfer price, eligibility status, and any blockers (unsupported TLD, ICANN waiting period, domain locked, etc.). Always call this before transfer_domain to verify eligibility and show the user the price.

Parameters1

domain

string

required

Domain to check, e.g. mysite.com

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Domain to check, e.g. mysite.com"
    }
  },
  "required": [
    "domain"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

transfer_domain

Initiate a domain transfer from another provider. PAID. The transfer includes 1 year of renewal, preserves current nameservers, and does not migrate DNS. Call plan_domain_adoption first, show the exact price and continuity plan, then get explicit confirmation before calling this. Requires the authorization/EPP code from the current provider.

Parameters6

domain	string	required	Domain to transfer, e.g. mysite.com
auth_code	string	required	Authorization/EPP code from the current provider
payment_method	string	optional	Payment method: 'card' to charge card on file, 'usdc' to pay with USDC. Overrides the user's default preference for this request.
payment_tx	string	optional	Transaction hash of a USDC payment already sent on-chain.
payment_chain	string	optional	Chain the USDC payment was sent on.
extra_subdomains	array	optional	Additional subdomains to include in the pre-transfer DNS snapshot. We auto-discover subdomains via CT logs, SPF, MX/DKIM inference, and a common wordlist - use this for any custom subdomains we might miss.

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Domain to transfer, e.g. mysite.com"
    },
    "auth_code": {
      "type": "string",
      "description": "Authorization/EPP code from the current provider"
    },
    "payment_method": {
      "description": "Payment method: 'card' to charge card on file, 'usdc' to pay with USDC. Overrides the user's default preference for this request.",
      "type": "string",
      "enum": [
        "card",
        "usdc"
      ]
    },
    "payment_tx": {
      "description": "Transaction hash of a USDC payment already sent on-chain.",
      "type": "string"
    },
    "payment_chain": {
      "description": "Chain the USDC payment was sent on.",
      "type": "string",
      "enum": [
        "base",
        "ethereum"
      ]
    },
    "extra_subdomains": {
      "description": "Additional subdomains to include in the pre-transfer DNS snapshot. We auto-discover subdomains via CT logs, SPF, MX/DKIM inference, and a common wordlist - use this for any custom subdomains we might miss.",
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "domain",
    "auth_code"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

watch_transfer

Watch a domain and get notified (email + webhook) when it becomes eligible for transfer. Uses RDAP to check ICANN lock periods and EPP status codes. If the domain is already eligible, returns immediately without creating a watch. If not eligible but has a known date, creates a watch and notifies you when it's ready.

Parameters1

domain

string

required

Domain to watch, e.g. example.com

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Domain to watch, e.g. example.com"
    }
  },
  "required": [
    "domain"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

renew_domain

Renew a domain you own for additional years. Always confirm with the user before calling this.

Parameters6

domain	string	required	Domain to renew, e.g. mysite.com
years	number	optional	Number of years to renew (1-10, default 1)
payment_method	string	optional	Payment method: 'card' to charge card on file, 'usdc' to pay with USDC. Overrides the user's default preference for this request.
payment_tx	string	optional	Transaction hash of a USDC payment already sent on-chain.
payment_chain	string	optional	Chain the USDC payment was sent on.
max_price	number	optional	Ceiling in USD for the renewal charge. Fails with PRICE_ABOVE_MAX (nothing charged) if the real price is above it.

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Domain to renew, e.g. mysite.com"
    },
    "years": {
      "description": "Number of years to renew (1-10, default 1)",
      "type": "number"
    },
    "payment_method": {
      "description": "Payment method: 'card' to charge card on file, 'usdc' to pay with USDC. Overrides the user's default preference for this request.",
      "type": "string",
      "enum": [
        "card",
        "usdc"
      ]
    },
    "payment_tx": {
      "description": "Transaction hash of a USDC payment already sent on-chain.",
      "type": "string"
    },
    "payment_chain": {
      "description": "Chain the USDC payment was sent on.",
      "type": "string",
      "enum": [
        "base",
        "ethereum"
      ]
    },
    "max_price": {
      "description": "Ceiling in USD for the renewal charge. Fails with PRICE_ABOVE_MAX (nothing charged) if the real price is above it.",
      "type": "number",
      "exclusiveMinimum": 0
    }
  },
  "required": [
    "domain"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

list_providers

List all supported hosting and email providers with their connection methods, target requirements, and setup notes

Parameters1

import_domain

Import an external domain you already own (registered at GoDaddy, Namecheap, Cloudflare, etc.) to manage through domani.run. Free, no transfer needed. Returns a TXT record to add at your DNS provider for ownership verification.

Parameters1

domain

string

required

Domain to import, e.g. mysite.com

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Domain to import, e.g. mysite.com"
    }
  },
  "required": [
    "domain"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

verify_import

Verify DNS TXT record and complete domain import. Call after adding the TXT record from import_domain.

Parameters1

domain

string

required

Domain to verify, e.g. mysite.com

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Domain to verify, e.g. mysite.com"
    }
  },
  "required": [
    "domain"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

set_parking

Enable or disable the parking page for a domain you own. When enabled, visitors to the domain see a default parking page (or a 'For Sale' page if a listing price is set). Parking is enabled by default for newly purchased domains. IMPORTANT: If the domain has existing DNS records, the response will include requires_confirmation=true and show the records that will be overwritten. You MUST inform the user and get their approval before calling again with confirm=true.

Parameters3

domain	string	required	Domain to configure, e.g. example.com
enabled	boolean	required	true to enable the parking page, false to disable it
confirm	boolean	optional	Set to true to confirm overwriting existing DNS records. Only needed when the first call returns requires_confirmation=true.

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Domain to configure, e.g. example.com"
    },
    "enabled": {
      "type": "boolean",
      "description": "true to enable the parking page, false to disable it"
    },
    "confirm": {
      "description": "Set to true to confirm overwriting existing DNS records. Only needed when the first call returns requires_confirmation=true.",
      "type": "boolean"
    }
  },
  "required": [
    "domain",
    "enabled"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_parking_analytics

Get visitor analytics for a parked domain - page views, inquiries, conversion rate, 30-day daily breakdown, and the 5 most recent inquiries. Use this to check how much traffic a parked domain gets and whether it's converting into buyer inquiries.

Parameters1

domain

string

required

Domain to get analytics for, e.g. example.com

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Domain to get analytics for, e.g. example.com"
    }
  },
  "required": [
    "domain"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

set_listing_price

Set a 'For Sale' price on a parked domain, or remove the listing. When a price is set and parking is enabled, visitors see a 'For Sale' page with the price and a contact form to reach the domain owner. Set price to null to remove the listing.

Parameters2

domain	string	required	Domain to configure, e.g. example.com
price	any	required	Sale price in USD (e.g. 499.99), or null to remove the listing

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Domain to configure, e.g. example.com"
    },
    "price": {
      "anyOf": [
        {
          "type": "number",
          "exclusiveMinimum": 0
        },
        {
          "type": "null"
        }
      ],
      "description": "Sale price in USD (e.g. 499.99), or null to remove the listing"
    }
  },
  "required": [
    "domain",
    "price"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

sell_domain

List a domain you own for sale on the Domani marketplace. Buyers can purchase it directly via the API. The domain must be active and not already listed. Requires domains:write scope.

Parameters3

domain	string	required	Domain to list for sale, e.g. premium.com
price	number	required	Sale price in USD (e.g. 5000)
description	string	optional	Optional listing description

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Domain to list for sale, e.g. premium.com"
    },
    "price": {
      "type": "number",
      "exclusiveMinimum": 0,
      "description": "Sale price in USD (e.g. 5000)"
    },
    "description": {
      "description": "Optional listing description",
      "type": "string",
      "maxLength": 500
    }
  },
  "required": [
    "domain",
    "price"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

update_listing

Update the price and/or description of an active marketplace listing. Requires domains:write scope.

Parameters3

domain	string	required	Domain with active listing, e.g. premium.com
price	number	optional	New price in USD
description	any	optional	New description (null to clear)

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Domain with active listing, e.g. premium.com"
    },
    "price": {
      "description": "New price in USD",
      "type": "number",
      "exclusiveMinimum": 0,
      "maximum": 20000000
    },
    "description": {
      "description": "New description (null to clear)",
      "anyOf": [
        {
          "type": "string",
          "maxLength": 500
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "domain"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

unsell_domain

Remove an active for-sale listing for a domain you own. The domain stays in your account but is no longer purchasable on the marketplace. Requires domains:write scope.

Parameters1

domain

string

required

Domain to unlist, e.g. premium.com

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Domain to unlist, e.g. premium.com"
    }
  },
  "required": [
    "domain"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

make_offer

Open an anonymous price negotiation on a listed domain with an initial offer (below or at the asking price). The seller can counter, accept, or decline. Neither side sees the other's identity. Requires deals:write scope.

Parameters3

domain	string	required	The listed domain to negotiate on, e.g. premium.com
offer	number	required	Your initial offer in USD, e.g. 500
message	string	optional	Optional message to the seller

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "The listed domain to negotiate on, e.g. premium.com"
    },
    "offer": {
      "type": "number",
      "exclusiveMinimum": 0,
      "description": "Your initial offer in USD, e.g. 500"
    },
    "message": {
      "description": "Optional message to the seller",
      "type": "string",
      "maxLength": 1000
    }
  },
  "required": [
    "domain",
    "offer"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

respond_to_offer

Counter, accept, or decline the current offer in a negotiation when it's your turn. 'accept' locks the price at the amount on the table; the buyer then finalizes payment. Requires deals:write scope.

Parameters4

negotiation_id	string	required	The negotiation ID
action	string	required	Your response
counter	number	optional	New amount in USD (required when action=counter)
message	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "negotiation_id": {
      "type": "string",
      "description": "The negotiation ID"
    },
    "action": {
      "type": "string",
      "enum": [
        "counter",
        "accept",
        "decline"
      ],
      "description": "Your response"
    },
    "counter": {
      "description": "New amount in USD (required when action=counter)",
      "type": "number",
      "exclusiveMinimum": 0
    },
    "message": {
      "type": "string",
      "maxLength": 1000
    }
  },
  "required": [
    "negotiation_id",
    "action"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

finalize_negotiation

As the buyer, pay the agreed price to create the escrow deal and start the transfer. Same payment methods as a purchase (card, USDC, x402). Requires domains:transfer scope. For a broker-sourced acquisition, if the agreed price is above the max_budget you set, this returns BUDGET_EXCEEDED - retry with confirm_over_budget: true to proceed anyway.

Parameters3

negotiation_id	string	required	The agreed negotiation to finalize
payment_method	string	optional
confirm_over_budget	boolean	optional	Set true to finalize a broker deal above the max_budget you set on the acquisition request

Raw schema

{
  "type": "object",
  "properties": {
    "negotiation_id": {
      "type": "string",
      "description": "The agreed negotiation to finalize"
    },
    "payment_method": {
      "type": "string",
      "enum": [
        "card",
        "usdc",
        "balance"
      ]
    },
    "confirm_over_budget": {
      "description": "Set true to finalize a broker deal above the max_budget you set on the acquisition request",
      "type": "boolean"
    }
  },
  "required": [
    "negotiation_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

list_negotiations

List your active and past price negotiations (as buyer or seller). Counterparties are anonymized. Requires deals:read scope.

Parameters2

role	string	optional	Filter by your role
status	string	optional	Filter by status (open\|agreed\|completed\|all)

Raw schema

{
  "type": "object",
  "properties": {
    "role": {
      "description": "Filter by your role",
      "type": "string",
      "enum": [
        "buyer",
        "seller"
      ]
    },
    "status": {
      "description": "Filter by status (open|agreed|completed|all)",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_deal_invoice

Get a role-aware receipt/statement for a marketplace deal. Buyers see what they paid; sellers see the sale, the platform commission line, and the net payout. Works for every payment method. Requires deals:read scope.

Parameters1

deal_id

string

required

The deal ID

Raw schema

{
  "type": "object",
  "properties": {
    "deal_id": {
      "type": "string",
      "description": "The deal ID"
    }
  },
  "required": [
    "deal_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

acquire_domain

Ask domani to acquire a specific taken, unlisted domain on your behalf. Agents source the owner via RDAP, reach out anonymously, and negotiate - commission-only, no upfront fee. Owner interest opens an anonymous negotiation you can accept/counter. Note: many owners are unreachable (GDPR-redacted WHOIS). Requires deals:write scope.

Parameters2

domain	string	required	The taken domain you want, e.g. dream.com
max_budget	number	optional	Your ceiling in USD (optional)

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "The taken domain you want, e.g. dream.com"
    },
    "max_budget": {
      "description": "Your ceiling in USD (optional)",
      "type": "number",
      "exclusiveMinimum": 0
    }
  },
  "required": [
    "domain"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

list_broker_requests

List your domain acquisition requests and their status (sourcing/contacted/negotiating/agreed/no_contact/declined). Requires deals:read scope.

Parameters1

status

string

optional

Filter by status, or 'all'

Raw schema

{
  "type": "object",
  "properties": {
    "status": {
      "description": "Filter by status, or 'all'",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

cancel_broker_request

Cancel an active domain acquisition request. Requires deals:write scope.

Parameters1

request_id

string

required

The broker request ID

Raw schema

{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string",
      "description": "The broker request ID"
    }
  },
  "required": [
    "request_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

respond_to_broker_inquiry

Owner-agent path: respond to a broker's acquisition inquiry using the token from the outreach email in your inbox - fully autonomous, no email round-trip, no magic-link. offer/counter names a price and opens/advances an anonymous negotiation; accept agrees to the buyer's current offer on the table; decline/opt_out ends it. Token-authorized (no scope needed).

Parameters3

token	string	required	The outreach token from your inquiry email (reply-to is broker+<token>@)
action	string	required	offer/counter to name a price; accept to take the buyer's current offer; decline to refuse; opt_out to stop contact
price	number	optional	Your asking price in USD (required for offer/counter)

Raw schema

{
  "type": "object",
  "properties": {
    "token": {
      "type": "string",
      "description": "The outreach token from your inquiry email (reply-to is broker+<token>@)"
    },
    "action": {
      "type": "string",
      "enum": [
        "offer",
        "counter",
        "accept",
        "decline",
        "opt_out"
      ],
      "description": "offer/counter to name a price; accept to take the buyer's current offer; decline to refuse; opt_out to stop contact"
    },
    "price": {
      "description": "Your asking price in USD (required for offer/counter)",
      "type": "number",
      "exclusiveMinimum": 0
    }
  },
  "required": [
    "token",
    "action"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_broker_inquiry_state

Owner-agent read path: poll the current, anonymized state of a broker inquiry with your token before acting. Returns the domain, the buyer's offer on the table, whose move it is, and the actions available now. Never exposes the buyer's identity or budget.

Parameters1

token

string

required

The outreach token from your inquiry email

Raw schema

{
  "type": "object",
  "properties": {
    "token": {
      "type": "string",
      "description": "The outreach token from your inquiry email"
    }
  },
  "required": [
    "token"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

browse_marketplace

Browse domains for sale on the Domani marketplace. Returns all active listings with prices. Use buy_domain to purchase a listed domain.

Parameters3

max_price	number	optional	Maximum price in USD
sort	string	optional	Sort by price or TLD (default: price)
order	string	optional	Sort order (default: asc)

Raw schema

{
  "type": "object",
  "properties": {
    "max_price": {
      "description": "Maximum price in USD",
      "type": "number"
    },
    "sort": {
      "description": "Sort by price or TLD (default: price)",
      "type": "string",
      "enum": [
        "price",
        "tld"
      ]
    },
    "order": {
      "description": "Sort order (default: asc)",
      "type": "string",
      "enum": [
        "asc",
        "desc"
      ]
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

create_backorder

Place a backorder on a domain that is currently registered to someone else. We watch it and automatically register it for the user when it becomes available (drops) - availability is polled every few minutes. The user is charged only if the catch succeeds - no upfront fee. Requires a card on file or payment_method 'balance'. Confirm the domain with the user first. Best-effort: a contested drop may be taken by a specialized drop-catcher first.

Parameters3

domain	string	required	The currently-taken domain to watch and catch on drop, e.g. taken.com
max_price	number	optional	Max USD to pay when caught. Defaults to the current registration price.
payment_method	string	optional	How to pay when caught: 'card' or 'balance' (marketplace credit).

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "The currently-taken domain to watch and catch on drop, e.g. taken.com"
    },
    "max_price": {
      "description": "Max USD to pay when caught. Defaults to the current registration price.",
      "type": "number",
      "exclusiveMinimum": 0
    },
    "payment_method": {
      "description": "How to pay when caught: 'card' or 'balance' (marketplace credit).",
      "type": "string",
      "enum": [
        "card",
        "balance"
      ]
    }
  },
  "required": [
    "domain"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

list_backorders

List the user's backorders (watching, caught, failed, cancelled, expired). Optionally filter by status.

Parameters1

status

string

optional

Filter by status

Raw schema

{
  "type": "object",
  "properties": {
    "status": {
      "description": "Filter by status",
      "type": "string",
      "enum": [
        "watching",
        "caught",
        "failed",
        "cancelled",
        "expired"
      ]
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

cancel_backorder

Stop watching a domain by cancelling a backorder. Only backorders in the 'watching' state can be cancelled.

Parameters1

string

required

The backorder ID to cancel

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The backorder ID to cancel"
    }
  },
  "required": [
    "id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

list_webhooks

List all webhook endpoints configured for the user's account. Returns URL, subscribed events, and active status for each webhook.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

create_webhook

Register a new webhook endpoint to receive event notifications. The URL must use HTTPS. Choose which events to subscribe to (e.g. domain.purchased, transfer.completed). The webhook secret is returned only once - save it to verify incoming payloads with HMAC-SHA256.

Parameters2

url	string	required	HTTPS URL that will receive webhook POST requests
events	array	required	Event types to subscribe to, e.g. ["domain.purchased", "dns.updated"]. Use list_webhook_events to see all available types.

Raw schema

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "HTTPS URL that will receive webhook POST requests"
    },
    "events": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Event types to subscribe to, e.g. [\"domain.purchased\", \"dns.updated\"]. Use list_webhook_events to see all available types."
    }
  },
  "required": [
    "url",
    "events"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

update_webhook

Update an existing webhook's URL, subscribed events, or active status. Use list_webhooks to get the webhook ID first.

Parameters4

webhook_id	string	required	ID of the webhook to update
url	string	optional	New HTTPS URL for the webhook
events	array	optional	New list of event types to subscribe to
active	boolean	optional	Set to false to pause the webhook, true to resume

Raw schema

{
  "type": "object",
  "properties": {
    "webhook_id": {
      "type": "string",
      "description": "ID of the webhook to update"
    },
    "url": {
      "description": "New HTTPS URL for the webhook",
      "type": "string"
    },
    "events": {
      "description": "New list of event types to subscribe to",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "active": {
      "description": "Set to false to pause the webhook, true to resume",
      "type": "boolean"
    }
  },
  "required": [
    "webhook_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

delete_webhook

Delete a webhook endpoint. All pending deliveries will be cancelled. This action cannot be undone.

Parameters1

webhook_id

string

required

ID of the webhook to delete

Raw schema

{
  "type": "object",
  "properties": {
    "webhook_id": {
      "type": "string",
      "description": "ID of the webhook to delete"
    }
  },
  "required": [
    "webhook_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

list_webhook_deliveries

Get recent delivery attempts for a webhook - shows event type, HTTP status, number of attempts, and any errors. Useful for debugging webhook issues.

Parameters2

webhook_id	string	required	ID of the webhook to get deliveries for
limit	integer	optional	Maximum number of deliveries to return (default 20)

Raw schema

{
  "type": "object",
  "properties": {
    "webhook_id": {
      "type": "string",
      "description": "ID of the webhook to get deliveries for"
    },
    "limit": {
      "description": "Maximum number of deliveries to return (default 20)",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "required": [
    "webhook_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

setup_domain_email

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

Parameters2

domain	string	required	Domain to enable email on, e.g. mysite.com
force	boolean	optional	Override existing MX records (e.g. Google Workspace). Default: false

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Domain to enable email on, e.g. mysite.com"
    },
    "force": {
      "description": "Override existing MX records (e.g. Google Workspace). Default: false",
      "type": "boolean"
    }
  },
  "required": [
    "domain"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_domain_email_status

Check if email is enabled on a domain and whether DNS records are verified. Returns record status and mailbox count.

Parameters1

domain

string

required

Domain to check email status for

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Domain to check email status for"
    }
  },
  "required": [
    "domain"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

create_mailbox

Create an email address. Specify slug (required) and optionally domain. For custom domains: email DNS is auto-configured on first use. For imported domains (external registrar): returns DNS records to add manually at your registrar. For domani.run: omit domain. Max 5 mailboxes per account, 1 free @domani.run per user. Pass force=true to override existing email provider (Google Workspace, etc.). API: POST /api/emails with {address}.

Parameters4

domain	string	optional	Domain for the mailbox. Omit for domani.run
slug	string	required	Local part of the email address, e.g. 'hello' for hello@mysite.com
name	string	optional	Display name for outbound emails, e.g. 'John Doe'. Shows as 'John Doe <slug@domain>' in recipients' inboxes
force	boolean	optional	Override existing MX records (e.g. Google Workspace). Default: false

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "description": "Domain for the mailbox. Omit for domani.run",
      "type": "string"
    },
    "slug": {
      "type": "string",
      "description": "Local part of the email address, e.g. 'hello' for hello@mysite.com"
    },
    "name": {
      "description": "Display name for outbound emails, e.g. 'John Doe'. Shows as 'John Doe <slug@domain>' in recipients' inboxes",
      "type": "string"
    },
    "force": {
      "description": "Override existing MX records (e.g. Google Workspace). Default: false",
      "type": "boolean"
    }
  },
  "required": [
    "slug"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

list_mailboxes

List all your email addresses. Optionally filter by domain. API: GET /api/emails (or GET /api/email).

Parameters1

domain

string

optional

Filter by domain, e.g. mysite.com. Omit to list all

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "description": "Filter by domain, e.g. mysite.com. Omit to list all",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

check_email_deliverability

Run the same deliverability and abuse-safety checks used by send_email, without sending or consuming quota. Use this before authentication, payment, onboarding, or high-volume messages. API: POST /api/emails/{address}/deliverability-check.

Parameters8

domain	string	required	Sender mailbox domain, e.g. mysite.com or domani.run
slug	string	required	Sender mailbox slug, e.g. hello
subject	string	optional	Email subject line
text	string	optional	Plain-text body
html	string	optional	HTML body
idempotency_key	string	optional	Stable idempotency key for this logical message
allow_risky_content	boolean	optional	Deprecated compatibility field. Public HTTPS third-party auth links are allowed with a warning; objective safety blocks cannot be overridden
attachments	array	optional	Attachment metadata only; content is not required for preflight

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Sender mailbox domain, e.g. mysite.com or domani.run"
    },
    "slug": {
      "type": "string",
      "description": "Sender mailbox slug, e.g. hello"
    },
    "subject": {
      "description": "Email subject line",
      "type": "string"
    },
    "text": {
      "description": "Plain-text body",
      "type": "string"
    },
    "html": {
      "description": "HTML body",
      "type": "string"
    },
    "idempotency_key": {
      "description": "Stable idempotency key for this logical message",
      "type": "string"
    },
    "allow_risky_content": {
      "description": "Deprecated compatibility field. Public HTTPS third-party auth links are allowed with a warning; objective safety blocks cannot be overridden",
      "type": "boolean"
    },
    "attachments": {
      "description": "Attachment metadata only; content is not required for preflight",
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "filename": {
            "type": "string",
            "description": "Filename with extension"
          },
          "content_type": {
            "description": "MIME type",
            "type": "string"
          }
        },
        "required": [
          "filename"
        ]
      }
    }
  },
  "required": [
    "domain",
    "slug"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

send_email

Send an email from one of your mailboxes. Specify domain and slug to identify the sender mailbox. Supports text and/or HTML body, CC/BCC, attachments (base64), and threading via In-Reply-To/References. Rate limited to 100 sends per hour per mailbox. API: POST /api/emails/{address}/send.

Parameters14

domain	string	required	Sender mailbox domain, e.g. mysite.com or domani.run
slug	string	required	Sender mailbox slug, e.g. hello or k7x9m2
to	any	required	Recipient email address(es)
cc	any	optional	CC recipient(s)
bcc	any	optional	BCC recipient(s)
subject	string	optional	Email subject line
text	string	optional	Plain text body
html	string	optional	HTML body
reply_to	string	optional	Reply-to email address
in_reply_to	string	optional	Message-ID of the email being replied to (for threading)
references	string	optional	Space-separated Message-ID chain (for threading)
attachments	array	optional	File attachments (max 10, max 40MB total)
idempotency_key	string	optional	Unique key to prevent duplicate sends. If a message with this key was already sent from this mailbox, the original result is returned.
allow_risky_content	boolean	optional	Deprecated compatibility field. Public HTTPS third-party auth links are allowed with a warning; objective safety blocks cannot be overridden

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Sender mailbox domain, e.g. mysite.com or domani.run"
    },
    "slug": {
      "type": "string",
      "description": "Sender mailbox slug, e.g. hello or k7x9m2"
    },
    "to": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      ],
      "description": "Recipient email address(es)"
    },
    "cc": {
      "description": "CC recipient(s)",
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      ]
    },
    "bcc": {
      "description": "BCC recipient(s)",
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      ]
    },
    "subject": {
      "description": "Email subject line",
      "type": "string"
    },
    "text": {
      "description": "Plain text body",
      "type": "string"
    },
    "html": {
      "description": "HTML body",
      "type": "string"
    },
    "reply_to": {
      "description": "Reply-to email address",
      "type": "string"
    },
    "in_reply_to": {
      "description": "Message-ID of the email being replied to (for threading)",
      "type": "string"
    },
    "references": {
      "description": "Space-separated Message-ID chain (for threading)",
      "type": "string"
    },
    "attachments": {
      "description": "File attachments (max 10, max 40MB total)",
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "content": {
            "type": "string",
            "description": "Base64-encoded file content"
          },
          "filename": {
            "type": "string",
            "description": "Filename with extension, e.g. report.pdf"
          },
          "content_type": {
            "description": "MIME type (optional, derived from filename)",
            "type": "string"
          }
        },
        "required": [
          "content",
          "filename"
        ]
      }
    },
    "idempotency_key": {
      "description": "Unique key to prevent duplicate sends. If a message with this key was already sent from this mailbox, the original result is returned.",
      "type": "string"
    },
    "allow_risky_content": {
      "description": "Deprecated compatibility field. Public HTTPS third-party auth links are allowed with a warning; objective safety blocks cannot be overridden",
      "type": "boolean"
    }
  },
  "required": [
    "domain",
    "slug",
    "to"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

list_email_messages

List messages in a system folder or virtual view. Defaults to Inbox. Supports pagination, direction and search filters. API: GET /api/emails/{address}/messages.

Parameters11

domain	string	required	Mailbox domain
slug	string	required	Mailbox slug
cursor	string	optional	Pagination cursor from previous response
limit	number	optional	Max messages to return (default 20, max 100)
direction	string	optional	Filter by direction: 'in' for received, 'out' for sent
folder	string	optional	System folder. Mutually exclusive with view. Defaults to inbox
view	string	optional	Virtual view. Mutually exclusive with folder
from	string	optional	Filter by sender address (case-insensitive, partial match)
to	string	optional	Filter by recipient address (case-insensitive, partial match)
subject	string	optional	Filter by subject (case-insensitive, partial match)
spam	boolean	optional	Filter by spam flag. Pass false to hide spam-flagged inbound; omit to include all.

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Mailbox domain"
    },
    "slug": {
      "type": "string",
      "description": "Mailbox slug"
    },
    "cursor": {
      "description": "Pagination cursor from previous response",
      "type": "string"
    },
    "limit": {
      "description": "Max messages to return (default 20, max 100)",
      "type": "number"
    },
    "direction": {
      "description": "Filter by direction: 'in' for received, 'out' for sent",
      "type": "string",
      "enum": [
        "in",
        "out"
      ]
    },
    "folder": {
      "description": "System folder. Mutually exclusive with view. Defaults to inbox",
      "type": "string",
      "enum": [
        "inbox",
        "archive",
        "sent",
        "spam",
        "trash"
      ]
    },
    "view": {
      "description": "Virtual view. Mutually exclusive with folder",
      "type": "string",
      "enum": [
        "starred",
        "all"
      ]
    },
    "from": {
      "description": "Filter by sender address (case-insensitive, partial match)",
      "type": "string"
    },
    "to": {
      "description": "Filter by recipient address (case-insensitive, partial match)",
      "type": "string"
    },
    "subject": {
      "description": "Filter by subject (case-insensitive, partial match)",
      "type": "string"
    },
    "spam": {
      "description": "Filter by spam flag. Pass false to hide spam-flagged inbound; omit to include all.",
      "type": "boolean"
    }
  },
  "required": [
    "domain",
    "slug"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

list_email_folders

List canonical mailbox folders, virtual views, server-derived total/unread counts, and backend capabilities. API: GET /api/emails/{address}/folders.

Parameters2

domain	string	required	Mailbox domain
slug	string	required	Mailbox slug

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Mailbox domain"
    },
    "slug": {
      "type": "string",
      "description": "Mailbox slug"
    }
  },
  "required": [
    "domain",
    "slug"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

update_email_messages

Apply a reversible mailbox lifecycle action to up to 100 messages, or permanently delete messages already in Trash with email:delete. API: POST /api/emails/{address}/messages/actions.

Parameters7

domain	string	required	Mailbox domain
slug	string	required	Mailbox slug
message_ids	array	required	Explicit message IDs
action	string	required
destination	string	optional	Required for move
read	boolean	optional	Required for mark_read
starred	boolean	optional	Required for star

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Mailbox domain"
    },
    "slug": {
      "type": "string",
      "description": "Mailbox slug"
    },
    "message_ids": {
      "minItems": 1,
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Explicit message IDs"
    },
    "action": {
      "type": "string",
      "enum": [
        "move",
        "mark_read",
        "star",
        "restore",
        "delete_permanently"
      ]
    },
    "destination": {
      "description": "Required for move",
      "type": "string",
      "enum": [
        "inbox",
        "archive",
        "sent",
        "spam",
        "trash"
      ]
    },
    "read": {
      "description": "Required for mark_read",
      "type": "boolean"
    },
    "starred": {
      "description": "Required for star",
      "type": "boolean"
    }
  },
  "required": [
    "domain",
    "slug",
    "message_ids",
    "action"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_message

Get a single message by ID with full content, headers, delivery events, and attachment download URLs. API: GET /api/emails/{address}/messages/{id}.

Parameters3

domain	string	required	Mailbox domain
slug	string	required	Mailbox slug
message_id	string	required	Message ID

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Mailbox domain"
    },
    "slug": {
      "type": "string",
      "description": "Mailbox slug"
    },
    "message_id": {
      "type": "string",
      "description": "Message ID"
    }
  },
  "required": [
    "domain",
    "slug",
    "message_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

set_email_webhook

Set or remove the inbound webhook URL for a mailbox. When set, incoming emails are POSTed to this URL in real-time with HMAC-SHA256 signing. Must be HTTPS. Set to null to remove. API: PUT /api/emails/{address}/webhook or DELETE /api/emails/{address}/webhook.

Parameters3

domain	string	required	Mailbox domain
slug	string	required	Mailbox slug
webhook_url	any	required	HTTPS webhook URL, or null to remove

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Mailbox domain"
    },
    "slug": {
      "type": "string",
      "description": "Mailbox slug"
    },
    "webhook_url": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "HTTPS webhook URL, or null to remove"
    }
  },
  "required": [
    "domain",
    "slug",
    "webhook_url"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

rotate_email_webhook_secret

Regenerate the HMAC signing secret for a mailbox webhook. The old secret is immediately invalidated. API: POST /api/emails/{address}/webhook/rotate.

Parameters2

domain	string	required	Mailbox domain
slug	string	required	Mailbox slug

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Mailbox domain"
    },
    "slug": {
      "type": "string",
      "description": "Mailbox slug"
    }
  },
  "required": [
    "domain",
    "slug"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

test_email_webhook

Send a signed test payload to the mailbox webhook URL. Returns HTTP status and success/failure. API: POST /api/emails/{address}/webhook/test.

Parameters2

domain	string	required	Mailbox domain
slug	string	required	Mailbox slug

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Mailbox domain"
    },
    "slug": {
      "type": "string",
      "description": "Mailbox slug"
    }
  },
  "required": [
    "domain",
    "slug"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

set_email_forward

Configure inbound handling for a mailbox: forward incoming emails to another address (in addition to storing) and/or drop spam-flagged messages. Set forward_to to null to remove forwarding. API: PATCH /api/emails/{address}.

Parameters4

domain	string	required	Mailbox domain
slug	string	required	Mailbox slug
forward_to	any	optional	Email address to forward to, or null to remove
drop_spam	boolean	optional	If true, spam-flagged inbound is dropped (not stored or webhooked)

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Mailbox domain"
    },
    "slug": {
      "type": "string",
      "description": "Mailbox slug"
    },
    "forward_to": {
      "description": "Email address to forward to, or null to remove",
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "drop_spam": {
      "description": "If true, spam-flagged inbound is dropped (not stored or webhooked)",
      "type": "boolean"
    }
  },
  "required": [
    "domain",
    "slug"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

add_mailbox_alias

Add an alias address that delivers into an existing mailbox, without using a mailbox slot. Useful for multiple public addresses (sales@, hello@, contact@) landing in one inbox. The alias must be on the same domain as the mailbox. API: POST /api/emails/{address}/aliases.

Parameters3

domain	string	required	Mailbox domain, e.g. mysite.com
slug	string	required	Mailbox slug the alias delivers to, e.g. inbox
alias	string	required	Alias address - a bare slug ('sales') or a full address on the same domain ('sales@mysite.com')

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Mailbox domain, e.g. mysite.com"
    },
    "slug": {
      "type": "string",
      "description": "Mailbox slug the alias delivers to, e.g. inbox"
    },
    "alias": {
      "type": "string",
      "description": "Alias address - a bare slug ('sales') or a full address on the same domain ('sales@mysite.com')"
    }
  },
  "required": [
    "domain",
    "slug",
    "alias"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

list_mailbox_aliases

List all alias addresses that deliver into a mailbox. API: GET /api/emails/{address}/aliases.

Parameters2

domain	string	required	Mailbox domain
slug	string	required	Mailbox slug

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Mailbox domain"
    },
    "slug": {
      "type": "string",
      "description": "Mailbox slug"
    }
  },
  "required": [
    "domain",
    "slug"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

remove_mailbox_alias

Remove an alias address from a mailbox. Email to that address stops being delivered. API: DELETE /api/emails/{address}/aliases/{alias}.

Parameters3

domain	string	required	Mailbox domain
slug	string	required	Mailbox slug
alias	string	required	Alias address to remove - a bare slug or full address

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Mailbox domain"
    },
    "slug": {
      "type": "string",
      "description": "Mailbox slug"
    },
    "alias": {
      "type": "string",
      "description": "Alias address to remove - a bare slug or full address"
    }
  },
  "required": [
    "domain",
    "slug",
    "alias"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

set_catch_all

Route any email sent to an unmatched address on a 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. API: PUT /api/domains/{domain}/email/catch-all.

Parameters2

domain	string	required	Domain to set the catch-all on, e.g. mysite.com
mailbox	string	required	Catch-all mailbox - a bare slug ('inbox') or full address ('inbox@mysite.com') on this domain

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Domain to set the catch-all on, e.g. mysite.com"
    },
    "mailbox": {
      "type": "string",
      "description": "Catch-all mailbox - a bare slug ('inbox') or full address ('inbox@mysite.com') on this domain"
    }
  },
  "required": [
    "domain",
    "mailbox"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

clear_catch_all

Remove the catch-all on a domain. Email to unmatched addresses will be dropped again. API: DELETE /api/domains/{domain}/email/catch-all.

Parameters1

domain

string

required

Domain to clear the catch-all on

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Domain to clear the catch-all on"
    }
  },
  "required": [
    "domain"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

list_suppressions

List addresses on your suppression list - hard bounces and complaints (added automatically) plus manual entries. Sends to these addresses are skipped. API: GET /api/suppressions.

Parameters2

cursor	string	optional	Pagination cursor from a previous response
limit	number	optional	Max entries to return (default 50, max 100)

Raw schema

{
  "type": "object",
  "properties": {
    "cursor": {
      "description": "Pagination cursor from a previous response",
      "type": "string"
    },
    "limit": {
      "description": "Max entries to return (default 50, max 100)",
      "type": "number"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

add_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. API: POST /api/suppressions.

Parameters2

address	string	required	Email address to suppress
reason	string	optional	Reason (default: manual)

Raw schema

{
  "type": "object",
  "properties": {
    "address": {
      "type": "string",
      "description": "Email address to suppress"
    },
    "reason": {
      "description": "Reason (default: manual)",
      "type": "string",
      "enum": [
        "manual",
        "hard_bounce",
        "complaint"
      ]
    }
  },
  "required": [
    "address"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

remove_suppression

Remove an address from your suppression list so you can email it again (e.g. after the recipient fixed their mailbox). API: DELETE /api/suppressions/{address}.

Parameters1

address

string

required

Email address to remove from the suppression list

Raw schema

{
  "type": "object",
  "properties": {
    "address": {
      "type": "string",
      "description": "Email address to remove from the suppression list"
    }
  },
  "required": [
    "address"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

add_mail_rule

Add an inbound filtering rule to a mailbox. If a message matches (by from/to/subject/body), the action runs: drop, mark_read, forward (to action_arg), webhook_only (skip forward-to), or label (with action_arg). Rules run in priority order (lower first); first match wins. API: POST /api/emails/{address}/rules.

Parameters9

domain	string	required	Mailbox domain
slug	string	required	Mailbox slug
match_field	string	required	Which field to match on
match_op	string	required	How to match
match_value	string	required	The value/pattern to match
action	string	required	What to do on match
action_arg	string	optional	For 'forward': the destination email. For 'label': the label value.
priority	integer	optional	Lower runs first (default 0)
enabled	boolean	optional	Default true

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Mailbox domain"
    },
    "slug": {
      "type": "string",
      "description": "Mailbox slug"
    },
    "match_field": {
      "type": "string",
      "enum": [
        "from",
        "to",
        "subject",
        "body"
      ],
      "description": "Which field to match on"
    },
    "match_op": {
      "type": "string",
      "enum": [
        "contains",
        "equals",
        "regex"
      ],
      "description": "How to match"
    },
    "match_value": {
      "type": "string",
      "description": "The value/pattern to match"
    },
    "action": {
      "type": "string",
      "enum": [
        "drop",
        "mark_read",
        "forward",
        "webhook_only",
        "label"
      ],
      "description": "What to do on match"
    },
    "action_arg": {
      "description": "For 'forward': the destination email. For 'label': the label value.",
      "type": "string"
    },
    "priority": {
      "description": "Lower runs first (default 0)",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "enabled": {
      "description": "Default true",
      "type": "boolean"
    }
  },
  "required": [
    "domain",
    "slug",
    "match_field",
    "match_op",
    "match_value",
    "action"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

list_mail_rules

List a mailbox's inbound filtering rules, in the priority order they are applied. API: GET /api/emails/{address}/rules.

Parameters2

domain	string	required	Mailbox domain
slug	string	required	Mailbox slug

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Mailbox domain"
    },
    "slug": {
      "type": "string",
      "description": "Mailbox slug"
    }
  },
  "required": [
    "domain",
    "slug"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

remove_mail_rule

Remove an inbound filtering rule from a mailbox. API: DELETE /api/emails/{address}/rules/{ruleId}.

Parameters3

domain	string	required	Mailbox domain
slug	string	required	Mailbox slug
rule_id	string	required	The rule ID to remove

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Mailbox domain"
    },
    "slug": {
      "type": "string",
      "description": "Mailbox slug"
    },
    "rule_id": {
      "type": "string",
      "description": "The rule ID to remove"
    }
  },
  "required": [
    "domain",
    "slug",
    "rule_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

delete_mailbox

Delete a mailbox and all its messages (including attachments). Requires confirm=true. Call without confirm first to see what will be deleted. API: DELETE /api/emails/{address}.

Parameters3

domain	string	required	Mailbox domain
slug	string	required	Mailbox slug
confirm	boolean	optional	Must be true to actually delete. Omit to preview.

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Mailbox domain"
    },
    "slug": {
      "type": "string",
      "description": "Mailbox slug"
    },
    "confirm": {
      "description": "Must be true to actually delete. Omit to preview.",
      "type": "boolean"
    }
  },
  "required": [
    "domain",
    "slug"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

mark_messages_read

Mark one or more messages as read or unread. Useful for tracking which messages have been processed by your agent. API: PATCH /api/emails/{address}/messages/read.

Parameters4

domain	string	required	Mailbox domain
slug	string	required	Mailbox slug
message_ids	array	required	IDs of messages to mark
read	boolean	required	true = mark as read, false = mark as unread

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Mailbox domain"
    },
    "slug": {
      "type": "string",
      "description": "Mailbox slug"
    },
    "message_ids": {
      "minItems": 1,
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "IDs of messages to mark"
    },
    "read": {
      "type": "boolean",
      "description": "true = mark as read, false = mark as unread"
    }
  },
  "required": [
    "domain",
    "slug",
    "message_ids",
    "read"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

delete_message

Move an email message to Trash. This is reversible with update_email_messages action=restore. API: DELETE /api/emails/{address}/messages/{id}.

Parameters3

domain	string	required	Mailbox domain
slug	string	required	Mailbox slug
message_id	string	required	ID of the message to delete

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Mailbox domain"
    },
    "slug": {
      "type": "string",
      "description": "Mailbox slug"
    },
    "message_id": {
      "type": "string",
      "description": "ID of the message to delete"
    }
  },
  "required": [
    "domain",
    "slug",
    "message_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

delete_messages

Move multiple messages to Trash. This is reversible with update_email_messages action=restore. API: POST /api/emails/{address}/messages/delete.

Parameters3

domain	string	required	Mailbox domain
slug	string	required	Mailbox slug
message_ids	array	required	IDs of messages to delete

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Mailbox domain"
    },
    "slug": {
      "type": "string",
      "description": "Mailbox slug"
    },
    "message_ids": {
      "minItems": 1,
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "IDs of messages to delete"
    }
  },
  "required": [
    "domain",
    "slug",
    "message_ids"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

forward_message

Forward an email message to another address. Includes the original message context (sender, date, subject, body). Optionally prepend a note. Subject is auto-prefixed with 'Fwd:'. API: POST /api/emails/{address}/messages/{id}/forward.

Parameters5

domain	string	required	Mailbox domain
slug	string	required	Mailbox slug
message_id	string	required	ID of the message to forward
to	any	required	Recipient email address(es)
text	string	optional	Optional note to prepend to the forwarded message

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Mailbox domain"
    },
    "slug": {
      "type": "string",
      "description": "Mailbox slug"
    },
    "message_id": {
      "type": "string",
      "description": "ID of the message to forward"
    },
    "to": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      ],
      "description": "Recipient email address(es)"
    },
    "text": {
      "description": "Optional note to prepend to the forwarded message",
      "type": "string"
    }
  },
  "required": [
    "domain",
    "slug",
    "message_id",
    "to"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

reply_to_message

Reply to an email message. Automatically sets To (from Reply-To or sender), Subject (Re: prefix), In-Reply-To and References headers for proper threading. Use all=true for reply-all (auto-populates CC from original recipients, excluding your own address). API: POST /api/emails/{address}/messages/{id}/reply.

Parameters7

domain	string	required	Mailbox domain
slug	string	required	Mailbox slug
message_id	string	required	ID of the message to reply to
text	string	optional	Plain text reply body
html	string	optional	HTML reply body
cc	any	optional	Additional CC recipients (overrides auto-CC when all=true)
all	boolean	optional	Reply-all: auto-CC original To and CC recipients (default: false)

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Mailbox domain"
    },
    "slug": {
      "type": "string",
      "description": "Mailbox slug"
    },
    "message_id": {
      "type": "string",
      "description": "ID of the message to reply to"
    },
    "text": {
      "description": "Plain text reply body",
      "type": "string"
    },
    "html": {
      "description": "HTML reply body",
      "type": "string"
    },
    "cc": {
      "description": "Additional CC recipients (overrides auto-CC when all=true)",
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      ]
    },
    "all": {
      "description": "Reply-all: auto-CC original To and CC recipients (default: false)",
      "type": "boolean"
    }
  },
  "required": [
    "domain",
    "slug",
    "message_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

check_email

Check email DNS health for a domain: MX records, SPF, DMARC, DKIM. Auto-detects the email provider from MX records.

Parameters1

domain

string

required

Domain to check email health for

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Domain to check email health for"
    }
  },
  "required": [
    "domain"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_email_deliverability

Get an owner-scoped email health report for a domain. Separates deterministic DNS readiness, 30-day bounce and complaint outcomes, account safety state, and measured inbox placement. A readiness score is not an Inbox probability. API: GET /api/domains/{domain}/email/deliverability.

Parameters1

domain

string

required

Domain to inspect

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Domain to inspect"
    }
  },
  "required": [
    "domain"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

create_hosted_mailbox

Create a real IMAP/SMTP mailbox on a domain you own (connect Apple Mail, Thunderbird, or any mail client), instead of an API mailbox. Provisions the mailbox on our mail server, publishes DNS when we manage it, and returns the DNS records, mail client settings, and a one-time app password. Requires a domain in your account. API: POST /api/emails with kind=hosted.

Parameters3

domain	string	required	A domain you own, e.g. mysite.com
slug	string	required	Local part, e.g. 'me' for me@mysite.com
name	string	optional	Display name for the mailbox

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "A domain you own, e.g. mysite.com"
    },
    "slug": {
      "type": "string",
      "description": "Local part, e.g. 'me' for me@mysite.com"
    },
    "name": {
      "description": "Display name for the mailbox",
      "type": "string"
    }
  },
  "required": [
    "domain",
    "slug"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_mailbox_client_settings

Get IMAP/SMTP settings for a hosted mailbox to configure a mail client (Apple Mail, Thunderbird). Username is the full address; password is an app password. API: GET /api/emails/{address}/client-settings.

Parameters2

domain	string	required	Hosted mailbox domain
slug	string	required	Hosted mailbox slug

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Hosted mailbox domain"
    },
    "slug": {
      "type": "string",
      "description": "Hosted mailbox slug"
    }
  },
  "required": [
    "domain",
    "slug"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

create_mailbox_credential

Create an app password for a hosted mailbox, used as the password in a mail client. The secret is returned once - store it. API: POST /api/emails/{address}/credentials.

Parameters3

domain	string	required	Hosted mailbox domain
slug	string	required	Hosted mailbox slug
label	string	optional	Label to identify this app password, e.g. 'Laptop Mail'

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Hosted mailbox domain"
    },
    "slug": {
      "type": "string",
      "description": "Hosted mailbox slug"
    },
    "label": {
      "description": "Label to identify this app password, e.g. 'Laptop Mail'",
      "type": "string"
    }
  },
  "required": [
    "domain",
    "slug"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

list_mailbox_credentials

List the app passwords for a hosted mailbox (labels + metadata; secrets are shown only once at creation). API: GET /api/emails/{address}/credentials.

Parameters2

domain	string	required	Hosted mailbox domain
slug	string	required	Hosted mailbox slug

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Hosted mailbox domain"
    },
    "slug": {
      "type": "string",
      "description": "Hosted mailbox slug"
    }
  },
  "required": [
    "domain",
    "slug"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

revoke_mailbox_credential

Revoke an app password on a hosted mailbox. Any mail client using it stops connecting. API: DELETE /api/emails/{address}/credentials/{id}.

Parameters3

domain	string	required	Hosted mailbox domain
slug	string	required	Hosted mailbox slug
credential_id	string	required	App password id from list_mailbox_credentials

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Hosted mailbox domain"
    },
    "slug": {
      "type": "string",
      "description": "Hosted mailbox slug"
    },
    "credential_id": {
      "type": "string",
      "description": "App password id from list_mailbox_credentials"
    }
  },
  "required": [
    "domain",
    "slug",
    "credential_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

README.md13 KBView on GitHub

domani

Domains and email - for humans and AI agents.

How it works

domani gives you one account and multiple ways in:

Web - Dashboard with a full inbox (compose, reply, threads), DNS editor, domain management
CLI - This package. Everything the web app does, from your terminal
MCP Server - typed tools for Claude Code, Cursor, Codex, and any MCP-compatible agent
OpenClaw - openclaw skills install @gwendall/domani
Agent Skill - Step-by-step guide your agent can follow. Install with npx skills add domani.run
REST API - Direct HTTP access to everything

All interfaces share the same API key and the same data.

Install

bash

npm install -g domani-cli

Secure MCP bridge

Agent plugins can use Domani without placing an API key in a prompt, shell history, or editor configuration:

bash

domani login --surface mcp
domani mcp serve

domani login stores the credential in the operating-system keychain when one is available. The stdio bridge resolves it locally and forwards MCP requests to https://domani.run/mcp; stdout remains reserved for JSON-RPC messages.

For an agent acting on someone else's behalf, request a scoped, expiring credential instead of their account key:

bash

domani login --scopes domains:read,search --label "Project agent" --expires-in 86400

The approval screen shows the requested access and the resulting credential is stored in the keychain without being printed.

After login, prove one complete inbound loop before browsing other tools or buying a domain:

bash

domani email create myagent@domani.run
domani email webhook myagent@domani.run --url https://my-agent.example/webhook
domani email webhook-test myagent@domani.run

Use --surface plugin, --surface skill, or --surface api when that is the entry point. This keeps activation attribution consistent without exposing a credential.

This installs the domani command. Or run directly with npx:

bash

npx domani-cli search myapp .com .dev .ai

Quick start

bash

# Domain
domani search myapp .com .io .dev     # Check availability
domani buy myapp.dev                  # Purchase a domain
domani connect myapp.dev vercel       # Auto-configure DNS for Vercel

# Email
domani email create hello@myapp.dev               # Create hello@myapp.dev
domani email send hello@myapp.dev \
  --to hi@friend.com --subject "Hello" --body "Sent from my terminal"
domani email forward hello@myapp.dev \
  --forward-to me@gmail.com                        # Forward inbound to personal email

# Health
domani status myapp.dev               # DNS, SSL, email, expiry check

Examples

bash

# Find available domains with a budget
domani search startup --expand --max-price 20

# AI-powered name suggestions
domani suggest "minimalist productivity app" --style brandable --tlds com,dev,ai

# Buy multiple domains at once
domani buy startup.dev startup.ai --yes

# Set up Vercel + Google Workspace in two commands
domani connect startup.dev vercel
domani connect startup.dev google-workspace

# Full email workflow: create, send, check inbox, forward
domani email create hello@startup.dev
domani email send hello@startup.dev \
  --to investor@vc.com --subject "Deck" --body "Here's our deck."
domani email inbox hello@startup.dev --direction in
domani email forward hello@startup.dev --forward-to me@gmail.com

# Webhook for inbound emails (for bots, support systems, etc.)
# CURSOR_AUTH contains the complete value, e.g. "Bearer sender-key"
domani email webhook hello@startup.dev --url https://myapp.dev/hooks/email \
  --authorization-env CURSOR_AUTH
domani email webhook-test hello@startup.dev

# Provision domain + mailbox + authenticated event webhook in one call.
# The secret stays in the environment; only its variable name is in argv.
AGENT_AUTH="Bearer sender-key" domani provision agent.dev \
  --webhook https://agent.example/inbox --authorization-env AGENT_AUTH

# Export DNS records before making changes
domani dns startup.dev snapshot
domani dns startup.dev set TXT @ "v=spf1 include:_spf.google.com ~all"

# Pipe to jq (auto-JSON when piped, no --json needed)
domani list | jq '.domains[] | {domain, expires_at}'

# Introspect command schemas for agent integration
domani schema buy --json

Commands

Domains

code

domani search <name> [tlds...]    Check availability across TLDs (--expand for 30+)
domani suggest <prompt>           AI-powered domain suggestions (--style, --lang, --tlds)
domani buy <domains...>           Purchase one or more domains
domani adopt <domain>             Inspect and plan a safe connection or transfer
domani transfer <domain>          Transfer registration, preserving current nameservers
domani renew <domain>             Renew a domain (--years 1-10)
domani import <domain>            Import a domain you own elsewhere (DNS monitoring only)
domani list                       List your domains
domani status <domain>            Health check (DNS, SSL, email, expiry)
domani tlds                       List all TLDs with pricing (--sort, --max-price)
domani whois <domain>             WHOIS/RDAP lookup

Email

code

domani email list                    List all mailboxes
domani email create user@domain      Create a mailbox
domani email delete user@domain      Delete a mailbox
domani email inbox user@domain       List messages (--folder, --view, --direction)
domani email folders user@domain     List folder and view counts
domani email archive user@domain --message-ids m1,m2
domani email trash user@domain --message-ids m1
domani email restore user@domain --message-ids m1
domani email read|unread|star|unstar user@domain --message-ids m1,m2
domani email send user@domain        Send an email (--to, --subject, --body, --cc, --bcc)
domani email forward user@domain     Forward inbound to a personal address (--forward-to)
domani email webhook user@domain     Forward inbound as JSON (--url, --authorization-env, --api-key-env, --clear-headers)
domani email webhook-test user@domain Deliver one signed test event to the configured webhook
domani email setup --domain <domain>       Auto-configure MX, SPF, DKIM, DMARC
domani email status --domain <domain>      Check email DNS health
domani email connect --domain <domain> <provider>   Connect external provider (Gmail, Fastmail, Proton)

Mailzero assistant (private preview)

code

domani assistant today               Now, Needs you, Waiting, Upcoming, Handled
domani assistant settings            Opt-in state, consent, and mailbox scope
domani assistant set                 Change settings (--enable, --shadow, --pause, --mailboxes, --none, --days)
domani assistant preview             Record consent and start a background history import (--mailboxes, --consent)
domani assistant backfill|retry      Follow the import or requeue its terminal failures
domani assistant item <id>           One work item with its Decision and options
domani assistant choose <id>         Record a decision (--item-version, --decision, --decision-version, --option)
domani assistant instruct|snooze|ignore|take-over|correct <id>
domani assistant plan <id>           Exact preview of a prepared reply; nothing is sent by the CLI
domani assistant activity            Content-free interaction and receipt log
domani assistant rules               The standing delegations (match, assignee, level, grants)
domani assistant approvals           The plans waiting for you and the questions your agents asked
domani assistant suggestions         The rules the assistant proposes from what recurred
domani assistant metrics             The seven numbers per account and per rule (--days)
domani assistant task <id>           The task envelope an assignee works from
domani assistant lease|release|effects|escalate|report <id>
domani assistant export|delete       Export or delete derived data (source mail is never touched)

Tokens need assistant:read for reads and assistant:write for changes.

DNS

code

domani dns <domain> get            List all DNS records
domani dns <domain> set <type> <name> <value>   Add/update a record
domani dns <domain> delete <type> <name>        Remove a record
domani dns <domain> snapshot       Export DNS to file
domani dns <domain> restore        Restore DNS from snapshot
domani nameservers <domain>        Get or set nameservers (--reset for defaults)
domani connect <domain> <target>   Auto-configure DNS for a provider

Supported providers: Vercel, Netlify, Cloudflare Pages, GitHub Pages, Fly.io, Railway, Render, Google Workspace, Fastmail, Proton Mail.

Settings

code

domani settings <domain>           View/update auto-renew, WHOIS privacy, security lock
domani contact [view|set]          Manage WHOIS contact info
domani parking <domain>            Manage parking page (enable/disable/price)
domani analytics <domain>          View parking analytics
domani auth-code <domain>          Get EPP auth code for outbound transfer
domani transfer-away <domain>      Check outbound transfer status

Account

code

domani login                       Log in to domani.run (opens browser)
domani logout                      Clear saved credentials
domani me                          Show account info
domani billing                     Add or update payment method (opens browser)
domani invoices                    List payment invoices
domani token                       Print your API key
domani tokens [list|create|revoke] Manage API tokens (scoped, expiring)
domani webhooks [action]           Manage webhook endpoints (auth headers via --authorization-env/--api-key-env)

Introspection

code

domani schema [command]            Show command schemas for AI agent integration
domani update                      Update to the latest version
domani uninstall                   Remove domani CLI and config

Agent integration

Built for AI agents and scripts, not just humans.

TTY auto-detect: When stdout is not a terminal, the CLI automatically switches to JSON output and skips confirmation prompts. No --json flag needed.

bash

domani list | jq '.domains[].domain'

Structured errors: In JSON mode, errors include code, hint, and fix_command for auto-recovery:

json

{ "error": "Not logged in", "code": "auth_required", "fix_command": "domani login" }

Code	Fix	Description
`auth_required`	`domani login`	Not logged in
`payment_required`	`domani billing`	No payment method on file
`contact_required`	`domani contact set`	WHOIS contact info missing
`validation_error`	Read `hint`	Invalid input
`not_found`	-	Domain doesn't exist or not owned
`rate_limited`	Wait `Retry-After`	Too many requests

Flags:

Flag	Description
`--json`	Force JSON output
`--fields <f>`	Filter JSON fields (comma-separated)
`--dry-run`	Preview mutations without executing
`--yes`	Skip confirmation prompts

Input hardening: All inputs are validated against path traversal, control characters, query strings, and double encoding - common agent hallucinations.

Schema introspection: Run domani schema <command> --json to get parameter types, constraints, and enums before constructing a command.

Payments

Domains are charged to your saved card. Add one at domani.run/dashboard or with domani card add.

bash

domani buy myapp.dev                     # Charged to saved card

Authentication

Method	Description
`domani login`	Interactive login (opens browser)
`$DOMANI_API_KEY`	API key as environment variable
OS keychain	Credential saved by `domani login` when available
`~/.domani/config.json`	Non-secret CLI settings, plus legacy fallback on systems without a keychain

The CLI checks $DOMANI_API_KEY first, then falls back to ~/.domani/config.json.

bash

domani login                             # Interactive (opens browser)
export DOMANI_API_KEY=domani_sk_...      # Or set env var

Scoped API tokens can be created with domani tokens create --scopes read,dns --expires-in 86400.

Environment variables

Variable	Description
`DOMANI_API_KEY`	API key (takes precedence over saved config)

License

MIT

Install

Tools (119)

get_accountsearchsuggest_domainslist_tldsdns_checkbuy_domainbuy_aftermarketprovision_agent

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://domani.run/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "domani": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://domani.run/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.