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, 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 sample

Retrieve a mailbox

cURL

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

Java

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;

public class WoodpeckerApiClient {
  public static void main(String[] args) {
    String apiKey = "YOUR_API_KEY"; // Replace with your actual API key
    String endpoint = "https://api.woodpecker.co/rest/v2/mailboxes/{id}"; 

    try {
      URL url = new URL(endpoint);
      HttpURLConnection connection = (HttpURLConnection) url.openConnection();
      connection.setRequestMethod("GET");
      connection.setRequestProperty("x-api-key", apiKey);

      int responseCode = connection.getResponseCode();
      if (responseCode == HttpURLConnection.HTTP_OK) {
        BufferedReader in = new BufferedReader(new InputStreamReader(connection.getInputStream()));
        String inputLine;
        StringBuilder response = new StringBuilder();

        while ((inputLine = in.readLine()) != null) {
          response.append(inputLine);
        }
        in.close();

        System.out.println("Response: " + response.toString());
      } else {
        System.out.println("GET request failed with response code: " + responseCode);
      }

      connection.disconnect();
    } catch (Exception e) {
      e.printStackTrace();
    }
  }
}

Node.js

const axios = require("axios");

const apiKey = "YOUR_API_KEY";
const url = "https://api.woodpecker.co/rest/v2/mailboxes/{id}";

axios
  .get(url, {
    headers: {
      "x-api-key": apiKey,
    },
  })
  .then((response) => {
    console.log("Response:", response.data);
  })
  .catch((error) => {
    console.error("Error:", error.response ? error.response.data : error.message);
  });

Response

Response examples

200

Successful response. 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
  }
}

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	Error message if one occurs
└─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	HTML email signature
└─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

IMAP

{
  "id": 456790,
  "type": "IMAP",
  "details": {
    "email": "jared@getpiedpiper.com",
    "provider": "CUSTOM",
    "login": "jared@getpiedpiper.com",
    "server": "mail.privateemail.com",
    "port": 993,
    "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.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

Unknown 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