Blacklist domains

Add domains to the blacklist. Blacklisting a domain doesn't change the status of prospects instantly - it happens while processing the prospect in a campaign.

Request

Endpoint

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

Headers

x-api-key: {YOUR_API_KEY}
Content-type: application/json

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

Body

The request body is a JSON object with the property domains holding an array of domains.

info

You can add up to 500 domains per request.

{
  "domains": [
    "baddomain.com",
    "blacklistedomain.io",
    "nomoreemails.co"
  ]
}

Field	Type	Description
domains	array[string]	List of blacklisted domains

Request sample

Blacklist a list of domains

cURL

curl --request POST \
  --url "https://api.woodpecker.co/rest/v2/blacklist/domains" \
  --header "x-api-key: {YOUR_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
    "domains": [
      "baddomain.com",
      "blacklistedomain.io",
      "nomoreemails.co"
    ]
  }'

Java

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

public class WoodpeckerApiClient {
  public static void addDomainsToBlacklist(String apiKey, List<String> domains) throws Exception {
    String url = "https://api.woodpecker.co/rest/v2/blacklist/domains";
    ObjectMapper objectMapper = new ObjectMapper();
    String jsonBody = objectMapper.writeValueAsString(new BlacklistRequest(domains));
    
    HttpClient client = HttpClient.newHttpClient();
    HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create(url))
      .POST(HttpRequest.BodyPublishers.ofString(jsonBody))
      .header("x-api-key", apiKey)
      .header("Content-Type", "application/json")
      .build();

    HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
    
    System.out.println("Response status: " + response.statusCode());
    System.out.println("Response body: " + response.body());
  }

  private static class BlacklistRequest {
    public List<String> domains;

    public BlacklistRequest(List<String> domains) {
      this.domains = domains;
    }
  }
}

Node.js

const axios = require("axios");

async function addDomainsToBlacklist(apiKey, domains) {
  try {
    const url = "https://api.woodpecker.co/rest/v2/blacklist/domains";
    const response = await axios({
      method: "post",
      url: url,
      headers: {
        "x-api-key": apiKey,
        "Content-Type": "application/json",
      },
      data: { domains },
    });

    console.log("Response status:", response.status);
    console.log("Response data:", response.data);
    return response.data;
  } catch (error) {
    console.error("Error:", error.response ? error.response.data : error.message);
    throw error;
  }
}

module.exports = { addDomainsToBlacklist };

Response

Response examples

200

The domains array will return the domains that were successfully blacklisted in this request. Domains that were not added, for example because they were already blacklisted or were of incorrect format, will not be returned.

{
  "domains": [
    "baddomain.com",
    "blacklistedomain.io",
    "nomoreemails.co"
  ],
  "status": {
    "status": "OK",
    "code": "OK",
    "msg": "Domains were added to blacklist successfully."
  }
}

Body schema

Field	Type	Description
domains	array[string]	List of blacklisted domains
status	Object	Status details of the request
└─ status	String	General status indicator of request
└─ code	String	Code representing the status of the request
└─ msg	String	Message providing additional information about the outcome.

200

All of the domains are already blacklisted or their format doesn't pass validation.

{
  "domains": [],
  "status": {
    "status": "NO_CONTENT",
    "code": "NO_CONTENT",
    "msg": "None of the requested domains could be blacklisted or are already blacklisted."
  }
}

Body schema

Field	Type	Description
domains[]	array	List of blacklisted domains
status	Object	Status details of the request
└─status	String	General status indicator of request
└─code	String	Code representing the status of the request
└─msg	String	Message providing additional information about the outcome.

400

Invalid request or malformed request syntax.

{
  "title": "Bad Request",
  "status": 400,
  "detail": "You can blacklist up to 500 records in one request." | "Value of domains is incorrect.",
  "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

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