Delete domain mailbox

Request deletion of an existing mailbox from a domain. Domain and mailbox lookups are case-insensitive. The mailbox must belong to the account, must belong to the domain in the path, and must not already be in a deletion status.

Request

You can delete a mailbox only when it is ready for deletion, which means it has the PAID status. If the mailbox is not ready yet, the endpoint returns a validation error with the cannot_delete_due_to_not_connected_mailbox issue.

warning

After the deletion is processed, the mailbox will no longer exist and cannot be recovered.

Endpoint

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

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
mailbox_email	Yes	string	Mailbox email address. URL-encode it if your client does not encode path parameters automatically, for example richard%40piedpiper.com

Request samples

Delete a mailbox

cURL

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

Python

import requests

def delete_domain_mailbox(domain_name, mailbox_email):
  encoded_mailbox_email = requests.utils.quote(mailbox_email, safe="")
  url = f"https://api.woodpecker.co/rest/v2/domains/{domain_name}/mailboxes/{encoded_mailbox_email}"
  headers = {
    "x-api-key": "{YOUR_API_KEY}"
  }

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

if __name__ == "__main__":
  try:
    result = delete_domain_mailbox("piedpiper.com", "richard@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;
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;

public class WoodpeckerApiClient {
  public static void main(String[] args) {
    try {
      String domainName = "piedpiper.com";
      String mailboxEmail = "richard@piedpiper.com";
      String encodedMailboxEmail = URLEncoder.encode(mailboxEmail, StandardCharsets.UTF_8);
      String url = "https://api.woodpecker.co/rest/v2/domains/" + domainName + "/mailboxes/" + encodedMailboxEmail;

      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: Mailbox 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 deleteDomainMailbox(domainName, mailboxEmail) {
  const encodedMailboxEmail = encodeURIComponent(mailboxEmail);
  const url = `https://api.woodpecker.co/rest/v2/domains/${domainName}/mailboxes/${encodedMailboxEmail}`;
  const headers = {
    'x-api-key': '{YOUR_API_KEY}'
  };

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

deleteDomainMailbox('piedpiper.com', 'richard@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';
  $mailboxEmail = rawurlencode('richard@piedpiper.com');
  $response = $client->delete("domains/{$domainName}/mailboxes/{$mailboxEmail}");
  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 mailbox 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. This also includes mailboxes that are not ready for deletion yet, for example a mailbox without the PAID status. In that case, the validation issue is cannot_delete_due_to_not_connected_mailbox.

{
  "type": "validation_error",
  "message": "Invalid field(s)",
  "code": "invalid_fields",
  "request_id": "dc4faa0f-78bf-54e9-9d5d-ce9538f2eec5",
  "fields": [
    {
      "field": "mailbox_email",
      "issue": "domain_mismatch",
      "value": "richard@other-domain.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. Possible fields include domain_name and mailbox_email
└─ 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