Set Bounce Shield threshold

Set or replace the Bounce Shield Monitor bounce rate threshold for a campaign. Provide the threshold as an integer representing a percentage, for example 10 for 10%. Bounce Shield Monitor uses this value to decide when to automatically pause the campaign.

Request

Endpoint

PUT https://api.woodpecker.co/rest/v2/campaigns/{campaign_id}/bounce_shield/threshold

Headers

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

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

Parameters

Parameter	Required	Type	Description
campaign_id	Yes	integer	Campaign ID

Body

The request body is required. Send bounce_rate_threshold as an integer between 1 and 99.

{
  "bounce_rate_threshold": 12
}

Body schema

Field	Type	Required	Description
bounce_rate_threshold	integer	Yes	Bounce rate threshold percentage

Request samples

Set the threshold

cURL

curl --request PUT \
  --url "https://api.woodpecker.co/rest/v2/campaigns/{campaign_id}/bounce_shield/threshold" \
  --header "x-api-key: {YOUR_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
    "bounce_rate_threshold": 12
  }'

Python

import requests

def set_bounce_shield_threshold(campaign_id):
  url = f"https://api.woodpecker.co/rest/v2/campaigns/{campaign_id}/bounce_shield/threshold"
  headers = {
    "x-api-key": "{YOUR_API_KEY}",
    "Content-Type": "application/json"
  }
  payload = {
    "bounce_rate_threshold": 12
  }

  response = requests.put(url, headers=headers, json=payload)

  if response.status_code == 204:
    print("Threshold set successfully.")
  else:
    print("PUT failed with status:", response.status_code, response.text)

if __name__ == "__main__":
  set_bounce_shield_threshold(123)

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}";

  public static void main(String[] args) {
    setBounceShieldThreshold(123);
  }

  public static void setBounceShieldThreshold(int campaignId) {
    try {
      String url = "https://api.woodpecker.co/rest/v2/campaigns/" + campaignId + "/bounce_shield/threshold";
      String jsonData = """
        {
          "bounce_rate_threshold": 12
        }
        """;

      HttpClient client = HttpClient.newHttpClient();
      HttpRequest request = HttpRequest.newBuilder()
        .uri(new URI(url))
        .header("x-api-key", API_KEY)
        .header("Content-Type", "application/json")
        .PUT(HttpRequest.BodyPublishers.ofString(jsonData))
        .build();

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

      if (response.statusCode() == 204) {
        System.out.println("Threshold set successfully.");
      } else {
        System.err.println("PUT request failed: " + response.statusCode());
      }
    } catch (Exception e) {
      e.printStackTrace();
    }
  }
}

Node.js

const axios = require("axios");

async function setBounceShieldThreshold(campaignId) {
  const url = `https://api.woodpecker.co/rest/v2/campaigns/${campaignId}/bounce_shield/threshold`;
  const headers = {
    "x-api-key": "{YOUR_API_KEY}",
    "Content-Type": "application/json"
  };
  const data = {
    bounce_rate_threshold: 12
  };

  try {
    const response = await axios.put(url, data, { headers });

    if (response.status === 204) {
      console.log("Threshold set successfully.");
    } else {
      console.error("PUT failed with status:", response.status);
    }
  } catch (error) {
    console.error("Request error:", error.response?.status || error.message);
  }
}

setBounceShieldThreshold(123);

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'),
    'Content-Type'  => 'application/json',
  ],
]);

$campaignId = '{campaign_id}';

try {
  $response = $client->put("campaigns/{$campaignId}/bounce_shield/threshold", [
    'json' => [
      'bounce_rate_threshold' => 12,
    ],
  ]);
  echo $response->getStatusCode(), "\n";
} catch (RequestException $e) {
  echo "Error: ", $e->getMessage(), "\n";
  if ($e->hasResponse()) {
    echo $e->getResponse()->getBody(), "\n";
  }
}

Response

Response examples

204

The threshold has been set.

Status: 204
Body: none

400

Invalid request body or threshold value.

{
  "code": "INPUT_DATA_VALIDATION_FAILURE",
  "message": "Input data validation failure",
  "details": {
    "errors": [
      {
        "field": "bounce_rate_threshold",
        "detail": "bounce_rate_threshold must be an integer between 1 and 99"
      }
    ]
  }
}

Body schema

Field	Type	Description
code	string	Error code
message	string	Error message
details	object	Additional information
└─ errors	array[object]	Validation errors
└─ field	string	Field that failed validation
└─ detail	string	Validation failure details

401

An issue with authorization. Please review the authentication 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

The requested campaign does not exist, was deleted, or belongs to another account.

{
  "code": "CAMPAIGN_NOT_EXIST",
  "message": "Campaign not found",
  "details": null
}

Body schema

Field	Type	Description
code	string	Error code
message	string	Error message
details	string/null	Additional information

500

An unknown error occurred while setting the threshold. Please try again later.

{
  "code": "UNKNOWN",
  "message": "Unknown error during campaign call",
  "details": null
}

Body schema

Field	Type	Description
code	string	Error code
message	string	Error message
details	string/null	Additional information