List domain mailboxes

Retrieve active mailboxes for a purchased domain, including basic mailbox information. For credentials and connection settings, use the get domain mailbox endpoint.

Request

Endpoint

GET https://api.woodpecker.co/rest/v2/domains/{domain_name}/mailboxes

Headers

x-api-key: {YOUR_API_KEY}

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

Parameters

Parameter	Required	Type	Description
domain_name	Yes	string	Full domain name

Request samples

List mailboxes

cURL

curl --request GET \
  --url "https://api.woodpecker.co/rest/v2/domains/piedpiper.com/mailboxes" \
  --header "x-api-key: {YOUR_API_KEY}"

Python

import requests

def list_domain_mailboxes(domain_name):
  url = f"https://api.woodpecker.co/rest/v2/domains/{domain_name}/mailboxes"
  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 = list_domain_mailboxes("piedpiper.com")
    print("GET response:", data)
  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 + "/mailboxes";

      HttpClient client = HttpClient.newHttpClient();
      HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create(url))
        .header("x-api-key", "{YOUR_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 {
        throw new Exception("GET request failed: " + response.statusCode() + ", " + response.body());
      }
    } catch (Exception e) {
      System.out.println("Error: " + e.getMessage());
    }
  }
}

Node.js

const axios = require('axios');

async function listDomainMailboxes(domainName) {
  const url = `https://api.woodpecker.co/rest/v2/domains/${domainName}/mailboxes`;
  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);
  }
}

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

try {
  $domainName = 'piedpiper.com';
  $response = $client->get("domains/{$domainName}/mailboxes");
  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

200

Request processed successfully. If there are no mailboxes under this domain, mailboxes will be an empty array.

{
  "mailboxes": [
    {
      "first_name": "Richard",
      "last_name": "Hendricks",
      "email": "richard@piedpiper.com",
      "provider": "GOOGLE",
      "status": "PAID"
    }
  ]
}

Body schema

Field	Type	Description
mailboxes	array	Mailboxes on the domain
└─ first_name	string	Mailbox owner's first name
└─ last_name	string	Mailbox owner's last name
└─ email	string	Mailbox email address
└─ provider	string	Public provider name
└─ status	string	Mailbox status. Possible values are ORDERED and PAID

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 domain was not found, belongs to another account, or is deleted. The response body is empty

422

Returned when the request has invalid or missing parameters.

{
  "type": "validation_error",
  "message": "Invalid field(s)",
  "code": "invalid_fields",
  "request_id": "dc4faa0f-78bf-54e9-9d5d-ce9538f2eec5",
  "fields": [
    {
      "field": "domain_name",
      "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
└─ 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