feat(domains): add the Forge endpoints

LU
18h ago
+76-1

Adds the Forge domain surface to the spec, matching the folded public-api implementation.

Endpoints

  • POST /domains/{domain_id}/forge (domains/enable-forge): puts a domain's sending on Forge and returns the DNS record Forge needs. Add the record, call the verify domain endpoint with scope: ["forge"], then poll the retrieve domain endpoint until the Forge record's status is verified. Idempotent: calling it again just returns the current state. Optional return_path body field (when omitted, the API picks a label that is free in the domain's DNS) and a documented Idempotency-Key header. Returns the full domain response (Domain). Receive-only domains, dedicated IPs, and legacy DKIM get forge_unavailable (noted in the description; the spec documents only success responses, like its neighbors).
  • POST /domains/{domain_id}/verify gained an optional request body (VerifyDomainOptions): scope, an array of strings whose only value is forge. Scoped, only the Forge record is checked and the other records stay verified; requires Forge to be enabled, otherwise forge_not_enabled. Omitted, all records are checked, exactly as before.
  • PATCH /domains/{domain_id} (UpdateDomainOptions) gained an optional forge_return_path: moves the Forge return path while the Forge record is still verifying; a verified record, a legacy-path collision, or a host that already has DNS records gets return_path_unavailable. Moving does not start verification: fetch the new record, add DNS, verify with scope: ["forge"].
  • There is no standalone PATCH /domains/{domain_id}/forge or POST /domains/{domain_id}/forge/verify: those endpoints were removed from the API before shipping.

Schema changes

  • EnableForgeRequest (return_path: 2-63 chars, pattern ^[a-zA-Z][a-zA-Z0-9-]*[a-zA-Z0-9]$), new VerifyDomainOptions (scope), and forge_return_path on UpdateDomainOptions with the same constraints as return_path.

Validation

  • yq eval . resend.yaml parses.
  • npx @redocly/cli lint resend.yaml: valid, 0 errors, 185 warnings (main has 184; the one added warning is the operation-4xx-response rule every neighboring operation already triggers).

Part of DEV-2470.

The Forge enable endpoint is live in production; the scoped verify and forge_return_path land with the API reshape, which deploys before this ships.

Domain response schemas are unchanged: Forge state is read from the Forge CNAME record in the records array, and verification is explicit via the verify endpoint.