Get a list of mailboxes

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

You can also retrieve information about one specific IMAP or SMTP using their IDs and the /mailboxes/id endpoint.

Request

Endpoint

GET https://api.woodpecker.co/rest/v2/mailboxes

Headers

x-api-key: {YOUR_API_KEY}

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

Request sample

Some sample request

cURL

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

Python

import requests

def getAllMailboxes():
  url = "https://api.woodpecker.co/rest/v2/mailboxes"
  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__":
  getAllMailboxes()

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) {
    getAllMailboxes();
  }

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

      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 getAllMailboxes() {
  const url = "https://api.woodpecker.co/rest/v2/mailboxes";
  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);
  }
}

getAllMailboxes();

Response

Response examples

200

Successful response. The below example showcases 3 separate mailboxes using 3 different email service providers.

If your account doesn't have any mailboxes connected, the response will be an empty array.

[
  {
    "id": 123456,
    "type": "SMTP",
    "details": {
      "email": "jared.dunn@piedpiper.com",
      "provider": "GOOGLE",
      "login": "jared.dunn@piedpiper.com",
      "server": "smtp.gmail.com",
      "port": null,
      "from_name": "Jared Dunn",
      "error": null,
      "daily_limit": 50,
      "sent_today": 20,
      "frequency_from": 150000,
      "frequency_to": 600000,
      "bcc_crm": "",
      "signature": "<div>Email signature wrapped in HTML.</div>",
      "open_url": "sub.piedpiper.com",
      "click_url": "sub.piedpiper.com",
      "unsubscribe_url": "sub.piedpiper.com",
      "freeze_account": [],
      "in_slot": true,
      "warmup_data": {
          "status": "PAUSED"
      },
      "imap_id": 123457
    }
  },
  {
    "id": 123457,
    "type": "IMAP",
    "details": {
      "email": "jared.dunn@piedpiper.com",
      "provider": "GOOGLE",
      "login": "jared.dunn@piedpiper.com",
      "server": "imap.gmail.com",
      "port": null,
      "private": true
    }
  },
  {
    "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
    }
  },
  {
    "id": 456790,
    "type": "IMAP",
    "details": {
      "email": "jared@getpiedpiper.com",
      "provider": "CUSTOM",
      "login": "jared@getpiedpiper.com",
      "server": "mail.privateemail.com",
      "port": 993,
      "private": false
    }
  },
  {
    "id": 987654,
    "type": "SMTP",
    "details": {
      "email": "erlich@usebachmanity.com",
      "provider": "OFFICE",
      "login": "erlich@usebachmanity.com",
      "server": "api",
      "port": null,
      "from_name": "Erlich Bachman",
      "error": null,
      "daily_limit": 30,
      "sent_today": 15,
      "frequency_from": 50000,
      "frequency_to": 800000,
      "bcc_crm": "",
      "signature": "<div>Erlich Bachman</div><div>Bachmanity</div>",
      "open_url": "email.usebachmanity.com",
      "click_url": "email.usebachmanity.com",
      "unsubscribe_url": "email.usebachmanity.com",
      "freeze_account": [
          {
              "date_from": "2025-05-01T00:00:00+0100",
              "date_to": "2025-05-01T23:59:59+0100"
          }
      ],
      "in_slot": true,
      "warmup_data": {
          "status": "DISABLED"
      },
      "imap_id": 987655
    }
  },
  {
    "id": 987655,
    "type": "IMAP",
    "details": {
      "email": "erlich@usebachmanity.com",
      "provider": "OFFICE",
      "login": "erlich@usebachmanity.com",
      "server": null,
      "port": null,
      "private": false
    }
  }
]

Body schema

Each object includes details for either SMTP or IMAP. While both types share the same fields, the SMTP includes additional information. Below is a breakdown of the body schemas for both types.

SMTP

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

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