Mail API reference

Mail API.

48 endpoints, 19 of them read-only. Every one is also a command in the orbit CLI, a method in the SDKs and a tool on the MCP server.

domains

Endpoint	Scope	Parameters	CLI · MCP tool
`GET /mail/domains` Domains set up for mail forwarding	read	—	`orbit mail domains list` `mail_domains_list`
`POST /mail/domains` Start accepting mail for a zone (publishes MX, SPF, DKIM, DMARC and the TLS policy)	write	body: `zone_id` integer, `server_id` string, `name` string, `zone_name` string, `mode` mailbox \| forward \| both	`orbit mail domains create` `mail_domains_create`
`GET /mail/domains/{id}` One domain, with the records we publish for it	read	`id` integer	`orbit mail domains get <id>` `mail_domains_get`
`PATCH /mail/domains/{id}` Enable/disable, or set the catch-all	write	`id` integer body: `enabled` boolean, `catch_all` string, `mode` mailbox \| forward \| both, `default_quota_bytes` integer, `dmarc_policy` none \| quarantine \| reject, `backup_enabled` boolean	`orbit mail domains patch <id>` `mail_domains_patch`
`DELETE /mail/domains/{id}` Stop accepting mail and remove the published records	write	`id` integer	`orbit mail domains delete <id>` `mail_domains_delete`
`GET /mail/domains/{id}/records` The wizard's records, as last checked (BYO) or published (legacy)	read	`id` integer	`orbit mail domains records <id>` `mail_domains_records`
`POST /mail/domains/{id}/records` Publish the mail records again	write	`id` integer	`orbit mail domains republish <id>` `mail_domains_republish`
`POST /mail/domains/{id}/check` Re-check the domain's records against public DNS right now (BYO only)	write	`id` integer	`orbit mail domains check <id>` `mail_domains_check`

routes

Endpoint	Scope	Parameters	CLI · MCP tool
`GET /mail/domains/{id}/routes` Forwarding rules	read	`id` integer	`orbit mail routes list <id>` `mail_routes_list`
`PUT /mail/domains/{id}/routes` Add or change a forwarding rule	write	`id` integer body: `local_part`* string, `dest`* string	`orbit mail routes put <id>` `mail_routes_put`
`DELETE /mail/domains/{id}/routes/{local}` Remove a forwarding rule	write	`id` integer `local` string	`orbit mail routes delete <id> <local>` `mail_routes_delete`

destinations

Endpoint	Scope	Parameters	CLI · MCP tool
`GET /mail/destinations` Addresses mail may be forwarded to	read	—	`orbit mail destinations list` `mail_destinations_list`
`POST /mail/destinations` Add a destination; a confirmation link is sent to it	write	body: `addr`* string	`orbit mail destinations create` `mail_destinations_create`
`DELETE /mail/destinations/{addr}` Remove a destination	write	`addr` string	`orbit mail destinations delete <addr>` `mail_destinations_delete`

General

Endpoint	Scope	Parameters	CLI · MCP tool
`GET /mail/domains/{id}/log` Recent envelopes and verdicts (never subjects or bodies)	read	`id` integer `?verdict` delivered \| rejected \| deferred \| dropped `?limit` integer	`orbit mail log <id>` `mail_log`
`GET /mail/domains/{id}/stats` Hourly counters	read	`id` integer `?days` integer	`orbit mail stats <id>` `mail_stats`
`GET /mail/servers/{id}/deliverability` PTR / outbound port 25 / SPF / DKIM / DMARC, and advice	read	`id` string	`orbit mail deliverability <id>` `mail_deliverability`
`POST /mail/send` Queue an outbound message; the node picks it up, signs it (DKIM) and delivers it	write	body: `mailbox_id`* string, `to`* string[], `cc` string[], `bcc` string[], `subject`* string, `text` string, `html` string, `attachments` object[], `in_reply_to` string	`orbit mail send` `mail_send`

servers

Endpoint	Scope	Parameters	CLI · MCP tool
`GET /mail/servers` Your BYO mail servers	read	—	`orbit mail servers list` `mail_servers_list`
`POST /mail/servers` Register a server and get its install command	write	body: `name`* string, `ip4`* string, `ip6` string	`orbit mail servers create` `mail_servers_create`
`GET /mail/servers/{id}` One server, with its last self-check	read	`id` string	`orbit mail servers get <id>` `mail_servers_get`
`DELETE /mail/servers/{id}` Remove a server (its domains must be removed first)	write	`id` string	`orbit mail servers delete <id>` `mail_servers_delete`
`POST /mail/servers/{id}/token` Invalidate the current session and get a fresh install command	write	`id` string	`orbit mail servers regenerate_token <id>` `mail_servers_regenerate_token`

mailboxes

Endpoint	Scope	Parameters	CLI · MCP tool
`GET /mail/domains/{domain_id}/mailboxes` Mailboxes on one domain	read	`domain_id` integer	`orbit mail mailboxes list <domain_id>` `mail_mailboxes_list`
`POST /mail/domains/{domain_id}/mailboxes` Create a mailbox	write	`domain_id` integer body: `domain_id`* integer, `local`* string, `display` string, `quota_bytes` integer	`orbit mail mailboxes create <domain_id>` `mail_mailboxes_create`
`PATCH /mail/mailboxes/{id}` Rename, requota, enable/disable	write	`id` string body: `display` string, `quota_bytes` integer, `state` active \| disabled, `user_email` string, `send_limit_hour` integer, `shared_with` string[], `collab` boolean	`orbit mail mailboxes patch <id>` `mail_mailboxes_patch`
`DELETE /mail/mailboxes/{id}` Delete a mailbox and its index	write	`id` string	`orbit mail mailboxes delete <id>` `mail_mailboxes_delete`
`POST /mail/domains/{id}/mailboxes/import` Create mailboxes in bulk (rows, or a CSV of local,display,quota_bytes)	write	`id` integer body: `rows` object[], `csv` string	`orbit mail mailboxes import <id>` `mail_mailboxes_import`

