Get domain mailbox

Retrieve details of a single mailbox under a purchased domain, including general mailbox information, credentials, and IMAP/SMTP settings. To get a list of all mailboxes under a domain, use the list domain mailboxes endpoint.

Request

Endpoint

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

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
mailbox_email	Yes	string	Mailbox email address. The mailbox must belong to the domain in domain_name. URL-encode it if your client does not encode path parameters automatically, for example richard%40piedpiper.com

Request samples

Get a mailbox

cURL

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

Python

import requests

def get_domain_mailbox(domain_name, mailbox_email):
  encoded_mailbox_email = requests.utils.quote(mailbox_email, safe="")
  url = f"https://api.woodpecker.co/rest/v2/domains/{domain_name}/mailboxes/{encoded_mailbox_email}"
  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_domain_mailbox("piedpiper.com", "richard@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;
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;

public class WoodpeckerApiClient {
  public static void main(String[] args) {
    try {
      String domainName = "piedpiper.com";
      String mailboxEmail = "richard@piedpiper.com";
      String encodedMailboxEmail = URLEncoder.encode(mailboxEmail, StandardCharsets.UTF_8);
      String url = "https://api.woodpecker.co/rest/v2/domains/" + domainName + "/mailboxes/" + encodedMailboxEmail;

      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 getDomainMailbox(domainName, mailboxEmail) {
  const encodedMailboxEmail = encodeURIComponent(mailboxEmail);
  const url = `https://api.woodpecker.co/rest/v2/domains/${domainName}/mailboxes/${encodedMailboxEmail}`;
  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);
  }
}

getDomainMailbox('piedpiper.com', 'richard@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';
  $mailboxEmail = rawurlencode('richard@piedpiper.com');
  $response = $client->get("domains/{$domainName}/mailboxes/{$mailboxEmail}");
  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

{
  "first_name": "Richard",
  "last_name": "Hendricks",
  "email": "richard@piedpiper.com",
  "login": "richard@piedpiper.com",
  "provider": "MAILDOSO",
  "status": "PAID",
  "authenticator": null,
  "smtp_server": "smtp.example.com",
  "smtp_password": "secret",
  "smtp_port": 587,
  "imap_server": "imap.example.com",
  "imap_email": "richard@piedpiper.com",
  "imap_password": "secret",
  "imap_port": 993,
  "created": "2026-06-24T10:00:00",
  "profile_picture": "https://avatars.example.com/users/40/avatar.png"
}

Body schema

Field	Type	Description
first_name	string	Mailbox display first name
last_name	string	Mailbox display last name
email	string	Mailbox email address
login	string	Login used for the mailbox
provider	string	Public provider name
status	string	Mailbox status. Possible values are ORDERED and PAID
authenticator	string or null	Current one-time authenticator code when available
smtp_server	string	SMTP server hostname
smtp_password	string	SMTP password
smtp_port	integer	SMTP port number
imap_server	string	IMAP server hostname
imap_email	string	IMAP email address
imap_password	string	IMAP password
imap_port	integer	IMAP port number
created	string	Mailbox creation timestamp
profile_picture	string or null	Profile picture URL

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

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": "mailbox_email",
      "issue": "domain_mismatch",
      "value": "richard@other-domain.com"
    }
  ]
}

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 mailbox_email
└─ 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