Blacklist emails

Add emails to the agency blacklist. Blacklisting an email does not immediately change the status of existing prospects. Instead, it prevents all current and future client accounts from contacting that prospect. A prospect's status will be updated to BLACKLISTED during campaign processing.

Request

Endpoint

POST https://api.woodpecker.co/rest/v2/agency/blacklist/emails

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 emails holding an array of emails.

info

You can add up to 500 emails per request

{
  "emails": [
    "wrong@baddomain.com",
    "worse@anotherone.com",
    "john@finisheddeal.co.uk",
    "drew@nomoreemails.co",
    "andrew@notmyicp.design"
  ]
}

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

Request sample

Blacklist a list of emails

cURL

curl --request POST \
  --url "https://api.woodpecker.co/rest/v2/agency/blacklist/emails" \
  --header "x-api-key: {YOUR_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
    "emails": [
      "wrong@baddomain.com",
      "worse@anotherone.com",
      "john@finisheddeal.co.uk"
    ]
  }'

Python

import requests

def blacklist_emails():
  url = "https://api.woodpecker.co/rest/v2/agency/blacklist/emails"
  headers = {
    "x-api-key": "{YOUR_API_KEY}",
    "Content-Type": "application/json"
  }
  payload = {
    "emails": [
      "wrong@baddomain.com",
      "worse@anotherone.com",
      "john@finisheddeal.co.uk"
    ]
  }
  
  response = requests.post(url, headers=headers, json=payload)
  if response.status_code == 201:
    return response.json()
  else:
    raise Exception(f"POST request failed: {response.status_code}, {response.text}")

if __name__ == "__main__":
  try:
    data = blacklist_emails()
    print("POST response:", data)
  except Exception as e:
    print("Error:", e)

Java

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

public class WoodpeckerApiClient {
  private static final String API_KEY = "{YOUR_API_KEY}";
  private static final String URL = "https://api.woodpecker.co/rest/v2/agency/blacklist/emails";

  public static void main(String[] args) {
    try {
      HttpClient client = HttpClient.newHttpClient();
      String jsonPayload = "{\"emails\": [\"wrong@baddomain.com\", \"worse@anotherone.com\", \"john@finisheddeal.co.uk\"]}";
      
      HttpRequest request = HttpRequest.newBuilder()
        .uri(new URI(URL))
        .header("Content-Type", "application/json")
        .header("x-api-key", API_KEY)
        .POST(HttpRequest.BodyPublishers.ofString(jsonPayload))
        .build();
      
      HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
      
      if (response.statusCode() == 201) {
        System.out.println("POST response: " + response.body());
      } else {
        System.err.println("POST request failed: " + response.statusCode());
      }
    } catch (Exception e) {
      e.printStackTrace();
    }
  }
}

Node.js

const axios = require('axios');

async function blacklistEmails() {
  const url = 'https://api.woodpecker.co/rest/v2/agency/blacklist/emails';
  const headers = {
    'x-api-key': '{YOUR_API_KEY}',
    'Content-Type': 'application/json'
  };
  const data = {
    emails: [
      'wrong@baddomain.com',
      'worse@anotherone.com',
      'john@finisheddeal.co.uk'
    ]
  };

  try {
    const response = await axios.post(url, data, { headers });
    if (response.status === 201) {
      console.log('POST response:', response.data);
    } else {
      console.error('POST request failed:', response.status);
    }
  } catch (error) {
    console.error('POST request failed:', error.response ? error.response.status : error.message);
  }
}

blacklistEmails();

Response

Response examples

201

The requested emails have been blacklisted

Status: 201
Body: none

400

Invalid request parameters or malformed request syntax.

{
  "title": "Bad Request",
  "status": 400,
  "detail": "You can blacklist up to 500 records in one request." | "Value of emails is incorrect." | "No data found. Provide at least one email.",
  "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