Set domain email forwarding

Set the forwarding email address for an existing domain. All emails sent to mailboxes under the domain will be automatically forwarded to the selected address. You can set it only after the domain is ready to use, meaning that get domain endpoint returns is_ready as true.

Request

Endpoint

PATCH https://api.woodpecker.co/rest/v2/domains/{domain_name}/set_email_forwarding

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
domain_name	Yes	string	Domain name

Body

{
  "email_forward_address": "forward@piedpiper.com"
}

Body schema

Field	Type	Required	Description
email_forward_address	string	Yes	Forwarding email address. Use an empty string to remove the existing forwarding address. A non-empty value must be a valid email address

Request samples

Set email forwarding

cURL

curl --request PATCH \
  --url "https://api.woodpecker.co/rest/v2/domains/piedpiper.com/set_email_forwarding" \
  --header "x-api-key: {YOUR_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
    "email_forward_address": "forward@piedpiper.com"
  }'

Python

import requests

def set_email_forwarding(domain_name):
  url = f"https://api.woodpecker.co/rest/v2/domains/{domain_name}/set_email_forwarding"
  headers = {
    "x-api-key": "{YOUR_API_KEY}",
    "Content-Type": "application/json"
  }
  payload = {
    "email_forward_address": "forward@piedpiper.com"
  }

  response = requests.patch(url, headers=headers, json=payload)
  if response.status_code == 202:
    return f"Email forwarding update accepted: {response.status_code}"
  else:
    raise Exception(f"PATCH request failed: {response.status_code}, {response.text}")

if __name__ == "__main__":
  try:
    result = set_email_forwarding("piedpiper.com")
    print("PATCH response:", result)
  except Exception as e:
    print("Error:", e)

Java

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

public class WoodpeckerApiClient {
  public static void main(String[] args) {
    try {
      String domainName = "piedpiper.com";
      String url = "https://api.woodpecker.co/rest/v2/domains/" + domainName + "/set_email_forwarding";
      String jsonData = """
        {
          "email_forward_address": "forward@piedpiper.com"
        }
        """;

      HttpClient client = HttpClient.newHttpClient();
      HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create(url))
        .header("x-api-key", "{YOUR_API_KEY}")
        .header("Content-Type", "application/json")
        .method("PATCH", HttpRequest.BodyPublishers.ofString(jsonData))
        .build();

      HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
      if (response.statusCode() == 202) {
        System.out.println("PATCH response: Email forwarding update accepted: " + response.statusCode());
      } else {
        throw new Exception("PATCH request failed: " + response.statusCode() + ", " + response.body());
      }
    } catch (Exception e) {
      System.out.println("Error: " + e.getMessage());
    }
  }
}

Node.js

const axios = require('axios');

async function setEmailForwarding(domainName) {
  const url = `https://api.woodpecker.co/rest/v2/domains/${domainName}/set_email_forwarding`;
  const headers = {
    'x-api-key': '{YOUR_API_KEY}',
    'Content-Type': 'application/json'
  };
  const data = {
    email_forward_address: 'forward@piedpiper.com'
  };

  try {
    const response = await axios.patch(url, data, { headers });
    console.log('PATCH response:', `Email forwarding update accepted: ${response.status}`);
  } catch (error) {
    console.error('PATCH request failed:', error.response ? error.response.status : error.message);
  }
}

setEmailForwarding('piedpiper.com');

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',
  ],
]);

try {
  $domainName = 'piedpiper.com';
  $response = $client->patch("domains/{$domainName}/set_email_forwarding", [
    'json' => [
      'email_forward_address' => 'forward@piedpiper.com',
    ],
  ]);
  echo $response->getStatusCode(), "\n";
  echo $response->getBody(), "\n";
} catch (RequestException $e) {
  echo "Error: ", $e->getMessage(), "\n";
  if ($e->hasResponse()) {
    echo $e->getResponse()->getBody(), "\n";
  }
}

Response

Response examples

202

The email forwarding update has been accepted

400

Invalid request or malformed request syntax

{
  "title": "Bad Request",
  "status": 400,
  "details": "error details",
  "timestamp": "2026-05-06T12:00:00Z"
}

Body schema

Field	Type	Description
title	string	A short title describing the error
status	integer	The HTTP status code
details	string	A detailed message explaining the error
timestamp	string	The timestamp when the error occurred

401

Authentication failed. Please review the authentication guide

{
  "title": "Unauthorized",
  "status": 401,
  "details": "error details",
  "timestamp": "2026-05-06T12:00:00Z"
}

Body schema

Field	Type	Description
title	string	A short title describing the error
status	integer	The HTTP status code
details	string	A detailed message explaining the error
timestamp	string	The timestamp when the error occurred

404

The requested resource or path does not exist

{
  "title": "Not Found",
  "status": 404,
  "details": "error details",
  "timestamp": "2026-05-06T12:00:00Z"
}

Body schema

Field	Type	Description
title	string	A short title describing the error
status	integer	The HTTP status code
details	string	A detailed message explaining the error
timestamp	string	The timestamp when the error occurred

422

Returned when the request body is valid JSON but contains invalid or missing fields.

{
  "type": "validation_error",
  "message": "Invalid field(s)",
  "code": "invalid_fields",
  "request_id": "dc4faa0f-78bf-54e9-9d5d-ce9538f2eec5",
  "fields": [
    {
      "field": "email_forward_address",
      "issue": "required",
      "value": null
    }
  ]
}

Body schema

Field	Type	Description
type	string	Error type
message	string	Error message
code	string	Error code
request_id	string or null	Request identifier when available
fields	array	Fields that failed validation
└─ field	string	Field with a validation issue. Possible fields include domain_name and email_forward_address
└─ issue	string	Detailed description of the validation issue
└─ value	string/null	Rejected value, or null for a missing required field

500

Unexpected server error

{
  "title": "Internal Server Error",
  "status": 500,
  "details": "error details",
  "timestamp": "2026-05-06T12:00:00Z"
}

Body schema

Field	Type	Description
title	string	A short title describing the error
status	integer	The HTTP status code
details	string	A detailed message explaining the error
timestamp	string	The timestamp when the error occurred

503

Service unavailable or communication error

{
  "title": "Service Unavailable",
  "status": 503,
  "details": "error details",
  "timestamp": "2026-05-06T12:00:00Z"
}

Body schema

Field	Type	Description
title	string	A short title describing the error
status	integer	The HTTP status code
details	string	A detailed message explaining the error
timestamp	string	The timestamp when the error occurred