Reply to a message

This endpoint allows you to reply to a message retrieved from the Woodpecker inbox.

You can define the reply content, subject, recipients, and whether the original inbox message should be quoted below your reply. By default, the reply will be sent from the same mailbox that received the original message, but you can specify a different connected SMTP mailbox.

Woodpecker automatically includes standard email reply threading headers, so the reply is sent in the same conversation thread.

Set quote_original_message to true to include the original message as a quotation in the sent email. This helps the recipient see their previous reply directly in the conversation.

tip

Responding to a message automatically marks the received response as 'read' in the inbox

Request

Endpoint

POST https://api.woodpecker.co/rest/v2/inbox/messages/{id}/reply

Headers

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

Parameters

Parameter	Required	Type	Description
id	Yes	integer	Path parameter - ID of the prospect's response that will be replied to

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

Body

{
  "mailbox_id": 123456,
  "to": "recipient@gmail.com",
  "cc": "cc1@gmail.com,cc2@gmail.com",
  "bcc": "bcc1@gmail.com,bcc2@gmail.com",
  "subject": "Re: Example subject",
  "body": {
    "html": "<p>Example response here</p>"
  },
  "quote_original_message": true
}

Body schema

Field	Required	Type	Description
mailbox_id	No	integer	Defaults to the mailbox that received the original message. When specified, identifies the SMTP ID of a mailbox used to send the reply. Use /mailboxes endpoint to fetch mailbox details
to	No	string	By default, the reply will be sent to the original author of the message. If provided, this field specifies the recipient's email addresses
cc	No	string	Comma-separated list of email addresses to include in CC
bcc	No	string	Comma-separated list of email addresses to include in BCC. If not provided, the BCC addresses configured in the mailbox settings (if any) will be used
subject	No	string	Subject of the reply message. If not provided, the subject of the original message will be used, prefixed with Re: if not already present
body	Yes	object	Object containing the message content
└─ html	Yes	string	Content of the response email in HTML format
quote_original_message	No	boolean	When true, includes the original inbox message as a quotation in the sent email. Default: false

Request samples

Reply to a message

cURL

curl --request POST \
  --url "https://api.woodpecker.co/rest/v2/inbox/messages/{id}/reply" \
  --header "x-api-key: {YOUR_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
    "body": {
      "html": "<p>Example response here</p>"
    },
    "quote_original_message": true
  }'

Python

import requests

def reply_to_message():
  url = "https://api.woodpecker.co/rest/v2/inbox/messages/{id}/reply"
  headers = {
    "x-api-key": "{YOUR_API_KEY}",
    "Content-Type": "application/json"
  }
  payload = {
    "body": {
      "html": "<p>Example response here</p>"
    },
    "quote_original_message": True
  }

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

if __name__ == "__main__":
  reply_to_message()

Java

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

public class WoodpeckerApiClient {
  public static void main(String[] args) {
    try {
      String url = "https://api.woodpecker.co/rest/v2/inbox/messages/{id}/reply";
      String json = """
        {
          "body": {
            "html": "<p>Example response here</p>"
          },
          "quote_original_message": true
        }
        """;

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

      HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
      if (response.statusCode() == 200) {
        System.out.println("POST response: " + response.body());
      } else {
        throw new Exception("POST request failed: " + response.statusCode() + ", " + response.body());
      }
    } catch (Exception e) {
      System.out.println("Error: " + e.getMessage());
    }
  }
}

Node.js

const axios = require('axios');

async function replyToMessage() {
  const url = 'https://api.woodpecker.co/rest/v2/inbox/messages/{id}/reply';
  const headers = {
    'x-api-key': '{YOUR_API_KEY}',
    'Content-Type': 'application/json'
  };
  const data = {
    body: {
      html: '<p>Example response here</p>'
    },
    quote_original_message: true
  };

  try {
    const response = await axios.post(url, data, { headers });
    if (response.status === 200) {
      console.log('POST response:', response.data);
    } else {
      throw new Error(`POST request failed: ${response.status}, ${response.data}`);
    }
  } catch (error) {
    console.error('Error:', error.response ? error.response.status : error.message);
  }
}

replyToMessage();

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

$messageId = '{id}';

try {
  $response = $client->post("inbox/messages/{$messageId}/reply", [
    'json' => [
      'body' => [
        'html' => '<p>Example response here</p>',
      ],
      'quote_original_message' => true,
    ],
  ]);
  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

Message passed to SMTP for delivery

Status: 200
Body: none

400

Invalid request or malformed request syntax. Example messages are provided below; other variations are also possible

{
  "title": "Bad Request",
  "status": 400,
  "detail": "Invalid request body" | "Bcc emails if provided must contain comma-separated valid email addresses" | "Recipient email if provided must be valid email address",
  "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

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

The requested mailbox does not exist, or the request URL is incorrect.

{
  "title": "Not Found",
  "status": 404,
  "detail": "Mailbox not found" | "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

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