Update mailbox

Update the signature of an SMTP email account connected to your account. The signature is added to emails sent from this mailbox.

Request

Endpoint

PATCH https://api.woodpecker.co/rest/v2/mailboxes/{smtp_mailbox_id}

You can update an email account using the SMTP email account ID. Use the /mailboxes endpoint to retrieve a list of your SMTP IDs.

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

The request body contains the mailbox signature to update. Use the footer field to provide the signature HTML.

{
  "footer": "<div>Best regards,</div><div>John</div>"
}

Body schema

Field	Type	Required	Description
footer	string	Yes	Signature of the email account in HTML format. Use null or an empty string to remove the footer. Supports the {{UNSUBSCRIBE}} snippet, which generates an unsubscribe link. Remember to wrap it in an <a href> tag

Request samples

Update a mailbox

cURL

curl --request PATCH \
  --url "https://api.woodpecker.co/rest/v2/mailboxes/{smtp_mailbox_id}" \
  --header "x-api-key: {YOUR_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
    "footer": "<div>Best regards,</div><div>John</div>"
  }'

Python

import requests

def update_mailbox(smtp_mailbox_id):
  url = f"https://api.woodpecker.co/rest/v2/mailboxes/{smtp_mailbox_id}"
  headers = {
    "x-api-key": "{YOUR_API_KEY}",
    "Content-Type": "application/json"
  }
  payload =  {
    "footer": "<div>Best regards,</div><div>John</div>"
  }

  try:
    response = requests.patch(url, headers=headers, json=payload)
    if response.status_code == 200:
      print("PATCH response:", response.json())
    else:
      raise Exception(f"PATCH request failed: {response.status_code}, {response.text}")
  except Exception as e:
    print("Error:", e)

if __name__ == "__main__":
  mailbox_id = 9876
  update_mailbox(mailbox_id)

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) {
    int smtpMailboxId = 9876;
    updateMailboxById(smtpMailboxId);
  }

  private static void updateMailboxById(int smtpMailboxId) {
    String endpoint = "https://api.woodpecker.co/rest/v2/mailboxes/" + smtpMailboxId;

    String jsonInputString = "{"
      + "\"footer\": \"<div>Best regards,</div><div>John</div>\""
      + "}";

    try {
      HttpClient client = HttpClient.newHttpClient();
      HttpRequest request = HttpRequest.newBuilder()
        .uri(new URI(endpoint))
        .header("x-api-key", API_KEY)
        .method("PATCH", HttpRequest.BodyPublishers.ofString(jsonInputString))
        .build();

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

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

Node.js

const axios = require("axios");

async function updateMailboxById(smtpMailboxId) {
  const apiKey = "YOUR_API_KEY";
  const url = `https://api.woodpecker.co/rest/v2/mailboxes/${smtpMailboxId}`;

  const data = {
    "footer": "<div>Best regards,</div><div>John</div>"
  };

  try {
    const response = await axios.patch(url, data, {
      headers: {
        "x-api-key": apiKey,
        "Content-Type": "application/json",
      },
    });

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

updateMailboxById(9876);

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',
  ],
]);

$smtpMailboxId = 9876;

try {
  $response = $client->patch("mailboxes/{$smtpMailboxId}", [
    'json' => [
      'footer' => '<div>Best regards,</div><div>John</div>'
    ]
  ]);
  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

200

Request processed successfully.

Status: 200
Body: None

400

Invalid request or malformed request syntax. Please review the request body and field requirements.

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

Body schema

Field	Type	Description
code	string	Error code
details	array[string]/null	Additional information

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

Mailbox not found. Use the /mailboxes endpoint to retrieve a list of your SMTP IDs.

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

Body schema

Field	Type	Description
code	string	Error code
details	array[string]/null	Additional information

422

Unprocessable request due to the provided IMAP ID. Please use an SMTP ID for this operation. Use the /mailboxes endpoint to retrieve a list of your SMTP IDs

{
  "code": "IMAP_NOT_ALLOWED",
  "details": ["Updating IMAP is not allowed"]
}

Body schema

Field	Type	Description
code	string	Error code
details	array[string]/null	Additional information

500

Unexpected error, please try again later

Status: 500
Body: none