apppasswords

Endpoint	Scope	Parameters	CLI · MCP tool
`POST /mail/mailboxes/{id}/apppasswords` Issue an application password (shown once)	write	`id` string body: `mailbox_id`* string, `label` string	`orbit mail apppasswords create <id>` `mail_apppasswords_create`
`DELETE /mail/apppasswords/{id}` Revoke an application password	write	`id` string	`orbit mail apppasswords revoke <id>` `mail_apppasswords_revoke`

messages

Endpoint	Scope	Parameters	CLI · MCP tool
`GET /mail/mailboxes/{id}/messages` A mailbox's index (headers and a verdict, never a body)	read	`id` string `?folder` string `?q` string `?cursor` string `?limit` integer	`orbit mail messages list <id>` `mail_messages_list`
`GET /mail/messages/{id}` One message: the index row plus a short-lived direct link to its body — on the node, or (?source=backup) through the control plane's decrypted backup copy	read	`id` string `?source` node \| backup	`orbit mail messages get <id>` `mail_messages_get`
`DELETE /mail/messages/{id}` Remove a message from the index	write	`id` string	`orbit mail messages delete <id>` `mail_messages_delete`
`GET /mail/messages/{id}/backup` The decrypted backup copy of a message (only when the domain has backup enabled and this message has one)	read	`id` string	`orbit mail messages backup <id>` `mail_messages_backup`
`POST /mail/messages/{id}/flags` Add/remove flags (e.g. \Seen)	write	`id` string body: `add` string[], `remove` string[]	`orbit mail messages flags <id>` `mail_messages_flags`

outbox

Endpoint	Scope	Parameters	CLI · MCP tool
`GET /mail/outbox/{id}` One outbound job's state	read	`id` string	`orbit mail outbox get <id>` `mail_outbox_get`

aliases

Endpoint	Scope	Parameters	CLI · MCP tool
`GET /mail/domains/{id}/aliases` Alias addresses on a domain	read	`id` integer	`orbit mail aliases list <id>` `mail_aliases_list`
`POST /mail/domains/{id}/aliases` Point an address at a mailbox	write	`id` integer body: `local_part`* string, `target_mailbox_id`* string, `enabled` boolean	`orbit mail aliases create <id>` `mail_aliases_create`
`DELETE /mail/aliases/{id}` Remove an alias	write	`id` integer	`orbit mail aliases delete <id>` `mail_aliases_delete`

groups

Endpoint	Scope	Parameters	CLI · MCP tool
`GET /mail/domains/{id}/groups` Mail groups on a domain	read	`id` integer	`orbit mail groups list <id>` `mail_groups_list`
`POST /mail/domains/{id}/groups` Create a group address	write	`id` integer body: `local_part`* string, `name` string, `members` object[], `allow_external_senders` boolean, `members_can_send` boolean, `enabled` boolean, `posting` anyone \| org \| members, `reply_to` sender \| group, `subject_tag` string, `archive` boolean, `replace_alias` boolean	`orbit mail groups create <id>` `mail_groups_create`
`PATCH /mail/groups/{id}` Rename a group, change its members, or who may write to it	write	`id` string body: `local_part`* string, `name` string, `members` object[], `allow_external_senders` boolean, `members_can_send` boolean, `enabled` boolean, `posting` anyone \| org \| members, `reply_to` sender \| group, `subject_tag` string, `archive` boolean, `replace_alias` boolean	`orbit mail groups patch <id>` `mail_groups_patch`
`DELETE /mail/groups/{id}` Delete a group	write	`id` string	`orbit mail groups delete <id>` `mail_groups_delete`

domainrules

Endpoint	Scope	Parameters	CLI · MCP tool
`GET /mail/domains/{id}/rules` Domain-level routing rules	read	`id` integer	`orbit mail domainrules list <id>` `mail_domainrules_list`
`POST /mail/domains/{id}/rules` Add a routing rule (forward a copy, refuse a sender, quarantine, relay a recipient)	write	`id` integer body: `kind`* forward_copy \| reject_sender \| quarantine_sender \| relay_rcpt, `pattern`* string, `target` string, `enabled` boolean	`orbit mail domainrules create <id>` `mail_domainrules_create`
`PATCH /mail/domainrules/{id}` Change a routing rule	write	`id` integer body: `kind`* forward_copy \| reject_sender \| quarantine_sender \| relay_rcpt, `pattern`* string, `target` string, `enabled` boolean	`orbit mail domainrules patch <id>` `mail_domainrules_patch`
`DELETE /mail/domainrules/{id}` Remove a routing rule	write	`id` integer	`orbit mail domainrules delete <id>` `mail_domainrules_delete`

logs

Endpoint	Scope	Parameters	CLI · MCP tool
`GET /mail/domains/{id}/logs` Received / rejected verdicts, deliveries, bounces and failed actions, newest first	read	`id` integer `?kind` received \| rejected \| delivered \| bounced \| action_failed `?q` string `?cursor` string `?limit` integer	`orbit mail logs list <id>` `mail_logs_list`

Account API reference

Every Account endpoint in the Orbit API (10): method and path, the token scope it needs, its parameters, and the matching CLI command and MCP tool.

Organization API reference

Every Organization endpoint in the Orbit API (10): method and path, the token scope it needs, its parameters, and the matching CLI command and MCP tool.

Services API reference

Every Services endpoint in the Orbit API (15): method and path, the token scope it needs, its parameters, and the matching CLI command and MCP tool.

← All documentation