Get blacklisted emails

Retrieve a list of emails blacklisted in your agency. You can use the email_filter parameter to check whether specific emails are included in the blacklist.

Request

Endpoint

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

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
email_filter	No	Comma-separated emails to check against the list

info

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

Request sample

Retrieve first 1000 emails

cURL

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

Python

import requests

def get_blacklist_emails():
  url = "https://api.woodpecker.co/rest/v2/agency/blacklist/emails?page=0&per_page=1000"
  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 = get_blacklist_emails()
    print("GET 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?page=0&per_page=1000";

  public static void main(String[] args) {
    try {
      HttpClient client = HttpClient.newHttpClient();
      HttpRequest request = HttpRequest.newBuilder()
        .uri(new URI(URL))
        .header("x-api-key", 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 {
        System.err.println("GET request failed: " + response.statusCode());
      }
    } catch (Exception e) {
      e.printStackTrace();
    }
  }
}

Node.js

const axios = require('axios');

async function getBlacklistEmails() {
  const url = 'https://api.woodpecker.co/rest/v2/agency/blacklist/emails?page=0&per_page=1000';
  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);
  }
}

getBlacklistEmails();

Lookup a list of emails

You can check whether certain emails are listed by using the email_filter parameter. The maximum length of the request URL is 4100 characters.

cURL

curl --request GET \
  --url "https://api.woodpecker.co/rest/v2/agency/blacklist/emails?email_filter=wrong@baddomain.com,worse@anotherone.com" \
  --header "x-api-key: {YOUR_API_KEY}"

Python

import requests

def get_blacklist_emails_by_filter():
  url = "https://api.woodpecker.co/rest/v2/agency/blacklist/emails?email_filter=wrong@baddomain.com,worse@anotherone.com"
  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 = get_blacklist_emails_by_filter()
    print("GET 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?email_filter=wrong@baddomain.com,worse@anotherone.com";

  public static void main(String[] args) {
    try {
      HttpClient client = HttpClient.newHttpClient();
      HttpRequest request = HttpRequest.newBuilder()
        .uri(new URI(URL))
        .header("x-api-key", 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 {
        System.err.println("GET request failed: " + response.statusCode());
      }
    } catch (Exception e) {
      e.printStackTrace();
    }
  }
}

Node.js

const axios = require('axios');

async function getBlacklistEmailsByFilter() {
  const url = 'https://api.woodpecker.co/rest/v2/agency/blacklist/emails?email_filter=wrong@baddomain.com,worse@anotherone.com';
  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);
  }
}

getBlacklistEmailsByFilter();

Response

Response examples

200

A list of blacklisted emails

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

Body schema

Field	Type	Description
emails	array[string]	List of blacklisted emails
total	integer	Total number of blacklisted emails, or total number of found emails when using email_filter

400

Invalid request parameters or malformed request syntax.

{
  "title": "Bad Request",
  "status": 400,
  "detail": "Value of {field_name} 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