# Domains and deliverability

Domain claims, DNS records, senders and mail deliverability checks.

Scopes for this area: `domains:read`, `domains:write` and `domains:admin`.

43 operations.

## domain

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/workspace/domains` | Every domain this project added, one status object each. | read | `rivier domains domain list` |
| POST | `/workspace/domains` | Add a domain: detect where its DNS is hosted, build the records and check for conflicts. | write | `rivier domains domain add` |
| GET | `/workspace/domains/{d}` | The status object of one domain: steps, per-record state and the next action. | read | `rivier domains domain get` |
| POST | `/workspace/domains/{d}/recheck` | Check the domain's DNS now and activate it when everything is verified. | write | `rivier domains domain recheck` |
| POST | `/workspace/domains/{d}/preview` | The plan Rivier would apply to the DNS, without changing anything. | write | `rivier domains domain preview` |
| POST | `/workspace/domains/{d}/configure` | Apply for me, or repair: take a dump of the zone, apply the records and verify. | write | `rivier domains domain configure` |
| POST | `/workspace/domains/{d}/mode` | Choose apex, subdomain or delegate hosting. | write | `rivier domains domain set mode` |
| POST | `/workspace/domains/{d}/site` | Serve the site on www and a wildcard, or turn it off with null. | write | `rivier domains domain set site` |
| POST | `/workspace/domains/{d}/dmarc` | Tighten the DMARC policy to quarantine or reject after clean reports. | write | `rivier domains domain advance dmarc` |
| POST | `/workspace/domains/{d}/rollback` | Restore the zone from a dump taken before an apply. | write | `rivier domains domain rollback` |
| POST | `/workspace/domains/{d}/cloudflare` | Connect a Cloudflare token scoped to this zone. The token is sealed and never returned. | write | `rivier domains domain connect cloudflare` |
| GET | `/workspace/domains/{d}/events` | The operations events of one domain. | read | `rivier domains domain events` |
| DELETE | `/workspace/domains/{d}` | Forget the domain. The DNS is left as it is. | write | `rivier domains domain remove` |

## sender

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| POST | `/workspace/senders` | Send a confirmation code to a sender address. | write | `rivier domains sender start` |
| POST | `/workspace/senders/confirm` | Confirm a sender address with the code it received. | write | `rivier domains sender confirm` |

## deliverability domain

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/deliverability/domains` | Every domain with its deliverability set-up: whether the own MTA is allowed and how many checks fail. | read | `rivier domains deliverability domain list` |
| POST | `/deliverability/domains/{d}/setup` | Set the DKIM selector, return-path host, IP pool and warmup plan of a domain. Changing the pool or selector switches the own MTA off until it is approved again. | write | `rivier domains deliverability domain setup` |

## deliverability readiness

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/deliverability/domains/{d}/readiness` | One readiness report for a domain: SPF, DKIM, DMARC, MTA-STS, MX, return-path, BIMI, reverse DNS, blocklists, warmup, reputation and the own-MTA gate, with the next steps in words. | read | `rivier domains deliverability readiness get` |

## deliverability gate

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/deliverability/domains/{d}/gate` | Whether the own MTA may carry this domain's mail now, each check passed or failed in words. The relay is always allowed. | read | `rivier domains deliverability gate get` |

## deliverability own mta

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| POST | `/deliverability/domains/{d}/own-mta` | A person switches the own MTA on or off for a domain. On is refused unless every check passes. | write | `rivier domains deliverability own mta set` |

## deliverability fix

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| POST | `/deliverability/domains/{d}/fixes/propose` | Propose a fix for every failing check, as the exact records or instructions. Changes nothing. | write | `rivier domains deliverability fix propose` |
| GET | `/deliverability/domains/{d}/fixes` | Open and past fix proposals for a domain. | read | `rivier domains deliverability fix list` |
| POST | `/deliverability/domains/{d}/fixes/{id}/apply` | A person approves a DNS fix: the records are written through the Domains connector after a zone dump, then the domain is checked again. | write | `rivier domains deliverability fix apply` |
| POST | `/deliverability/domains/{d}/fixes/{id}/reject` | Reject a fix proposal. | write | `rivier domains deliverability fix reject` |

