Skip to main content

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 --request GET \
  --url "https://api.woodpecker.co/rest/v2/mailboxes" \
  --header "x-api-key: {YOUR_API_KEY}"

Response​

Response examples​

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.

FieldTypeDescription
idintegerUnique identifier of an SMTP configuration
typestringConfiguration type: SMTP or IMAP
└─detailsobjectObject containing all mailbox details
└─details.emailstringEmail address
└─details.providerstringEmail provider of the mailbox
└─details.loginstringEmail login
└─details.serverstringSMTP server
└─details.portinteger/nullSMTP port. Optional field, can be null
└─details.from_namestringDisplay name for SMTP sender
└─details.errorstring/nullError message if one occurs
└─details.daily_limitintegerMaximum daily email sending limit
└─details.sent_todayintegerEmails sent in the last 24 hours
└─details.frequency_fromintegerMinimum delay between sending messages (ms)
└─details.frequency_tointegerMaximum delay between sending messages (ms)
└─details.bcc_crmstringBCC email for CRM integration
└─details.signaturestringHTML email signature
└─details.open_urlstringTracking domain for email opens
└─details.click_urlstringTracking domain for link clicks
└─details.unsubscribe_urlstringTracking domain for unsubscribe links
└─details.freeze_accountarrayArray of JSON objects containing scheduled pauses in sending -date_from and date_to, ISO 8601 format
└─details.in_slotbooleanDeprecated
└─details.warmup_dataobjectEmail warm-up configuration
└─details.warmup_data.statusstringWarm-up status: RUNNING, PAUSED, DISABLED, BLOCKED
└─details.imap_idintegerReference to linked IMAP configuration. One IMAP can be assigned to multiple SMTPs