Get a mailbox

Retrieve a configuration of a specific email account connected to your account. Each object contains details of a specific SMTP or IMAP and information about the connection settings, errors, sending limits, warm-up status and freeze dates, etc.

You can also retrieve a list of all mailboxes under your account using the /mailboxes endpoint.

Request

Endpoint

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

Headers

x-api-key: {YOUR_API_KEY}

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

Request samples

Retrieve a mailbox

cURL

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

Python

import requests

def getMailboxById(mailbox_id):
  url = f"https://api.woodpecker.co/rest/v2/mailboxes/{mailbox_id}"
  headers = {
    "x-api-key": "{YOUR_API_KEY}"
  }

  response = requests.get(url, headers=headers)

  if response.status_code == 200:
    print("GET successful:", response.json())
  else:
    print("GET failed with status:", response.status_code)

if __name__ == "__main__":
  getMailboxById(9876)  # Example mailbox ID

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) {
    int mailboxId = 9876; // Example mailbox ID
    getMailboxById(mailboxId);
  }

  public static void getMailboxById(int mailboxId) {
    try {
      String url = "https://api.woodpecker.co/rest/v2/mailboxes/" + mailboxId;

      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 getMailboxById(mailboxId) {
  const url = `https://api.woodpecker.co/rest/v2/mailboxes/${mailboxId}`;
  const headers = {
    "x-api-key": "{YOUR_API_KEY}"
  };

  try {
    const response = await axios.get(url, { headers: headers });

    if (response.status === 200) {
      console.log("GET successful:", response.data);
    } else {
      console.error("GET failed with status:", response.status);
    }
  } catch (error) {
    console.error("Request error:", error.response?.status || error.message);
  }
}

getMailboxById(9876); // Example mailbox ID

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

$mailboxId = '{id}';

try {
  $response = $client->get("mailboxes/{$mailboxId}");
  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. Each response provides details for either SMTP or IMAP. Although both types share the same fields, the SMTP response includes additional information. The example below illustrates a response for SMTP along with its corresponding IMAP, and it includes a breakdown of the body schemas for both types.

SMTP

{
  "id": 456789,
  "type": "SMTP",
  "details": {
    "email": "jared@getpiedpiper.com",
    "provider": "CUSTOM",
    "login": "jared@getpiedpiper.com",
    "server": "mail.privateemail.com",
    "port": 587,
    "from_name": "Jared from Pied Piper",
    "error": null,
    "daily_limit": 100,
    "sent_today": 0,
    "frequency_from": 300000,
    "frequency_to": 600000,
    "bcc_crm": "mycrm@pipedrivemail.com",
    "signature": "<div>Jered Dunn</div><div>Pied Pieper</div>",
    "open_url": "mail.getpiedpiper.com",
    "click_url": "mail.getpiedpiper.com",
    "unsubscribe_url": "mail.getpiedpiper.com",
    "freeze_account": [],
    "in_slot": true,
    "warmup_data": {
        "status": "RUNNING"
    },
    "imap_id": 456790,
    "reconnect_required": false
  }
}

Body schema

Field	Type	Description
id	integer	Unique identifier of an SMTP configuration
type	string	Configuration type: SMTP or IMAP
details	object	Object containing all mailbox details
└─details.email	string	Email address
└─details.provider	string	Email provider of the mailbox
└─details.login	string	Email login
└─details.server	string	SMTP server
└─details.port	integer/null	SMTP port. Optional field, can be null
└─details.from_name	string	Display name for SMTP sender
└─details.error	string/null	Mailbox error message. For SMTP, this can describe an SMTP problem or an IMAP problem affecting this SMTP. Returns null when the mailbox is connected without issues
└─details.daily_limit	integer	Maximum daily email sending limit
└─details.sent_today	integer	Emails sent in the last 24 hours
└─details.frequency_from	integer	Minimum delay between sending messages (ms)
└─details.frequency_to	integer	Maximum delay between sending messages (ms)
└─details.bcc_crm	string	BCC email for CRM integration
└─details.signature	string	Email signature in HTML format
└─details.open_url	string	Tracking domain for email opens
└─details.click_url	string	Tracking domain for link clicks
└─details.unsubscribe_url	string	Tracking domain for unsubscribe links
└─details.freeze_account	array	Array of JSON objects containing scheduled pauses in sending -date_from and date_to, ISO 8601 format
└─details.in_slot	boolean	Deprecated
└─details.warmup_data	object	Email warm-up configuration
└─details.warmup_data.status	string	Warm-up status: RUNNING, PAUSED, DISABLED, BLOCKED
└─details.imap_id	integer	Reference to linked IMAP configuration. One IMAP can be assigned to multiple SMTPs
└─details.reconnect_required	boolean	Whether the returned error requires reconnecting the mailbox. Returns false when reconnecting is not required or there is no mailbox error

IMAP

{
  "id": 456790,
  "type": "IMAP",
  "details": {
    "email": "jared@getpiedpiper.com",
    "provider": "CUSTOM",
    "login": "jared@getpiedpiper.com",
    "server": "mail.privateemail.com",
    "port": 993,
    "error": null,
    "private": false
  }
}

Body schema

Field	Type	Description
id	integer	Unique identifier of an IMAP configuration
type	string	Configuration type: SMTP or IMAP
└─details	object	Object containing all mailbox details
└─details.email	string	Email address
└─details.provider	string	Email provider of the mailbox
└─details.login	string	Email login
└─details.server	string	IMAP server
└─details.port	integer/null	IMAP port. Optional field, can be null
└─details.error	string/null	IMAP error message. Returns null when the IMAP is connected without issues
└─details.private	boolean	Privacy setting indicating whether Woodpecker downloads all emails or emails related to campaigns

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

Unexpected 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