## deliverability warmup

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/deliverability/domains/{d}/warmup` | The warmup plan laid onto the calendar for a domain: each day's date and volume caps. | read | `rivier domains deliverability warmup schedule` |

## deliverability signal

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| POST | `/deliverability/domains/{d}/signals` | Record a reading from outside (Gmail Postmaster reputation, Microsoft SNDS colour, a seed test result) so it shows beside the sending numbers. | write | `rivier domains deliverability signal add` |

## deliverability event

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| POST | `/deliverability/events` | Report a delivery event (sent, delivered, deferred, bounced, complained, opened, clicked, unsubscribed). Counted per domain, day and recipient provider; hard bounces and complaints suppress the address; repeated soft bounces suppress by the project's rule. | write | `rivier domains deliverability event ingest` |

## deliverability analytics

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/deliverability/analytics` | Sending, delivery, bounce, complaint, open and click numbers by day, recipient provider and transport, with plain flags for rates over the project's lines and for providers where opens or deferrals look wrong. | read | `rivier domains deliverability analytics get` |

## deliverability rules

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/deliverability/rules` | The project's lines: soft-bounce escalation, complaint and bounce rates that warn or pause, minimum sample. | read | `rivier domains deliverability rules get` |
| PUT | `/deliverability/rules` | Change the project's deliverability lines (owner or manager). | write | `rivier domains deliverability rules set` |

## deliverability suppression

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| POST | `/deliverability/suppressions/import` | Add many addresses to the do-not-send list at once (bounced, complained, manual, invalid). Dry run counts without changing. Listing and lifting are under /crm/suppressions. | write | `rivier domains deliverability suppression import` |

## deliverability pool

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/deliverability/pools` | IP pools and their IPs (the operator sees all, a project sees the pool assigned to its domains). | read | `rivier domains deliverability pool list` |
| POST | `/deliverability/pools` | Create or change an IP pool (operator). | write | `rivier domains deliverability pool save` |
| DELETE | `/deliverability/pools/{id}` | Remove an empty IP pool (operator). | write | `rivier domains deliverability pool remove` |

## deliverability ip

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| POST | `/deliverability/ips` | Add or change a sending IP: pool, expected reverse DNS name, status, warmup plan and start date (operator). | write | `rivier domains deliverability ip save` |
| DELETE | `/deliverability/ips/{ip}` | Remove a sending IP (operator). | write | `rivier domains deliverability ip remove` |

## deliverability blocklist

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/deliverability/blocklists` | The blocklist zones watched, the suggested ones not yet adopted, and the last answers. | read | `rivier domains deliverability blocklist list` |
| POST | `/deliverability/blocklists` | Watch a blocklist zone, or change how it counts (operator). | write | `rivier domains deliverability blocklist save` |
| DELETE | `/deliverability/blocklists/{zone}` | Stop watching a blocklist zone (operator). | write | `rivier domains deliverability blocklist remove` |
| POST | `/deliverability/blocklists/scan` | Query every watched zone for every active sending IP now (operator). DNS queries only. | write | `rivier domains deliverability blocklist scan` |

## deliverability plan

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/deliverability/warmup-plans` | Warmup plans: the stage tables of volume per day per domain and per IP. | read | `rivier domains deliverability plan list` |
| POST | `/deliverability/warmup-plans` | Create or change a warmup plan (operator). The volumes are the operator's numbers. | write | `rivier domains deliverability plan save` |
| DELETE | `/deliverability/warmup-plans/{id}` | Remove a warmup plan (operator). | write | `rivier domains deliverability plan remove` |