Delete domain

Request deletion of an existing Woodpecker domain. Domain lookup is case-insensitive. The domain must belong to the account, must have is_ready: true, and must not already be in deletion process.

Request

You can delete a domain only when it is ready for deletion, which means it has is_ready: true. If the domain is not ready yet, the endpoint returns a validation error.

warning

Deleting a domain also deletes all mailboxes attached to that domain. After the deletion is processed, those mailboxes will no longer exist and cannot be recovered.

Endpoint

DELETE https://api.woodpecker.co/rest/v2/domains/{domain_name}

Headers

x-api-key: {YOUR_API_KEY}

For details on how to authenticate your requests, please see the authentication guide.

Parameters

Parameter	Required	Type	Description
domain_name	Yes	string	Domain name

Request samples

Delete a domain

cURL

curl --request DELETE \
  --url "https://api.woodpecker.co/rest/v2/domains/piedpiper.com" \
  --header "x-api-key: {YOUR_API_KEY}"

Python

import requests

def delete_domain(domain_name):
  url = f"https://api.woodpecker.co/rest/v2/domains/{domain_name}"
  headers = {
    "x-api-key": "{YOUR_API_KEY}"
  }

  response = requests.delete(url, headers=headers)
  if response.status_code == 202:
    return f"Domain deletion accepted: {response.status_code}"
  else:
    raise Exception(f"DELETE request failed: {response.status_code}, {response.text}")

if __name__ == "__main__":
  try:
    result = delete_domain("piedpiper.com")
    print("DELETE response:", result)
  except Exception as e:
    print("Error:", e)

Java

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;

public class WoodpeckerApiClient {
  public static void main(String[] args) {
    try {
      String domainName = "piedpiper.com";
      String url = "https://api.woodpecker.co/rest/v2/domains/" + domainName;

      HttpClient client = HttpClient.newHttpClient();
      HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create(url))
        .header("x-api-key", "{YOUR_API_KEY}")
        .DELETE()
        .build();

      HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
      if (response.statusCode() == 202) {
        System.out.println("DELETE response: Domain deletion accepted: " + response.statusCode());
      } else {
        throw new Exception("DELETE request failed: " + response.statusCode() + ", " + response.body());
      }
    } catch (Exception e) {
      System.out.println("Error: " + e.getMessage());
    }
  }
}

Node.js

const axios = require('axios');

async function deleteDomain(domainName) {
  const url = `https://api.woodpecker.co/rest/v2/domains/${domainName}`;
  const headers = {
    'x-api-key': '{YOUR_API_KEY}'
  };

  try {
    const response = await axios.delete(url, { headers });
    console.log('DELETE response:', `Domain deletion accepted: ${response.status}`);
  } catch (error) {
    console.error('DELETE request failed:', error.response ? error.response.status : error.message);
  }
}

deleteDomain('piedpiper.com');

PHP

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;
use GuzzleHttp\Exception\RequestException;

$client = new Client([
  'base_uri' => 'https://api.woodpecker.co/rest/v2/',
  'headers'  => [
    'x-api-key' => getenv('WOODPECKER_API_KEY'),
  ],
]);

try {
  $domainName = 'piedpiper.com';
  $response = $client->delete("domains/{$domainName}");
  echo $response->getStatusCode(), "\n";
  echo $response->getBody(), "\n";
} catch (RequestException $e) {
  echo "Error: ", $e->getMessage(), "\n";
  if ($e->hasResponse()) {
    echo $e->getResponse()->getBody(), "\n";
  }
}

Response

Response examples

202

The domain deletion has been accepted

400

Invalid request or malformed request syntax

{
  "title": "Bad Request",
  "status": 400,
  "details": "error details",
  "timestamp": "2026-05-06T12:00:00Z"
}

Body schema

Field	Type	Description
title	string	A short title describing the error
status	integer	The HTTP status code
details	string	A detailed message explaining the error
timestamp	string	The timestamp when the error occurred

401

Authentication failed. Please review the authentication guide

{
  "title": "Unauthorized",
  "status": 401,
  "details": "error details",
  "timestamp": "2026-05-06T12:00:00Z"
}

Body schema

Field	Type	Description
title	string	A short title describing the error
status	integer	The HTTP status code
details	string	A detailed message explaining the error
timestamp	string	The timestamp when the error occurred

422

Returned when the request body is valid JSON but contains invalid or missing fields.

{
  "type": "validation_error",
  "message": "Invalid field(s)",
  "code": "invalid_fields",
  "request_id": "dc4faa0f-78bf-54e9-9d5d-ce9538f2eec5",
  "fields": [
    {
      "field": "domain_name",
      "issue": "not_found",
      "value": "piedpiper.com"
    }
  ]
}

Body schema

Field	Type	Description
type	string	Error type
message	string	Error message
code	string	Error code
request_id	string or null	Request identifier when available
fields	array	Fields that failed validation
└─ field	string	Field with a validation issue
└─ issue	string	Detailed description of the validation issue
└─ value	string/null	Rejected value, or null for a missing required field

500

Unexpected server error

{
  "title": "Internal Server Error",
  "status": 500,
  "details": "error details",
  "timestamp": "2026-05-06T12:00:00Z"
}

Body schema

Field	Type	Description
title	string	A short title describing the error
status	integer	The HTTP status code
details	string	A detailed message explaining the error
timestamp	string	The timestamp when the error occurred

503

Service unavailable or communication error

{
  "title": "Service Unavailable",
  "status": 503,
  "details": "error details",
  "timestamp": "2026-05-06T12:00:00Z"
}

Body schema

Field	Type	Description
title	string	A short title describing the error
status	integer	The HTTP status code
details	string	A detailed message explaining the error
timestamp	string	The timestamp when the error occurred