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.
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,
"include_mailbox_signature": true
}
Set include_mailbox_signature to true to append the sending mailbox's configured signature below your reply. The signature can be included independently of quote_original_message; when both are enabled, the quoted original message appears below the signature.
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 |
include_mailbox_signature | No | boolean | When true, appends the sending mailbox's signature if configured in Woodpecker account settings. Default: false; when omitted or false, no signature is appended |
Request samples
Reply to a message
The examples send a reply with the mailbox signature and the original message quoted below it. They use reply ID 123456 from the inbox response example.
- cURL
- Python
- Java
- Node.js
- PHP
curl --request POST \
--url "https://api.woodpecker.co/rest/v2/inbox/messages/123456/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,
"include_mailbox_signature": true
}'
import requests
def reply_to_message(reply_id):
url = f"https://api.woodpecker.co/rest/v2/inbox/messages/{reply_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,
"include_mailbox_signature": True
}
response = requests.post(url, headers=headers, json=payload)
if response.status_code == 200:
return "Reply passed to SMTP for delivery."
raise Exception(f"POST request failed: {response.status_code}, {response.text}")
if __name__ == "__main__":
try:
print(reply_to_message(123456))
except Exception as e:
print("Error:", e)
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/123456/reply";
String json = """
{
"body": {
"html": "<p>Example response here</p>"
},
"quote_original_message": true,
"include_mailbox_signature": 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("Reply passed to SMTP for delivery.");
} else {
throw new Exception("POST request failed: " + response.statusCode() + ", " + response.body());
}
} catch (Exception e) {
System.out.println("Error: " + e.getMessage());
}
}
}
const axios = require('axios');
async function replyToMessage(replyId) {
const url = `https://api.woodpecker.co/rest/v2/inbox/messages/${replyId}/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,
include_mailbox_signature: true
};
try {
const response = await axios.post(url, data, { headers });
if (response.status === 200) {
console.log('Reply passed to SMTP for delivery.');
} else {
throw new Error(`POST request failed: ${response.status}, ${response.data}`);
}
} catch (error) {
console.error('Error:', error.response ? error.response.status : error.message);
}
}
replyToMessage(123456);
<?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 = 123456;
try {
$response = $client->post("inbox/messages/{$messageId}/reply", [
'json' => [
'body' => [
'html' => '<p>Example response here</p>',
],
'quote_original_message' => true,
'include_mailbox_signature' => 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
- 400
- 401
- 404
- 422
- 500
Message passed to SMTP for delivery.
Status: 200
Body: none
Invalid request or malformed request syntax. Example message is provided below; other variations are also possible.
{
"title": "Bad Request",
"status": 400,
"detail": "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 |
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 |
The requested message or sending mailbox was not found, or the request URL is incorrect.
{
"title": "Not Found",
"status": 404,
"detail": "Mailbox not found",
"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 |
The reply could not be sent because of a problem with the SMTP mailbox.
{
"title": "Unprocessable Entity",
"status": 422,
"detail": "Problem with SMTP mailbox",
"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 |
An unexpected server error occurred. The response may be empty; handle the status without relying on a response body.
Status: 500
Body: none