Get blacklisted domains

Retrieve a paginated list of all blacklisted domains for the authenticated account.

Request

Endpoint

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

Headers

x-api-key: {YOUR_API_KEY}

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

Parameters

Parameter	Required	Description
page	No	Requested results page (0-based)
per_page	No	Number of records per page. Default: 100, maximum: 1000

info

Page parameter is 0-based. Use page=0 to retrieve the first one. pagination_data.current_page_number is 1-based.

Request sample

Retrieve first 1000 domains

cURL

curl --request GET \
  --url "https://api.woodpecker.co/rest/v2/blacklist/domains?page=0&per_page=1000" \
  --header "x-api-key: {YOUR_API_KEY}"

Java

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

HttpClient client = HttpClient.newHttpClient();

HttpRequest request = HttpRequest.newBuilder()
  .uri(URI.create("https://api.woodpecker.co/rest/v2/blacklist/domains?page=0&per_page=1000"))
  .header("x-api-key", "YOUR_API_KEY")
  .GET()
  .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

System.out.println("Status code: " + response.statusCode());
System.out.println("Response body: " + response.body());

Node.js

async function getDomains() {
  try {
    const response = await fetch("https://api.woodpecker.co/rest/v2/blacklist/domains?page=0&per_page=1000", {
      headers: {
        "x-api-key": "YOUR_API_KEY",
      },
    });

    const data = await response.json();
    console.log("Status:", response.status);
    console.log("Data:", data);
  } catch (error) {
    console.error("Error:", error.message);
  }
}

getDomains();

Retrieve all blacklisted domains, paginate through results

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.util.ArrayList;
import java.util.List;

public class WoodpeckerApiClient {
  private static final String API_URL = "https://api.woodpecker.co/rest/v2/blacklist/domains";
  private static final String API_KEY = "YOUR_API_KEY"; 

  public static void main(String[] args) {
    try {
      List<String> allDomains = new ArrayList<>();
      HttpClient client = HttpClient.newHttpClient();
      ObjectMapper objectMapper = new ObjectMapper();

      int page = 0;
      boolean hasMorePages = true;

      while (hasMorePages) {
        String requestUrl = API_URL + "?page=" + page + "&per_page=1000";

        HttpRequest request = HttpRequest.newBuilder()
          .uri(URI.create(requestUrl))
          .header("x-api-key", API_KEY)
          .header("Accept", "application/json")
          .GET()
          .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

        JsonNode jsonResponse = objectMapper.readTree(response.body());

        if (jsonResponse.has("domains")) {
          for (JsonNode domain : jsonResponse.get("domains")) {
            allDomains.add(domain.asText());
          }
        }

        JsonNode paginationData = jsonResponse.get("pagination_data");
        int currentPage = paginationData.get("current_page_number").asInt();
        int totalPages = paginationData.get("total_pages").asInt();

        if (currentPage >= totalPages) {
          hasMorePages = false;
        } else {
          page++;
        }
      }

      System.out.println("Total blacklisted domains: " + allDomains.size());
      allDomains.forEach(System.out::println);

    } catch (Exception e) {
      System.err.println("Error: " + e.getMessage());
    }
  }
}

Node.js

const axios = require("axios");

async function getAllBlacklistedDomains() {
  try {
    let allDomains = [];
    let page = 0;
    let hasMorePages = true;

    while (hasMorePages) {
      const response = await axios.get("https://api.woodpecker.co/rest/v2/blacklist/domains", {
        params: {
          page: page,
          per_page: 1000,
        },
        headers: {
          "x-api-key": "YOUR_API_KEY",
          Accept: "application/json",
        },
      });

      allDomains = allDomains.concat(response.data.domains);

      if (response.data.pagination_data.current_page_number >= response.data.pagination_data.total_pages) {
        hasMorePages = false;
      } else {
        page++;
      }
    }

    console.log("Total blacklisted domains:", allDomains.length);
    console.log("Domains:", allDomains);
  } catch (error) {
    console.error("Error:", error.message);
  }
}

getAllBlacklistedDomains();

Response

Response examples

200

A list of blacklisted domains. The domains are sorted alphabetically.

{
  "domains": [
    "baddomain.com",
    "blacklistedomain.io",
    "finisheddeal.co.uk",
    "nomoreemails.co",
    "notmyicp.design"
  ],
  "pagination_data": {
    "total_elements": 505,
    "total_pages": 6,
    "current_page_number": 6,
    "page_size": 100
  }
}

Body schema

Field	Type	Description
domains	array[string]	List of blacklisted domains
pagination_data	object	Pagination information. See the pagination section

401

An issue with authorization. Please review the authorization guide

{
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid api key",
  "timestamp": "2025-03-05 17:57:00"
}

Body schema

Field	Type	Description
title	string	A short title describing the error
status	integer	The HTTP status code
detail	string	A detailed message explaining the error
timestamp	string	The timestamp when the error occurred, YYYY-MM-DD HH:MM:SS UTC

404

Please review the request URL.

{
  "title": "Not Found",
  "status": 404,
  "detail": "Requested resource does not exist",
  "timestamp": "2025-03-05 17:57:00"
}

Body schema

Field	Type	Description
title	string	A short title describing the error
status	integer	The HTTP status code
detail	string	A detailed message explaining the error
timestamp	string	The timestamp when the error occurred, YYYY-MM-DD HH:MM:SS UTC

500

Unknown error, please try again later

{
  "title": "Internal server error",
  "status": 500,
  "detail": "An unexpected error has occurred. Please try again later.",
  "timestamp": "2025-03-05 17:57:00"
}

Body schema

Field	Type	Description
title	string	A short title describing the error
status	integer	The HTTP status code
detail	string	A detailed message explaining the error
timestamp	string	The timestamp when the error occurred, YYYY-MM-DD HH:MM:SS UTC

Pagination

The response body contains pagination details. It will support you in navigating through larger datasets.

Use the per_page parameter to reduce or increase the number of returned domains per page. Default value: 100, maximum value: 1000.

Use page parameter to view a specific page.

info

Page parameter is 0-based. Use page=0 to retrieve the first one. pagination_data.current_page_number is 1-based.

{
  "domains": [],
  "pagination_data": {
    "total_elements": 501,
    "total_pages": 6,
    "current_page_number": 3,
    "page_size": 100
  }
}

Field	Type	Description
pagination_data	object	Pagination information
└─total_elements	integer	Total number of blacklisted domains
└─total_pages	integer	Total number of available pages
└─current_page_number	integer	Current page number (1-based)
└─page_size	integer	Maximum number of items per page