Add Microsoft mailboxes in bulk

Connect one or more Microsoft mailboxes with Microsoft Graph app-only authentication. Use a credential_id from List credentials, or omit it only when your account has exactly one valid Microsoft Graph credential.

Request

Endpoint

POST https://api.woodpecker.co/rest/v2/mailboxes/microsoft/bulk

Headers

x-api-key: {YOUR_API_KEY}
Content-Type: application/json

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

Body

{
  "auth_type": "APP_ONLY",
  "credential_id": 22334455,
  "accounts": [
    {
      "mailbox_email": "jim@example.com",
      "display_name": "Jimothy H"
    },
    {
      "mailbox_email": "michael@example.com",
      "display_name": "Michael Scarn"
    }
  ]
}

Body schema

Field	Type	Required	Description
auth_type	string	No	Authentication type. Defaults to APP_ONLY; only APP_ONLY is supported
credential_id	integer	No	Microsoft Graph credential ID. Can be ommited only when your account has exactly one valid Microsoft Graph credential
accounts	array	Yes	Microsoft mailboxes to connect
└─mailbox_email	string	Yes	Mailbox email address
└─display_name	string	No	Display name used for the mailbox

Request samples

Connect Microsoft mailboxes

cURL

curl --request POST \
  --url "https://api.woodpecker.co/rest/v2/mailboxes/microsoft/bulk" \
  --header "x-api-key: {YOUR_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
    "auth_type": "APP_ONLY",
    "credential_id": 22334455,
    "accounts": [
      {
        "mailbox_email": "jim@example.com",
        "display_name": "Jimothy H"
      },
      {
        "mailbox_email": "michael@example.com",
        "display_name": "Michael Scarn"
      }
    ]
  }'

Python

import requests

def connect_microsoft_mailboxes():
  url = "https://api.woodpecker.co/rest/v2/mailboxes/microsoft/bulk"
  headers = {
    "x-api-key": "{YOUR_API_KEY}",
    "Content-Type": "application/json",
  }
  payload = {
    "auth_type": "APP_ONLY",
    "credential_id": 22334455,
    "accounts": [
        {
          "mailbox_email": "jim@example.com",
          "display_name": "Jimothy H",
        },
        {
          "mailbox_email": "michael@example.com",
          "display_name": "Michael Scarn",
        },
    ],
  }

  response = requests.post(url, headers=headers, json=payload)

  if response.status_code == 201:
    print(response.json())
  else:
    print("Request failed:", response.status_code, response.text)

if __name__ == "__main__":
    connect_microsoft_mailboxes()

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

  public static void connectMicrosoftMailboxes() {
    try {
      String url = "https://api.woodpecker.co/rest/v2/mailboxes/microsoft/bulk";
      String jsonData = """
        {
          "auth_type": "APP_ONLY",
          "credential_id": 22334455,
          "accounts": [
            {
              "mailbox_email": "jim@example.com",
              "display_name": "Jimothy H"
            },
            {
              "mailbox_email": "michael@example.com",
              "display_name": "Michael Scarn"
            }
          ]
        }
        """;

      HttpClient client = HttpClient.newHttpClient();
      HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create(url))
        .header("x-api-key", API_KEY)
        .header("Content-Type", "application/json")
        .POST(HttpRequest.BodyPublishers.ofString(jsonData))
        .build();

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

      if (response.statusCode() == 201) {
        System.out.println(response.body());
      } else {
        System.err.println("Request failed: " + response.statusCode());
      }
    } catch (Exception e) {
      e.printStackTrace();
    }
  }
}

Node.js

const axios = require("axios");

async function connectMicrosoftMailboxes() {
  const url = "https://api.woodpecker.co/rest/v2/mailboxes/microsoft/bulk";
  const headers = {
    "x-api-key": "{YOUR_API_KEY}",
    "Content-Type": "application/json"
  };
  const data = {
    auth_type: "APP_ONLY",
    credential_id: 22334455,
    accounts: [
      {
        mailbox_email: "jim@example.com",
        display_name: "Jimothy H"
      },
      {
        mailbox_email: "michael@example.com",
        display_name: "Michael Scarn"
      }
    ]
  };

  try {
    const response = await axios.post(url, data, { headers });

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

connectMicrosoftMailboxes();

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'),
    'Content-Type'  => 'application/json',
  ],
]);

try {
  $response = $client->post('mailboxes/microsoft/bulk', [
    'json' => [
      'auth_type'     => 'APP_ONLY',
      'credential_id' => 22334455,
      'accounts'      => [
          [
            'mailbox_email' => 'jim@example.com',
            'display_name'  => 'Jimothy H',
          ],
          [
            'mailbox_email' => 'michael@example.com',
            'display_name'  => 'Michael Scarn',
          ],
      ],
    ],
  ]);
  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

201

All submitted mailboxes were connected.

[
  {
    "success": true,
    "id": 444444,
    "email": "jim@example.com",
    "name": "Jimothy H",
    "deliverability": {
      "spf_correct": true,
      "dkim_correct": true
    },
    "error": null
  }
]

Body schema

Field	Type	Description
success	boolean	Whether the mailbox was connected
id	integer	Connected mailbox ID
email	string	Mailbox email address
name	string/null	Mailbox display name
deliverability	object	Deliverability check result
└─spf_correct	boolean	Whether SPF is configured correctly
└─dkim_correct	boolean	Whether DKIM is configured correctly
error	string/null	Per-mailbox error code

207

At least one mailbox could not be connected. Check each response item to see which mailboxes succeeded.

[
  {
    "success": true,
    "id": 444444,
    "email": "jim@example.com",
    "name": "Jimothy H",
    "deliverability": {
      "spf_correct": true,
      "dkim_correct": true
    },
    "error": null
  },
  {
    "success": false,
    "id": null,
    "email": "michael@example.com",
    "name": "Michael Scarn",
    "deliverability": null,
    "error": "WRONG_ALIAS"
  }
]

Body schema

Field	Type	Description
success	boolean	Whether the mailbox was connected
id	integer/null	Connected mailbox ID, or null when the mailbox failed
email	string	Mailbox email address
name	string/null	Mailbox display name
deliverability	object/null	Deliverability check result, or null when the mailbox failed
└─spf_correct	boolean	Whether SPF is configured correctly
└─dkim_correct	boolean	Whether DKIM is configured correctly
error	string/null	Per-mailbox error code

400

Invalid or empty JSON request body.

Status: 400
Body: none

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

422

Unprocessable Entity. The submitted mailbox batch cannot be processed.

{
  "message": "INVALID_CREDENTIAL_ID"
}

Body schema

Field	Type	Description
message	string	Validation error code. Possible values: UNSUPPORTED_AUTH_TYPE - auth_type is not supported MISSING_CREDENTIAL_ID - credential_id is required for this request MULTIPLE_VALID_CREDENTIALS - more than one valid credential exists, so credential_id must be provided INVALID_CREDENTIAL_ID - the provided credential does not exist or cannot be used MISSING_ACCOUNTS - the accounts array is missing or empty INVALID_MAILBOX_EMAIL - at least one submitted mailbox email is invalid

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