Mailbox connection batch status

Review the status of the submitted connection batch using the batch ID returned by rest/v2/mailboxes/manual_connection/bulk. This endpoint will provide an overview of the connection process and details about any potential issues.

Request

Endpoint

GET https://api.woodpecker.co/rest/v2/mailboxes/manual_connection/bulk/{batch_id}/summary

Headers

x-api-key: {YOUR_API_KEY}

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

Request sample

Retrieve batch summary

cURL

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

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();

HttpRequest request = HttpRequest.newBuilder()
  .uri(URI.create("https://api.woodpecker.co/rest/v2/mailboxes/manual_connection/bulk/{batch_id}/summary"))
  .header("x-api-key", "YOUR_API_KEY")
  .GET()
  .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

System.out.println("Status code: " + response.statusCode());
System.out.println("Response body: " + response.body());

Node.js

async function getBatchStatus() {
  try {
    const response = await fetch(
      "https://api.woodpecker.co/rest/v2/mailboxes/manual_connection/bulk/{batch_id}/summary",
      {
        headers: {
          "x-api-key": "YOUR_API_KEY",
        },
      }
    );

    const data = await response.json();
    console.log("Status:", response.status);
    console.log("Data:", data);
  } catch (error) {
    console.error("Error:", error.message);
  }
}

getBatchStatus();

Response

Response examples

200

Successful connection

An example response received when the processing has been finished and all mailboxes have been successfully connected.

{
  "processing_finished": true,
  "batch_size": 25,
  "pending_mailboxes_count": 0,
  "connected_mailboxes_count": 25,
  "conditionally_connected_mailboxes_count": 0,
  "failed_mailboxes_count": 0,
  "conditionally_connected_mailboxes": [],
  "failed_mailboxes": []
}

Body schema

Field	Type	Description
processing_finished	boolean	Indicates if the batch processing is complete
batch_size	integer	Total number of mailboxes submitted in the batch
pending_mailboxes_count	integer	Number of mailboxes still being processed
connected_mailboxes_count	integer	Number of successfully connected mailboxes
conditionally_connected_mailboxes_count	integer	Number of mailboxes connected conditionally (not included in connected_mailboxes_count)
failed_mailboxes_count	integer	Number of mailboxes that failed to connect
conditionally_connected_mailboxes	array	List of mailboxes connected conditionally
failed_mailboxes	array	List of mailboxes that failed to connect

Connection in progress

This response indicates that the processing is still ongoing. Mailboxes that failed to connect are listed in their respective arrays.

{
  "processing_finished": false,
  "batch_size": 100,
  "pending_mailboxes_count": 20,
  "connected_mailboxes_count": 75,
  "conditionally_connected_mailboxes_count": 1,
  "failed_mailboxes_count": 4,
  "conditionally_connected_mailboxes": [
    {
      "connection_request_id": 12345,
      "smtp_email": "john@conditional.co",
      "smtp_login": "john@conditional.co",
      "imap_email": "peter@conditional.co"
    }
  ],
  "failed_mailboxes": [
    {
      "connection_request_id": 12346,
      "smtp_email": "jared.dunn@piedpiper.com",
      "smtp_login": "jared.dunn@piedpiper.com",
      "imap_email": "jared.dunn@piedpiper.com",
      "error_message": "SMTP account already connected"
    },
    {
      "connection_request_id": 12347,
      "smtp_email": "jared@piedpiper.com",
      "smtp_login": "jared@piedpiper.com",
      "imap_email": "jared@piedpiper.com",
      "error_message": "Cannot connect to SMTP server"
    },
    {
      "connection_request_id": 12348,
      "smtp_email": "jared@getpiedpiper.com",
      "smtp_login": "jared@getpiedpiper.com",
      "imap_email": "jared@getpiedpiper.com",
      "error_message": "Unknown SMTP error"
    },
    {
      "connection_request_id": 12349,
      "smtp_email": "jdunn@piedpiper.com",
      "smtp_login": "jdunn@piedpiper.com",
      "imap_email": "jdunn@piedpiper.com",
      "error_message": "Unknown error"
    }
  ]
}

Body schema

Field	Type	Description
processing_finished	boolean	Indicates if the batch processing is complete
batch_size	integer	Total number of mailboxes submitted in the batch
pending_mailboxes_count	integer	Number of mailboxes still being processed
connected_mailboxes_count	integer	Number of successfully connected mailboxes
conditionally_connected_mailboxes_count	integer	Number of mailboxes connected conditionally (not included in connected_mailboxes_count)
failed_mailboxes_count	integer	Number of mailboxes that failed to connect
conditionally_connected_mailboxes	array	List of conditionally connected mailboxes
└─ connection_request_id	integer	Unique identifier of the connection request
└─ smtp_email	string	SMTP email address of the conditionally connected mailbox
└─ smtp_login	string	SMTP login of the conditionally connected mailbox
└─ imap_email	string	IMAP email address of the conditionally connected mailbox
failed_mailboxes	array	List of mailboxes that failed to connect
└─ connection_request_id	integer	Unique identifier of the connection request
└─ smtp_email	string	SMTP email address of the mailbox that couldn't connect
└─ smtp_login	string	SMTP login of the mailbox that couldn't connect
└─ imap_email	string	IMAP email address of the mailbox that couldn't connect
└─ error_message	string	Connection error message. If possible, the response will indicate whether the issue is related to SMTP or IMAP connection

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

Batch not found. Please review the batch ID.

{
  "code": "BATCH_NOT_FOUND",
  "details": null
}

Body schema

Field	Type	Description
code	string	Error code BATCH_NOT_FOUND
details	string/null	Additional information

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