DELETE/api/v1/projects/{project_id}/domains/{domain_id}

`delete_sending_domain`

Deletes a sending domain for good: no read finds it again, its DKIM key is destroyed, and its name is free to add again (with a new key); its records stay in DNS until removed at the provider.

Call it: when a domain is no longer sent from.
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 confirm: true; without it the call changes nothing and tells what it would do.
Returns: outcome (would_delete, deleted), effect in words and the domain as get_sending_domain returns it after the call (null once deleted; a second call is not_found); the API’s DELETE /api/v1/projects/{project_id}/domains/{domain_id} answers 204.

Arguments

object
domain_idstring · uuidrequired

The domain’s id.
confirmboolean

true deletes the domain. Without it the call only tells what would happen and changes nothing.

default false
project_idstring · uuid | null

The domain’s project. An admin key must pass it; a project key’s own project is used and this is ignored.

No other arguments are accepted.

Result

The result comes back as structuredContent, with the same JSON as a text block.

object · all fields required
domainSendingDomain | null

The domain as it is now; null once deleted.
14 fields
- SendingDomain object · all fields required
- bounce_subdomainstring
- checksarray of DomainCheck
  
  One entry per check that ran, in the canonical order; empty until the domain is first verified.
  3 fields
  
  DomainCheck object · all fields required
  
  detailstring | null
  
  What was found instead of what was expected; null when ok.
  
  namestring
  
  spf_bounce, mx_bounce, dkim, dmarc, tracking_cname, tracking_tls or ptr.
  
  statusCheckStatusOutput
  
  How one verification check came out.
  
  ok The required record is present and matches.
  
  missing No record of this kind is in DNS yet.
  
  mismatch A record is there, but not the one Postwind needs.
  
  warning Not ok, but it does not fail the domain (ptr).
- created_atstring · date-time
- dkim_public_keystring
  
  The DKIM public key: base64 of its DER SubjectPublicKeyInfo, the p= of the DKIM record.
- dkim_selectorstring
- dns_providerDnsProviderOutput
  
  Who applies a domain’s DNS records.
  
  porkbun Porkbun’s API.
  
  manual Nobody: the records are for entry by hand.
- domainstring
  
  In punycode for an international name.
- idstring · uuid
- ip_poolstring
- last_checked_atstring · date-time | null
  
  When the records were last checked; null until then.
- project_idstring · uuid
- statusDomainStatusOutput
  
  Where a sending domain stands.
  
  pending Its records are not checked yet, or changed since.
  
  verified Every required record checked out.
  
  failed A required record is missing or wrong.
- tracking_hoststring | null
  
  null: none.
- updated_atstring · date-time
effectstring

The outcome in words, for the agent and its user.
outcomeDomainDeletionOutcome

What a call of delete_sending_domain did.

would_delete A dry run: nothing changed; a call with confirm: true deletes.

deleted Deleted now. A deleted domain is gone: a second call is not_found.

Definitions

CheckStatusOutput

How one verification check came out.

string · enum

ok The required record is present and matches.

missing No record of this kind is in DNS yet.

mismatch A record is there, but not the one Postwind needs.

warning Not ok, but it does not fail the domain (ptr).

DnsProviderOutput

Who applies a domain’s DNS records.

string · enum

porkbun Porkbun’s API.

manual Nobody: the records are for entry by hand.

DomainCheck

One verification check.

object · all fields required
detailstring | null

What was found instead of what was expected; null when ok.
namestring

spf_bounce, mx_bounce, dkim, dmarc, tracking_cname, tracking_tls or ptr.
statusCheckStatusOutput

How one verification check came out.

ok The required record is present and matches.

missing No record of this kind is in DNS yet.

mismatch A record is there, but not the one Postwind needs.

warning Not ok, but it does not fail the domain (ptr).

DomainDeletionOutcome

What a call of delete_sending_domain did.

string · enum

would_delete A dry run: nothing changed; a call with confirm: true deletes.

deleted Deleted now. A deleted domain is gone: a second call is not_found.

DomainStatusOutput

Where a sending domain stands.

string · enum

pending Its records are not checked yet, or changed since.

verified Every required record checked out.

failed A required record is missing or wrong.

SendingDomain

A sending domain (get_sending_domain, list_sending_domains).

object · all fields required
bounce_subdomainstring
checksarray of DomainCheck

One entry per check that ran, in the canonical order; empty until the domain is first verified.

see DomainCheck
created_atstring · date-time
dkim_public_keystring

The DKIM public key: base64 of its DER SubjectPublicKeyInfo, the p= of the DKIM record.
dkim_selectorstring
dns_providerDnsProviderOutput

Who applies a domain’s DNS records.

porkbun Porkbun’s API.

manual Nobody: the records are for entry by hand.
domainstring

In punycode for an international name.
idstring · uuid
ip_poolstring
last_checked_atstring · date-time | null

When the records were last checked; null until then.
project_idstring · uuid
statusDomainStatusOutput

Where a sending domain stands.

pending Its records are not checked yet, or changed since.

verified Every required record checked out.

failed A required record is missing or wrong.
tracking_hoststring | null

null: none.
updated_atstring · date-time

Errors

A failed call answers isError: true with a code from the same table as the HTTP API, and detail. How tools report errors

HTTP API

The same operation over HTTP: DELETE /api/v1/projects/{project_id}/domains/{domain_id}