Apply a domain's DNS records

Applies the domain’s required records through its DNS provider and answers each record’s outcome. For a manual-provider domain nothing is changed and every record’s outcome is manual (the records to enter by hand). Postwind creates and changes the SPF and MX of the bounce subdomain, the DKIM record and the tracking CNAME; it creates _dmarc only when absent and never changes it; and it refuses (never overwrites) a bounce-subdomain TXT that is not SPF. A provider failure on one record is that record’s outcome, not an error; the first unavailable record stops the run, which ends within 30 s, and a repeat converges. Until the node has a TLS client, a Porkbun domain answers precondition_failed. Needs scope write.

Parameters

Name	In	Type	Description
`project_id`required	path	string · uuid	The project’s id
`domain_id`required	path	string · uuid	The domain’s id
`Idempotency-Key`	header	string 1–128 characters · pattern `^[!-~]{1,128}$`	A key of the client’s choosing, one per request it means to send once (a UUID will do). A repeat with the same key and the same body within 24 h creates nothing again and gets the first answer, marked `Idempotent-Replayed: true`. The key belongs to the API key that sent it. Only a `2xx` answer is kept: after any other answer the key is free again.

Request body

None.

Responses

200

Each record’s outcome

Header	Type	Description
`Idempotent-Replayed`	string · enum	`true` when the answer is a replay of an earlier request with the same `Idempotency-Key`; absent otherwise.

AppliedDnsRecords object · all fields required
dns_providerDnsProvider

Who applied the records: porkbun, or manual (nothing was changed; each record’s outcome is manual).
- porkbun
- manual
recordsarray of AppliedDnsRecord

One entry per required record, in the order they are created.
6 fields
- AppliedDnsRecord object · all fields required
- contentstring
  
  The value the record should hold.
- detailstring | null
  
  A message for the outcomes that carry one (conflict, provider_error, unavailable); null otherwise.
- namestring
  
  The owner name, without a trailing dot.
  
  example bounce.news.example.com
- outcomeDnsApplyOutcome
  
  What apply did to one record.
  - created
  - updated
  - unchanged
  - skipped_exists
  - manual
  - conflict
  - provider_error
  - unavailable
- purposeRecordPurpose
  
  What a required record is for.
  - spf_bounce
  - mx_bounce
  - dkim
  - dmarc
  - tracking_cname
- typeRecordType
  
  The type of a DNS record.
  - txt
  - mx
  - cname

401

No valid key

Problem (application/problem+json)

403

A project key without scope write (forbidden)

Problem (application/problem+json)

404

No such project or domain in it, or another project’s (not_found)

Problem (application/problem+json)

409

The project is deleted (conflict); or a request with the same Idempotency-Key has not answered yet (idempotency_key_in_progress)

Problem (application/problem+json)

422

The node has no usable web.public_url, no longer declares the domain’s IP pool, Porkbun is not configured for the domain or cannot be reached over HTTPS from this build, or the domain has no registrable domain (precondition_failed); or the Idempotency-Key was used in the last 24 h for another request (idempotency_key_reused), or is not 1 to 128 visible ASCII characters (validation_failed, field Idempotency-Key)

Problem (application/problem+json)

429

The key is over its rate limit, api.rate_limit_per_minute requests a minute on this node (rate_limited)

Header	Type	Description
`Retry-After`	integer	Seconds until the key’s next request passes; rounded up.

Problem (application/problem+json)

504

Postwind’s storage did not answer within its time limit (storage_timeout). A change the request makes may still take effect: check before repeating it. A repeat with the same Idempotency-Key never runs it twice: it is 409 idempotency_key_in_progress until the key’s 24 h end

Problem (application/problem+json)

bashRequest

# set POSTWIND_URL, POSTWIND_KEY and the ids first
curl -X POST "$POSTWIND_URL/api/v1/projects/$PROJECT_ID/domains/$DOMAIN_ID/dns/apply" \
  -H "Authorization: Bearer $POSTWIND_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

MCP tool `apply_dns_records`

Call it: after add_sending_domain for a Porkbun domain to create the records automatically, or on a manual domain to get the list to enter by hand (nothing is changed; every outcome is manual).
Needs: an admin key with project_id, or a project key with scope write (its own project; the argument is ignored), the domain’s id, and, for Porkbun, credentials on the node or the project. No confirm is needed: re-running converges, _dmarc and records Postwind does not own are never overwritten, and nothing is deleted. A provider failure is that record’s outcome, not an error; the first unavailable record stops the run and the call ends within 30 s, so run it again for whatever is not created, updated or unchanged. Until the node has a TLS client, a Porkbun domain answers precondition_failed.
Returns: dns_provider and records (each with purpose, type, name, content, outcome and detail); the same as POST /api/v1/projects/{project_id}/domains/{domain_id}/dns/apply.

jsontools/call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "apply_dns_records",
    "arguments": {
      "domain_id": "<domain_id>"
    }
  }
}

Open the tool page