List domains

Retrieve all purchased domains that belong to your account, including their status, expiration date, mailbox count, and other basic information. To retrieve full details for a specific domain, use the get domain endpoint.

Request

Endpoint

GET https://api.woodpecker.co/rest/v2/domains

Headers

x-api-key: {YOUR_API_KEY}

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

Request samples

List domains

cURL

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

Python

import requests

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

  response = requests.get(url, headers=headers)
  if response.status_code == 200:
    return response.json()
  else:
    raise Exception(f"GET request failed: {response.status_code}, {response.text}")

if __name__ == "__main__":
  try:
    data = list_domains()
    print("GET response:", data)
  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 url = "https://api.woodpecker.co/rest/v2/domains";

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

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

Node.js

const axios = require('axios');

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

  try {
    const response = await axios.get(url, { headers });
    console.log('GET response:', response.data);
  } catch (error) {
    console.error('GET request failed:', error.response ? error.response.status : error.message);
  }
}

listDomains();

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 {
  $response = $client->get('domains');
  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

200

Request processed successfully. If there are no domains under this account, domains will be an empty array.

{
  "domains": [
    {
      "domain": "piedpiper.com",
      "mailboxes_count": 2,
      "provider": "GOOGLE",
      "is_custom_domain": true,
      "is_ready": true,
      "expires": "2027-06-24T10:00:00",
      "created": "2026-06-24T10:00:00"
    }
  ]
}

Body schema

Field	Type	Description
domains	array	Domains that belong to the account
└─ domain	string	Domain name
└─ mailboxes_count	integer	Number of non-deleted mailboxes associated with the domain
└─ provider	string	Domain and mailboxes provider name. Check providers endpoint to list available providers
└─ is_custom_domain	boolean	Whether the domain was purchased independently and transferred to Woodpecker
└─ is_ready	boolean	Whether the domain is ready to use
└─ expires	string	Domain expiration timestamp
└─ created	string	Domain creation timestamp

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

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